> ## Documentation Index > Fetch the complete documentation index at: https://tyk.io/docs/llms.txt > Use this file to discover all available pages before exploring further. # SSO with Okta > Learn how to configure Single Sign-On (SSO) for Tyk Dashboard or Tyk Developer Portal using Okta, via OpenID Connect or SAML. ## Introduction [Okta](https://www.okta.com/) supports both [OpenID Connect (OIDC)](#sso-with-openid-connect) and [SAML 2.0](#sso-with-saml). * For most new deployments, OIDC is recommended as it is simpler to configure. * Use SAML if your organization requires it for policy or compatibility reasons. Before configuring your IdP and TIB profile, read [Dashboard SSO](https://tyk.io/docs/tyk-identity-broker/dashboard-sso.md) or [Portal SSO](https://tyk.io/docs/tyk-stack/tyk-developer-portal/enterprise-developer-portal/managing-access/enable-sso.md) to understand the `ActionType`, `ReturnURL`, and `IdentityHandlerConfig` fields required for your use case. This page covers the Okta-specific configuration only. ## SSO with OpenID Connect ### Configure Okta 1. Log in to your Okta Admin Console and navigate to **Applications > Applications**. 2. Click **Create App Integration**, select **OIDC - OpenID Connect** as the sign-in method and **Web Application** as the application type, then click **Next**. 3. Give the application a name. 4. Under **Sign-in redirect URIs**, add the TIB callback URL: ``` http://{tib-host}/auth/{profile-id}/openid-connect/callback ``` Replace `{tib-host}` with the hostname of your TIB instance and `{profile-id}` with the ID you will assign to the TIB profile. 5. Under **Assignments**, configure which users or groups can access the application. 6. Click **Save**. 7. From the application's **General** tab, note the **Client ID** and **Client Secret**. The Okta OIDC discovery URL for your org is: ``` https://{okta-domain}/.well-known/openid-configuration ``` Where `{okta-domain}` is your Okta org domain (for example, `your-org.okta.com`). If you are using a custom Authorization Server, the discovery URL is: ``` https://{okta-domain}/oauth2/{auth-server-id}/.well-known/openid-configuration ``` ### TIB Profile The Okta-specific configuration goes in the `ProviderConfig` block of the TIB profile. Set `ProviderName` to `SocialProvider` and `Type` to `redirect`. ```json expandable theme={null} { "ProviderName": "SocialProvider", "Type": "redirect", "ProviderConfig": { "CallbackBaseURL": "http://{tib-host}", "FailureRedirect": "http://{failure-redirect-url}", "UseProviders": [ { "Name": "openid-connect", "Key": "{okta-client-id}", "Secret": "{okta-client-secret}", "Scopes": ["openid", "email", "profile"], "DiscoverURL": "https://{okta-domain}/.well-known/openid-configuration" } ] } } ``` The Okta-specific `ProviderConfig` fields are: | Field | Description | | - | - | | `CallbackBaseURL` | The base URL of your TIB instance. TIB appends the callback path automatically. | | `FailureRedirect` | URL to redirect the user to on authentication failure. | | `UseProviders.Name` | Must be `openid-connect`. This value routes TIB to the OpenID Connect provider implementation. | | `UseProviders.Key` | The Okta Client ID. | | `UseProviders.Secret` | The Okta Client Secret. | | `UseProviders.Scopes` | OAuth scopes to request. `openid` and `email` are required. | | `UseProviders.DiscoverURL` | The Okta OIDC discovery URL for your org or Authorization Server. | #### JSON Web Encryption (JWE) If Okta is configured to encrypt ID tokens, TIB can decrypt them using JWE. Add a `JWE` block to `ProviderConfig` to enable this: ```json theme={null} { "ProviderConfig": { "UseProviders": [...], "JWE": { "Enabled": true, "PrivateKeyLocation": "{certificate-id-or-path}" } } } ``` For embedded TIB in Tyk Dashboard, set `PrivateKeyLocation` to the certificate ID from the Tyk Dashboard certificate manager. For standalone TIB, set it to the file path of a PEM file containing the private key. The key must correspond to the public key registered with Okta for token encryption. Requires Tyk Identity Broker v1.6.1+ and Tyk Dashboard v5.7.0+. ### Worked Examples (OIDC) These examples use embedded TIB, so the `CallbackBaseURL` is the same as the Dashboard or Portal respectively; TIB handles requests on the same host and port. > [tab] Dashboard SSO > > In this example, Tyk Dashboard is running at `http://dashboard.example.com` on port `3000`; replace the example values with your own. > > **Tyk Dashboard configuration** > > ```json theme={null} > { > "sso_enable_user_lookup": true, > "sso_permission_defaults": { > "apis": "write", > "keys": "write", > "policies": "write" > }, > "sso_default_group_id": "{tyk-user-group-id}" > } > ``` > > With this configuration, registered users (with a Tyk Dashboard user account) get their own permissions; unregistered users fall back to the group specified in `sso_default_group_id`. See [Dashboard SSO](https://tyk.io/docs/tyk-identity-broker/dashboard-sso.md) for full details. > > **TIB profile** > > The TIB profile is created via the [Tyk Identity Broker API](https://tyk.io/docs/tyk-identity-broker/tib-rest-api.md) or the [Tyk Dashboard UI](https://tyk.io/docs/tyk-identity-broker/dashboard-sso.md#create-a-tib-profile-using-dashboard-ui). > > ```json expandable theme={null} > { > "ID": "okta-dashboard-oidc", > "Name": "Okta Dashboard SSO (OIDC)", > "OrgID": "{tyk-org-id}", > "ActionType": "GenerateOrLoginUserProfile", > "Type": "redirect", > "ProviderName": "SocialProvider", > "ReturnURL": "http://dashboard.example.com:3000/tap", > "IdentityHandlerConfig": { > "DashboardCredential": "{tib-service-user-api-key}" > }, > "ProviderConfig": { > "CallbackBaseURL": "http://dashboard.example.com:3000", > "FailureRedirect": "http://dashboard.example.com:3000/?fail=true", > "UseProviders": [ > { > "Name": "openid-connect", > "Key": "{okta-client-id}", > "Secret": "{okta-client-secret}", > "Scopes": ["openid", "email", "profile"], > "DiscoverURL": "https://{okta-domain}/.well-known/openid-configuration" > } > ] > } > } > ``` > > * set `Key` to the Okta **Client ID** > * set `Secret` to the Okta **Client Secret** > * set `DashboardCredential` to the [TIB service account's](https://tyk.io/docs/tyk-identity-broker/dashboard-sso.md#tib-service-account) Dashboard credentials > > **Okta redirect URI** > > Ensure the following URL is listed in **Sign-in redirect URIs** in your Okta application settings. The `ID` in the registered URL must exactly match the `ID` in your TIB profile; a mismatch will result in a `400 Bad Request` error: > > ``` > http://dashboard.example.com:3000/auth/okta-dashboard-oidc/openid-connect/callback > ``` > > **Login URL** > > This URL initiates the SSO login flow: > > ``` > http://dashboard.example.com:3000/auth/okta-dashboard-oidc/openid-connect > ``` > > In production, present this as a "Log in with Okta" button or link on a custom login page, rather than expecting users to navigate to it directly. > > See [Dashboard SSO](https://tyk.io/docs/tyk-identity-broker/dashboard-sso.md) for details on session behavior, permissions, and user group mapping. > [tab] Portal SSO > > In this example, Tyk Developer Portal is running at `http://portal.example.com` on port `3001`; replace the example values with your own. > > **Tyk Developer Portal configuration** > > Enable embedded TIB in the Portal configuration: > > ```json theme={null} > { > "TIB": { > "Enable": true > } > } > ``` > > **TIB profile** > > The TIB profile is created via the Tyk Developer Portal UI under **Settings > SSO Profiles**. > > ```json expandable theme={null} > { > "ID": "okta-portal-oidc", > "Name": "Okta Portal SSO (OIDC)", > "OrgID": "{tyk-org-id}", > "ActionType": "GenerateOrLoginDeveloperProfile", > "Type": "redirect", > "ProviderName": "SocialProvider", > "ReturnURL": "http://portal.example.com:3001/sso", > "IdentityHandlerConfig": { > "DashboardCredential": "{portal-api-secret}" > }, > "ProviderConfig": { > "CallbackBaseURL": "http://portal.example.com:3001", > "FailureRedirect": "http://portal.example.com:3001/?fail=true", > "UseProviders": [ > { > "Name": "openid-connect", > "Key": "{okta-client-id}", > "Secret": "{okta-client-secret}", > "Scopes": ["openid", "email", "profile"], > "DiscoverURL": "https://{okta-domain}/.well-known/openid-configuration" > } > ] > } > } > ``` > > * set `ActionType` and `OrgID` based on the audience: > * Admin Portal (API owners): `ActionType: "GenerateOrLoginUserProfile"`, `OrgID: "0"` > * Live Portal (API consumers): `ActionType: "GenerateOrLoginDeveloperProfile"`, `OrgID` is not required > * set `Key` to the Okta **Client ID** > * set `Secret` to the Okta **Client Secret** > * set `DashboardCredential` to the [PORTAL\_API\_SECRET](https://tyk.io/docs/product-stack/tyk-enterprise-developer-portal/deploy/configuration.md#portal_api_secret) used to authenticate with the Portal's management API > > **Okta redirect URI** > > Ensure the following URL is listed in **Sign-in redirect URIs** in your Okta application settings. The `ID` in the registered URL must exactly match the `ID` in your TIB profile; a mismatch will result in a `400 Bad Request` error: > > ``` > http://portal.example.com:3001/auth/okta-portal-oidc/openid-connect/callback > ``` > > **Login URL** > > This URL initiates the SSO login flow: > > ``` > http://portal.example.com:3001/auth/okta-portal-oidc/openid-connect > ``` > > In production, present this as a "Log in with Okta" button or link on the Portal login page. > > For details on user group mapping and admin vs developer profiles, see [Portal SSO](https://tyk.io/docs/tyk-stack/tyk-developer-portal/enterprise-developer-portal/managing-access/enable-sso.md). ## SSO with SAML ### Configure Okta 1. In the Okta Admin Console, navigate to **Applications > Applications** and click **Create App Integration**. 2. Select **SAML 2.0** as the sign-in method and click **Next**. 3. Give the application a name and click **Next**. 4. In the **SAML Settings** section, set the following. For embedded TIB, the values are based on your Dashboard or Portal host: * **Single sign-on URL** (ACS URL): `http://{tib-host}/auth/{profile-id}/saml/callback` * **Audience URI (SP Entity ID)**: `http://{tib-host}/auth/{profile-id}/saml/metadata` 5. Under **Attribute Statements**, map the email attribute. Add a statement with name `email` and value `user.email`. 6. Click **Next**, complete the feedback form, and click **Finish**. 7. From the application's **Sign On** tab, copy the **Metadata URL**. You will need this for `IDPMetadataURL` in the TIB profile. ### TIB Profile The Okta-specific configuration goes in the `ProviderConfig` block of the TIB profile. Set `ProviderName` to `SAMLProvider` and `Type` to `redirect`. ```json expandable theme={null} { "ProviderName": "SAMLProvider", "Type": "redirect", "ProviderConfig": { "SAMLBaseURL": "http://{tib-host}", "IDPMetadataURL": "https://{okta-domain}/app/{app-id}/sso/saml/metadata", "CertLocation": "/path/to/sp-cert-and-key.pem", "FailureRedirect": "http://{failure-redirect-url}", "SAMLEmailClaim": "email", "SAMLForenameClaim": "firstName", "SAMLSurnameClaim": "lastName", "ForceAuthentication": false } } ``` | Field | Description | | - | - | | `SAMLBaseURL` | The base URL of your TIB instance. Used to construct the SP metadata and ACS URLs. | | `IDPMetadataURL` | The Okta application SAML metadata URL from step 7. | | `CertLocation` | Path to a PEM file containing the SP certificate and private key concatenated. When using Tyk Dashboard with embedded TIB, this can be a certificate ID from the Tyk Certificate Store. | | `SAMLEmailClaim` | The SAML attribute name for the user's email address, as configured in Okta's Attribute Statements. | | `SAMLForenameClaim` | The SAML attribute name for the user's first name. | | `SAMLSurnameClaim` | The SAML attribute name for the user's last name. | | `ForceAuthentication` | Set to `true` to force Okta to re-authenticate the user on every request. | ### Worked Examples (SAML) These examples use embedded TIB, so `SAMLBaseURL` is the same as the Dashboard or Portal respectively; TIB handles requests on the same host and port. > [tab] Dashboard SSO > > In this example, Tyk Dashboard is running at `http://dashboard.example.com` on port `3000`; replace the example values with your own. > > **Tyk Dashboard configuration** > > ```json theme={null} > { > "sso_enable_user_lookup": true, > "sso_permission_defaults": { > "apis": "write", > "keys": "write", > "policies": "write" > }, > "sso_default_group_id": "{tyk-user-group-id}" > } > ``` > > With this configuration, registered users (with a Tyk Dashboard user account) get their own permissions; unregistered users fall back to the group specified in `sso_default_group_id`. See [Dashboard SSO](https://tyk.io/docs/tyk-identity-broker/dashboard-sso.md) for full details. > > **Certificate** > > Upload the Service Provider certificate pair to the Tyk Certificate Store (**API Security > TLS/SSL Certificates**), noting the assigned certificate ID to be used in the TIB profile. > > **TIB profile** > > The TIB profile is created via the [Tyk Identity Broker API](https://tyk.io/docs/tyk-identity-broker/tib-rest-api.md) or the [Tyk Dashboard UI](https://tyk.io/docs/tyk-identity-broker/dashboard-sso.md#create-a-tib-profile-using-dashboard-ui). > > ```json expandable theme={null} > { > "ID": "okta-dashboard-saml", > "Name": "Okta Dashboard SSO (SAML)", > "OrgID": "{tyk-org-id}", > "ActionType": "GenerateOrLoginUserProfile", > "Type": "redirect", > "ProviderName": "SAMLProvider", > "ReturnURL": "http://dashboard.example.com:3000/tap", > "IdentityHandlerConfig": { > "DashboardCredential": "{tib-service-user-api-key}" > }, > "ProviderConfig": { > "SAMLBaseURL": "http://dashboard.example.com:3000", > "IDPMetadataURL": "https://{okta-domain}/app/{app-id}/sso/saml/metadata", > "CertLocation": "{certificate-id-from-dashboard}", > "FailureRedirect": "http://dashboard.example.com:3000/?fail=true", > "SAMLEmailClaim": "email", > "SAMLForenameClaim": "firstName", > "SAMLSurnameClaim": "lastName", > "ForceAuthentication": false > } > } > ``` > > * set `DashboardCredential` to the [TIB service account's](https://tyk.io/docs/tyk-identity-broker/dashboard-sso.md#tib-service-account) Dashboard credentials > * set `CertLocation` to the certificate ID from the Tyk Certificate Store > > **Login URL** > > This URL initiates the SSO login flow: > > ``` > http://dashboard.example.com:3000/auth/okta-dashboard-saml/saml > ``` > > In production, present this as a "Log in with Okta" button or link on a custom login page, rather than expecting users to navigate to it directly. > > See [Dashboard SSO](https://tyk.io/docs/tyk-identity-broker/dashboard-sso.md) for details on session behavior, permissions, and user group mapping. > [tab] Portal SSO > > In this example, Tyk Developer Portal is running at `http://portal.example.com` on port `3001`; replace the example values with your own. > > **Tyk Developer Portal configuration** > > Enable embedded TIB in the Portal configuration: > > ```json theme={null} > { > "TIB": { > "Enable": true > } > } > ``` > > **Certificate** > > Unlike the Dashboard, the Portal's embedded TIB loads certificates from the filesystem. Set `CertLocation` to the file path of a PEM file containing the SP certificate and private key concatenated, accessible on the server running the Portal. > > **TIB profile** > > The TIB profile is created via the Tyk Developer Portal UI under **Settings > SSO Profiles**. > > ```json expandable theme={null} > { > "ID": "okta-portal-saml", > "Name": "Okta Portal SSO (SAML)", > "OrgID": "{tyk-org-id}", > "ActionType": "GenerateOrLoginDeveloperProfile", > "Type": "redirect", > "ProviderName": "SAMLProvider", > "ReturnURL": "http://portal.example.com:3001/sso", > "IdentityHandlerConfig": { > "DashboardCredential": "{portal-api-secret}" > }, > "ProviderConfig": { > "SAMLBaseURL": "http://portal.example.com:3001", > "IDPMetadataURL": "https://{okta-domain}/app/{app-id}/sso/saml/metadata", > "CertLocation": "/path/to/sp-cert-and-key.pem", > "FailureRedirect": "http://portal.example.com:3001/?fail=true", > "SAMLEmailClaim": "email", > "SAMLForenameClaim": "firstName", > "SAMLSurnameClaim": "lastName", > "ForceAuthentication": false > } > } > ``` > > * set `ActionType` and `OrgID` based on the audience: > * Admin Portal (API owners): `ActionType: "GenerateOrLoginUserProfile"`, `OrgID: "0"` > * Live Portal (API consumers): `ActionType: "GenerateOrLoginDeveloperProfile"`, `OrgID` is not required > * set `CertLocation` to the file path of the SP certificate PEM file on the Portal server > * set `DashboardCredential` to the [PORTAL\_API\_SECRET](https://tyk.io/docs/product-stack/tyk-enterprise-developer-portal/deploy/configuration.md#portal_api_secret) used to authenticate with the Portal's management API > > **Login URL** > > This URL initiates the SSO login flow: > > ``` > http://portal.example.com:3001/auth/okta-portal-saml/saml > ``` > > In production, present this as a "Log in with Okta" button or link on the Portal login page. > > For details on user group mapping and admin vs developer profiles, see [Portal SSO](https://tyk.io/docs/tyk-stack/tyk-developer-portal/enterprise-developer-portal/managing-access/enable-sso.md).