> ## Documentation Index
> Fetch the complete documentation index at: https://docs.portkey.ai/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# SSO

> SSO support for enterprises

Portkey Control plane supports following authentication protocols for enterprise customers.

1. **OIDC** (OpenID Connect)
2. **SAML 2.0** (Security Assertion Markup Language)

Below are the steps to integrate your identity provider with our system.

<Info>
  **Auto-Provisioning**: First-time SSO users are automatically provisioned to your organization when they log in. If a user has a pending invite, it will be automatically accepted during their first SSO login.
</Info>

## Table of Contents

* [OIDC Integration](#oidc-integration)
* [SAML Integration](#saml-integration)

## OIDC Integration

For OIDC integration, we require the following information from your identity provider:

### Required Information

* **Issuer URL**: The URL of your identity provider's OIDC authorization endpoint. Wellknown OIDC configuration should be available at this URL.
* **Client ID**: The client ID provided by your identity provider.
* **Client Secret Key**: The client secret provided by your identity provider.

### Setup Steps

<Info>
  Following scopes are required for Portkey to work with OIDC:

  * openid
  * profile
  * email
  * offline\_access

  For airgapped deployments, you can configure additional custom OIDC scopes by setting the `OIDC_CUSTOM_SCOPES` environment variable (comma-separated list) on the backend service.
</Info>

#### General

* Create an OIDC application in your identity provider.
* Once the application is created, please note the following details:
  * `Issuer URL`
  * `Client Id`
  * `Client Secret`
* Update the above details in Portkey Control Plane in `Admin Settings > Authentication Settings > OIDC`.

#### Okta

* Go to `Applications` tab on Okta dashboard and `create a new app integration`.
* Select `OIDC - OpenID Connect` as the signin method.
* Select Application Type as `Web` Application
* On the next step, fill in the required fields. The `signin redirect URI` should be [https://app.portkey.ai/v2/auth/callback](https://app.portkey.ai/v2/auth/callback) and the `Grant Type` should have `Authorization code` and `Refresh Token` as checked
* Create Application
* After the application is created, go to the `General` section of the application.
* Click on the `edit` button for the General Settings section.
* Select `Either Okta or app` for the `Login initiated by` field.
* Add [https://app.portkey.ai/v2/auth/callback](https://app.portkey.ai/v2/auth/callback) as the `initiate login URI`
* Go to the `Sign On` section and click on `Edit`. Select `Okta Url` as the `issuer` and save the updated details
* Once everything is setup please note the following details
  * `Issuer URL` will be the `Issuer` from above step
  * `Client Id` would be same as `Audience`/ `Client ID`
  * `Client Secret` is needed for Web App based flow. It can be found under `General > Client Credentials > Client Secrets` in your Okta App.
* Update the above details in Portkey Control Plane in `Admin Settings > Authentication Settings > OIDC`

#### Azure AD

* Sign in to the Azure portal.
* Search for and select Azure Active Directory.
* Under Manage, select App registrations.
* Select New registration.
* Enter a name.
* Select one of the Supported account types that best reflects your organization requirements.
* Under `Redirect URI`,
  * Select `Web` as the platform
  * Enter [https://app.portkey.ai/v2/auth/callback](https://app.portkey.ai/v2/auth/callback) as redirect url
* Click on Register
* Once saved, go to `Certificates & secrets`
  * Click on `Client Secrets`
  * Click on `New client secret`
  * Use appropriate settings according to your organization
  * Click on `Add`
* Once everything is set up. Please go to `Overview`
  * Click on `Endpoints` and note the `OpenID Connect metadata document` url
  * Please note the `Application (client) ID` from `Essentials`
  * Please note the `Client Secret` from `Certificates & secrets`
* Update the above details in Portkey Control Plane in `Admin Settings > Authentication Settings > OIDC`

## SAML Integration

For SAML integration, we require the following information from your identity provider:

### Required Information

Either of the following information is required:

* **Provider Metadata URL**: The URL from your identity provider containing the metadata, including SAML configuration details.
* **Provider Metadata XML**: The XML metadata of your identity provider.

### Setup Steps

#### General

* Create an SAML application in your identity provider.
* Once the application is created, please note the following details:
  * `Provider Metadata URL`
  * `Provider Metadata XML`
* Update the above details in Portkey Control Plane in `Admin Settings > Authentication Settings > SAML`.

#### Okta

* Go to `Applications` tab on okta dashboard and `create a new app integration`.
* Select `SAML 2.0` as the signin method.
* In `Configure SAML`, update
  * `Single sign-on URL` with Saml redirect url. You can find the Saml redirect url from the `Admin Settings > Authentication Settings > SAML Redirect/Consumer Service URL` from Portkey Control Plane.
  * `Audience URI (SP Entity ID)` with SAML Entity ID from Portkey Control Plane.
* Create Application
* Once everything is set up, please note the following details
  * `Sign On tab > SAML 2.0 tab > Metadata details > Metadata URL`
* Update the above details in Portkey Control Plane in `Admin Settings > Authentication Settings > SAML`

#### Azure AD

* Sign in to the Azure portal.
* Search for and select Azure Active Directory.
* Under Manage, select App registrations.
* Select New registration.
* Enter a name.
* Select one of the Supported account types that best reflects your organization requirements.
* Under `Redirect URI`,
  * Select `Web` as the platform
  * Enter the `SAML Redirect/Consumer Service URL` from Portkey Control Plane as redirect url
* Select `Register`.
* Select `Endpoints` at the top of the page.
* Find the `Federation metadata document URL` and select the copy icon.
* In the left side panel, select `Expose an API`.
* To the right of `Application ID URI`, select `Add`.
  * Enter `SAML Entity ID` from Portkey Control Plane as the `App ID URI`.
* Select `Save`.
* Once everything is set up, please note the following details
  * Copy the `Federation metadata document URL` and paste it in Portkey Control Plane in `Admin Settings > Authentication Settings > SAML > Provider Metadata URL`

***

## Allowed Domains

In `Admin Settings > Authentication Settings`, you can configure **Allowed Domains** to restrict which email domains are permitted to authenticate with your organization. You can add one or more domains (e.g., `example.com`) to control access.

### Subdomain Support

You can enable the **`allow_subdomains`** flag on a root domain to automatically allow authentication from **all subdomains** under that root domain.

For example, if you add `example.com` as an allowed domain and enable `allow_subdomains`, users with emails from any subdomain like `dev.example.com`, `team.example.com`, or `us.example.com` will also be allowed to authenticate.

<Warning>
  The `allow_subdomains` flag can only be enabled on **root domains**. If you attempt to enable it on a subdomain (e.g., `dev.example.com`), the operation will fail and return an error. Always set this flag on the root domain instead.
</Warning>

| Configuration     | `allow_subdomains` | Allowed Emails                                                   |
| ----------------- | ------------------ | ---------------------------------------------------------------- |
| `example.com`     | Disabled           | Only `*@example.com`                                             |
| `example.com`     | Enabled            | `*@example.com`, `*@dev.example.com`, `*@team.example.com`, etc. |
| `dev.example.com` | Enabled            | **Error** — flag only works on root domains                      |
| `dev.example.com` | Disabled           | Only `*@dev.example.com`                                         |