Single Sign On

Last updated: May 24, 2024 6 minutes read.

Introduction to Single Sign On (SSO)

SSO - The generic use case

SSO gives users the ability to log in to multiple applications without the need to enter their password more than once. OIDC or SAML enables an application to verify the identity of users from an organisation without the need to self store and manage them, and without doing the identification process and exposing their passwords to that application. Their lists of users and passwords are kept safe in one single place, in the IDP that the organisation has chosen to use. The Authorisation server of the IdP identify the users for a pre-registered and approved application (client in OAuth and OIDC terminology).

SSO in Tyk

SSO is sometimes complicated to understand or set up but can be easily accomplished by using the built-in Tyk Identity Broker (TIB).

Using our Tyk-Identity-Broker (TIB), you can do both - use your existing users directory to login to the Dashboard or Developer Portal and have an SSO. TIB, among other options, supports four methods for login to Tyk’s UI:

Tyk Identity Broker (TIB)

TIB is an open-source project which can be used to integrate Tyk authentication with 3rd party identity providers (IDPs). Starting from Tyk v3.0, TIB has been added as a built-in feature of the Tyk Dashboard meaning there is no configuration required and it is readily available for use. TIB has been designed as a glue-code solution, so it can integrate with almost any identity provider (IDP) including all the known Social providers. See our TIB detailed overview for further information.

SSO is sometimes complicated to understand or set up but once you get it and learn to use our Tyk-Identity-Broker it becomes an easy task.

In short, all you need is as follow:

Access the Identity Manager under System Management in the Tyk Dashboard
Create a profile for your preferred IDP
Get the client_id + secret that are defined on your IDP
Set the Callback URL generated by Tyk on your IDP
Provide your SSO profile in Tyk with the Discover URL (well known endpoint)
Visit the Login URL after saving your profile to initialize the login
More Docs for the flow can be found on our GitHub TIB repo README and our 3rd Party integration docs

See using a Social Identity Provider for details of using SSO with Social Identity Providers.

SSO with OpenID Connect (OIDC)

Instruction on setting SSO with Okta
Instructions on setting SSO with Auth0
Instructions on setting SSO with PingID - will be added soon
Instructions on setting SSO with Keycloak

SSO with SAML

SAML authentication is a way for a service provider, such as the Tyk Dashboard or Portal, to assert the Identity of a User via a third party.

Tyk Identity Broker can act as the go-between for the Tyk Dashboard and Portal and a third party identity provider. Tyk Identity broker can also interpret and pass along information about the user who is logging in such as Name, Email and group or role metadata for enforcing role based access control in the Tyk Dashboard.

The provider config for SAML has the following values that can be configured in a Profile:

SAMLBaseURL - The host of TIB that will be used in the metadata document for the Service Provider. This will form part of the metadata URL used as the Entity ID by the IDP. The redirects configured in the IDP must match the expected Host and URI configured in the metadata document made available by Tyk Identity Broker.

FailureRedirect - Where to redirect failed login requests.

IDPMetaDataURL - The metadata URL of your IDP which will provide Tyk Identity Broker with information about the IDP such as EntityID, Endpoints (Single Sign On Service Endpoint, Single Logout Service Endpoint), its public X.509 cert, NameId Format, Organisation info and Contact info.

This metadata XML can be signed providing a public X.509 cert and the private key.

CertLocation: An X.509 certificate and the private key for signing your requests to the IDP, this should be one single file with the cert and key concatenated. When using internal identity broker, this value should be the id of the certificate uploaded via certificate manager in dashboard, otherwise it should be a path where the certificate is placed.

ForceAuthentication - Ignore any session held by the IDP and force re-login every request.

SAMLEmailClaim - Key for looking up the email claim in the SAML assertion form the IDP. Defaults to: http://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddress

SAMLForenameClaim - Key for looking up the forename claim in the SAML assertion form the IDP. Defaults to: http://schemas.xmlsoap.org/ws/2005/05/identity/claims/forename

SAMLSurnameClaim - Key for looking up the surname claim in the SAML assertion form the IDP. Defaults to: http://schemas.xmlsoap.org/ws/2005/05/identity/claims/surname

Example profile configuration:

{
    "ActionType": "GenerateOrLoginUserProfile",
    "ID": "saml-sso-login",
    "OrgID": "{YOUR_ORGANISATION_ID}",
    "CustomEmailField": "",
    "IdentityHandlerConfig": {
        "DashboardCredential": "{DASHBOARD_USER_API_KEY}"
    },
    "ProviderConfig": {
        "SAMLBaseURL": "https://{HOST}",
        "FailureRedirect": "http://{DASHBOARD_HOST}:{PORT}/?fail=true",
        "IDPMetaDataURL": "{IDP_METADATA_URL}",
        "CertLocation":"myservice.cert",
        "ForceAuthentication": false,
        "SAMLEmailClaim": "",
        "SAMLForenameClaim": "",
        "SAMLSurnameClaim": ""
    },
    "ProviderName": "SAMLProvider",
    "ReturnURL": "http://{DASHBOARD_URL}:{PORT}/tap",
    "Type": "redirect"
}

Example Video

We have a video that walks you through getting Tyk Dashboard SSO Access via SAML using Microsoft Azure as IDP and our internal Dashboard TIB.

Tyk’s REST API for SSO

The SSO API allows you to implement custom authentication schemes for the Dashboard and Portal. You can access the API by both admin and dashboard APIs. Our Tyk Identity Broker (TIB) internally also uses these APIs.

Generate authentication token

The Dashboard exposes two APIs:

/admin/sso - See Dashboard Admin API SSO for more details.
/api/sso - See Dashboard API SSO for more details.

which allow you to generate a temporary authentication token, valid for 60 seconds. They make same thing you can select one of them and use it. However, the admin API requires admin-auth header which should be same with admin-secret parameter in tyk_analytics.conf, the regular API requires authorization header which should be same with the user authentication token.

Using the Token

Once you have issued a token you can login to the dashboard using the /tap url, or to the portal using the <portal-url>/sso URL, and provide an authentication token via the nonce query param. If nonce is valid, Tyk will create a temporary user and log them in.

If you want to re-use existing dashboard users, instead of creating temporary ones, you can set "sso_enable_user_lookup": true variable in the Dashboard config file (tyk_analytics.conf). This way you can set individual permissions for users logged via SSO.

Set up default permissions for the dashboard

If you use the token with dashboard scope, and would like to avoid login in as admin user (which is the default permissions), you can add the sso_permission_defaults configuration option to the Dashboard config file (tyk_analytics.conf) to specify SSO user permissions in the following format:

"sso_permission_defaults": {
  "analytics": "read",
  "apis": "write",
  "hooks": "write",
  "idm": "write",
  "keys": "write",
  "policies": "write",
  "portal": "write",
  "system": "write",
  "users": "write",
  "user_groups": "write"
}

As alternative, you can set sso_default_group_id to specify User Group ID assigned to SSO users.

In order to set individual user permissions, you should first create this users in the dashboard first, set needed permissions, enable sso_enable_user_lookup to true inside dashboard config. If SSO user with the same email will be found in Dashboard users, it will re-use his permissions.

GET /tap?nonce=YTNiOGUzZjctYWZkYi00OTNhLTYwODItZTAzMDI3MjM0OTEw HTTP/1.1
Host: localhost:3000

SSO with LDAP Integration

Detailed instruction on setting SSO with LDAP.

See apply search filters to add advanced search to your LDAP authentication.