SSO with Social Identity Providers

Learn how to configure Single Sign-On (SSO) for Tyk Dashboard or Tyk Developer Portal using OAuth-based social identity providers such as Google, GitHub, and LinkedIn.

Introduction

TIB supports OAuth 2.0-based social identity providers using SocialProvider. Each supported provider requires an OAuth application registered with that provider, from which you obtain a Client ID and Client Secret.

The following provider names are supported in UseProviders[].Name:

Provider	Name value
GitHub	github
LinkedIn	linkedin
Twitter / X	twitter
Bitbucket	bitbucket
DigitalOcean	digitalocean
Dropbox	dropbox
Salesforce	salesforce

The legacy gplus provider for Google no longer works following the Google+ shutdown in 2019. Use the openid-connect provider name instead, as shown in the Google example below.

Before configuring your TIB profile, read Dashboard SSO or Portal SSO to understand the ActionType, ReturnURL, and IdentityHandlerConfig fields required for your use case.

TIB Profile

The social provider 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": "{provider-name}",
        "Key": "{client-id}",
        "Secret": "{client-secret}"
      }
    ]
  }
}

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	The provider name (for example, github, linkedin). See the table above.
UseProviders.Key	The OAuth Client ID from your social provider application.
UseProviders.Secret	The OAuth Client Secret from your social provider application.

Domain Constraint

For providers that return the user’s email address (such as Google), you can restrict access to users from a specific email domain by adding a ProviderConstraints block to the profile:

{
  "ProviderConstraints": {
    "Domain": "your-company.com",
    "Group": ""
  }
}

Users whose email address does not match the configured domain will be redirected to FailureRedirect.

JSON Web Encryption (JWE)

SocialProvider supports JSON Web Encryption (JWE), which allows TIB to decrypt encrypted ID tokens returned by the IdP. This is useful when your IdP is configured to encrypt tokens for additional security.

JWE requires Tyk Identity Broker v1.6.1+ and Tyk Dashboard v5.7.0+.

To enable JWE, add a JWE block to ProviderConfig:

{
  "ProviderConfig": {
    "UseProviders": [...],
    "JWE": {
      "Enabled": true,
      "PrivateKeyLocation": "{certificate-id-or-path}"
    }
  }
}

Field	Description
Enabled	Set to true to enable JWE decryption.
PrivateKeyLocation	For embedded TIB in Tyk Dashboard, use the certificate ID from the Tyk Dashboard certificate manager. For standalone TIB, use the file path to a PEM file containing the private key.

The private key must correspond to the public key registered with your IdP for token encryption. Configure your IdP to encrypt ID tokens using the matching public key before enabling this setting.

Configure Your Provider

Register an OAuth application with your chosen social provider and note the Client ID and Client Secret. The callback URL to register with the provider is shown below. The {profile-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://{tib-host}/auth/{profile-id}/{provider-name}/callback

For example, for GitHub with a profile ID of github-dashboard and TIB running at http://dashboard.example.com:3000:

http://dashboard.example.com:3000/auth/github-dashboard/github/callback

Worked Example: GitHub

This example configures GitHub OAuth for Dashboard SSO. The same pattern applies to all other social providers; only the Name, Key, Secret, and the callback URL registered with the provider differ.

Dashboard SSO

In this example, Tyk Dashboard is running at http://dashboard.example.com on port 3000; replace the example values with your own.

GitHub OAuth application

Register an OAuth application at github.com/settings/applications/new. Set the Authorization callback URL to:

http://dashboard.example.com:3000/auth/github-dashboard/github/callback

Note the Client ID and Client Secret.

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": "github-dashboard",
  "Name": "GitHub Dashboard SSO",
  "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": "github",
        "Key": "{github-client-id}",
        "Secret": "{github-client-secret}"
      }
    ]
  }
}

• set Key to the GitHub Client ID
• set Secret to the GitHub Client Secret
• set DashboardCredential to the TIB service account’s Dashboard credentials

Login URL

This URL initiates the SSO login flow:

http://dashboard.example.com:3000/auth/github-dashboard/github

In production, present this as a “Log in with GitHub” 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.

GitHub OAuth application

Register an OAuth application at github.com/settings/applications/new. Set the Authorization callback URL to:

http://portal.example.com:3001/auth/github-portal/github/callback

Note the Client ID and Client Secret.

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": "github-portal",
  "Name": "GitHub Portal SSO",
  "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": "github",
        "Key": "{github-client-id}",
        "Secret": "{github-client-secret}"
      }
    ]
  }
}

• 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 GitHub Client ID
• set Secret to the GitHub Client Secret
• set DashboardCredential to the PortalAPISecret used to authenticate with the Portal’s management API

Login URL

This URL initiates the SSO login flow:

http://portal.example.com:3001/auth/github-portal/github

In production, present this as a “Log in with GitHub” button or link on the Portal login page.

For details on user group mapping and admin vs developer profiles, see Portal SSO.

Worked Example: Google

Google authentication uses the openid-connect provider name rather than a named OAuth provider, since the gplus provider was retired in 2019. The setup follows the same pattern as any OIDC provider.

Configure Google

1. Go to the Google Cloud Console and navigate to APIs and Services > Credentials.
2. Click Create Credentials and select OAuth client ID.
3. Select Web application as the application type.
4. Under Authorized redirect URIs, add the TIB callback URL:
   http://{tib-host}/auth/{profile-id}/openid-connect/callback
   
5. Click Create and note the Client ID and Client Secret.

Google’s OIDC discovery URL is:

https://accounts.google.com/.well-known/openid-configuration

Worked Examples (Google)

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": "google-dashboard-oidc",
  "Name": "Google Dashboard SSO",
  "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": "{google-client-id}",
        "Secret": "{google-client-secret}",
        "Scopes": ["openid", "email", "profile"],
        "DiscoverURL": "https://accounts.google.com/.well-known/openid-configuration"
      }
    ]
  }
}

• set Key to the Google Client ID
• set Secret to the Google Client Secret
• set DashboardCredential to the TIB service account’s Dashboard credentials

Google redirect URI

Ensure the following URL is listed in Authorized redirect URIs in your Google Cloud Console credentials. 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/google-dashboard-oidc/openid-connect/callback

Login URL

This URL initiates the SSO login flow:

http://dashboard.example.com:3000/auth/google-dashboard-oidc/openid-connect

In production, present this as a “Log in with Google” 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": "google-portal-oidc",
  "Name": "Google Portal SSO",
  "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": "{google-client-id}",
        "Secret": "{google-client-secret}",
        "Scopes": ["openid", "email", "profile"],
        "DiscoverURL": "https://accounts.google.com/.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 Google Client ID
• set Secret to the Google Client Secret
• set DashboardCredential to the PortalAPISecret used to authenticate with the Portal’s management API

Google redirect URI

Ensure the following URL is listed in Authorized redirect URIs in your Google Cloud Console credentials. 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/google-portal-oidc/openid-connect/callback

Login URL

This URL initiates the SSO login flow:

http://portal.example.com:3001/auth/google-portal-oidc/openid-connect

In production, present this as a “Log in with Google” button or link on the Portal login page.

For details on user group mapping and admin vs developer profiles, see Portal SSO.