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 supports both OpenID Connect (OIDC) and SAML 2.0.

• 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 or Portal SSO 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.

{
  "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:

{
  "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.

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

{
  "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 for full details.

TIB profile

The TIB profile is created via the Tyk Identity Broker API or the Tyk Dashboard UI.

{
  "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 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 for details on session behavior, permissions, and user group mapping.

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:

{
  "TIB": {
    "Enable": true
  }
}

TIB profile

The TIB profile is created via the Tyk Developer Portal UI under Settings > SSO Profiles.

{
  "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 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.

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.

{
  "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.

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

{
  "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 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 or the Tyk Dashboard UI.

{
  "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 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 for details on session behavior, permissions, and user group mapping.

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:

{
  "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.

{
  "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 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.