Single Sign On
Last updated: 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 organization 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 organization has chosen to use. The Authorization 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:
- Login with 3rd party social providers
- Login with any IdP that supports OIDC
- Login with any IdP that supports SAML
- Login with LDAP (not using OIDC)
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 with Open ID Connect or Social Providers
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
SSO with Social Identity Providers
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, Organization 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.
Sample Login Request
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.