Tyk Identity Broker - Integrate Social Logins, IDPs, LDAP and Custom Authentication

​

Introduction

1. Introduction to Tyk Identity Broker: Explore key concepts, configuration options, and implementation steps for TIB. You’ll learn how to set up profiles for different identity providers, understand the flow of authentication requests, and customize the integration to fit your specific needs.
2. Single Sign On with Tyk: We will learn how to implement seamless SSO experiences for Tyk Dashboard and Developer Portal.
3. SSO with different Protocols and Systems: We will explore SSO integrations with LDAP, Social OAuth, SAML, and OpenID Connect.
4. Handling Custom Authentication: We will learn how to configure TIB for unique authentication scenarios using the Proxy Provider.

​

What is Tyk Identity Broker (TIB)?

1. Internal TIB: Embedded in dashboard. Easy configuration and set up. Share the same port as the dashboard
2. External TIB: Installation of TIB as a different component for advanced use cases. Requires changes to the config files and separate port.

• Enabling easy access via social logins to the developer portal (e.g. GitHub login)
• Enabling internal access to the dashboard (e.g. via LDAP/ActiveDirectory)
• Enabling easy token generation from a third party for things such as mobile apps and webapps without complex configuration

​

Working of Tyk Identity Broker (TIB)

1. An Identity Provider that will authorize a user and validate their identity
2. An Identity Handler that will authenticate a user with a delegated service (in this case, Tyk)

​

Identity Providers

1. Social - this provides OAuth handlers for many popular social logins (such as Google, Github and Bitbucket)
2. LDAP - a simple LDAP protocol binder that can validate a username and password against an LDAP server (tested against OpenLDAP)
3. Proxy - a generic proxy handler that will forward a request to a third party and provides multiple “validators” to identify whether a response is successful or not (e.g. status code, content match and regex)
4. SAML - provides a way to authenticate against a SAML IDP.

​

Identity Handlers

1. GenerateOrLoginUserProfile - this will log a user into the Tyk Dashboard (this does not create a user, it only creates a temporary session for the user to have access). This flow is defined as next:

2. GenerateOrLoginDeveloperProfile - this will create or login a user to the Tyk Developer Portal. The flow is similar to GenerateOrLoginUserProfile but in this case if the developer doesn’t exist then it will be created.
3. GenerateOAuthTokenForClient - this will act as a client ID delegate and grant an Tyk provided OAuth token for a user using a fragment in the redirect URL (standard flow). The flow is defined as:

​

Exploring TIB Profiles

​

Anatomy of a Profile

​

Fields that are common for all the providers

​

LDAP profile fields

​

ProxyProvider profile fields

​

Social profile fields

​

SAML profile fields

​

Installing Tyk Identity Broker (TIB)

1. Embedded TIB: Starting from Tyk Dashboard v3.0 TIB is built-in to the dashboard, in this case TIB will store the profiles in the same mongo database configured for dashboard
2. Standalone TIB: Deployed as a seperate entity. In the standalone TIB, the profiles will be stored in file indicated when the app is started

• Tyk Gateway v1.9.1+
• Redis
• Tyk Dashboard v0.9.7.1+ (Only if you want to do SSO to Tyk Dashboard UI or Tyk Developer Portal)

​

Enable Embedded TIB

"identity_broker": {
    "enabled": true,
},

• If enabled = false then neither the external or internal TIB will be loaded
• If enabled = true and the tib host is not present the internal TIB will be loaded
• If enabled = true and the tib host is set, then external TIB will be loaded

​

Install Standalone TIB

1. Docker: You can install via Docker.
2. Linux Packages: You can install via packages (deb or rpm).
3. Helm Chart for Kubernetes: Tyk Helm Chart does not support installing TIB as separate application. If you want to enable embedded TIB in Dashboard, you can do so by updating tib.enabled to true in tyk-dashboard chart. If you are using an umbrella chart from us (e.g. tyk-stack and tyk-control-plane), you can do so by updating tyk-dashboard.tib.enabled to true.

​

Important TIB Configurations

​

Configure secret for hashing session cookies

​

Setting Absolute Paths

Usage of ./tyk-auth-proxy:
  -c=string
        Path to the config file (default "tib.conf")
  -p#=string
        Path to the profiles file (default "profiles.json")

​

Exploring Tyk Identity Broker REST API

​

Single Sign On (SSO)

​

SSO in Tyk

1. Login with 3rd party social providers
2. Login with any IdP that supports OIDC
3. Login with any IdP that supports SAML
4. Login with LDAP

​

SSO with Open ID Connect or Social Providers

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

​

Tyk’s REST API for SSO

​

Generate authentication token

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

​

Using the Token

Set up default permissions for the dashboard

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

Sample Login Request

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

​

SSO with Social Identity Providers

• Bitbucket
• Digital Ocean
• Dropbox
• GitHub
• Google+
• Linkedin
• Twitter
• Salesforce

​

Log into an APP with Github OAuth

​

Log into an APP with Google (Oauth)

​

To Set up an OAuth client with Google Apps

1. Go to the Google Developer Console and create a new app
2. Register a new OAuth client. Let’s call it WebApp 1 (Select “New Credentials -> OAuth Client ID”)
3. Select Web App
4. Add the following URL (modify for your domain) to the “Authorized redirect URIs” section: http://tib-hostname:TIB-PORT/auth/{PROFILE-ID}/gplus/callback

​

Create an OAuth Client in Tyk Dashboard

{
  "ActionType": "GenerateOAuthTokenForClient",
  "ID": "3",
  "IdentityHandlerConfig": {
    "DashboardCredential": "{DASHBOARD-API-ID}",
    "DisableOneTokenPerAPI": false,
    "OAuth": {
      "APIListenPath": "{API-LISTEN-PATH}",
      "BaseAPIID": "{BASE-API-ID}",
      "ClientId": "{TYK-OAUTH-CLIENT-ID}",
      "RedirectURI": "http://{APP-DOMAIN}:{PORT}/{AUTH-SUCCESS-PATH}",
      "ResponseType": "token",
      "Secret": "{TYK-OAUTH-CLIENT-SECRET}"
    }
  },
  "MatchedPolicyID": "567a86f630c55e3256000003",
  "OrgID": "53ac07777cbb8c2d53000002",
  "ProviderConfig": {
    "CallbackBaseURL": "http://{TIB-DOMAIN}:{TIB-PORT}",
    "FailureRedirect": "http://{PORTAL-DOMAIN}:{PORTAL-PORT}/portal/login/?fail=true",
    "UseProviders": [{
      "Key": "GOOGLE-OAUTH-CLIENT-KEY",
      "Name": "gplus",
      "Secret": "GOOGLE-OAUTH-CLIENT-SECRET"
    }]
  },
  "ProviderConstraints": {
    "Domain": "",
    "Group": ""
  },
  "ProviderName": "SocialProvider",
  "ReturnURL": "",
  "Type": "redirect"
}

• APIListenPath: This is the listen path of your API, TIB uses this to generate the OAuth token.
• BaseAPIID: The base API ID for the listen path mentioned earlier, this forms the basic access grant for the token (this will be superseded by the MatchedPolicyID, but is required for token generation).
• ClientId: The client ID for this profile within Tyk Gateway.
• Secret: The client secret for this profile in Tyk Gateway.
• RedirectURI: The Redirect URL set for this profile in the Tyk Gateway.
• ResponseType: This can be token or authorization_code, the first will generate a token directly, the second will generate an auth code for follow up access. For SPWA and Mobile Apps it is recommended to just use token.

​

Log into Dashboard with Google

{
  "ActionType": "GenerateOrLoginUserProfile",
  "ID": "2",
  "IdentityHandlerConfig": null,
  "MatchedPolicyID": "1C",
  "OrgID": "53ac07777cbb8c2d53000002",
  "ProviderConfig": {
    "CallbackBaseURL": "http://:{TIB-PORT}",
    "FailureRedirect": "http://{DASH-DOMAIN}:{DASH-PORT}/?fail=true",
    "UseProviders": [{
      "Name": "gplus",
      "Key": "GOOGLE-OAUTH-CLIENT-KEY",
      "Secret": "GOOGLE-OAUTH-CLIENT-SECRET"
    }]
  },
  "ProviderConstraints": {
    "Domain": "yourdomain.com",
    "Group": ""
  },
  "ProviderName": "SocialProvider",
  "ReturnURL": "http://{DASH-DOMAIN}:{DASH-PORT}/tap",
  "Type": "redirect"
}

​

SSO with OpenID Connect (OIDC)

• Instruction on setting SSO with Okta
• Instructions on setting SSO with Auth0
• Instructions on setting SSO with Keycloak
• Instructions on setting SSO with AzureAD

​

OIDC with Azure AD

​

Configuration at Azure

1. Access your Azure Portal and navigate to the Azure Active Directory page.
2. Go to app registrations and create or access an application you want to use for Dashboard access.
   • If you are creating an application, give it a name and register it
3. Add a redirect URL to your application as callback to TIB in your Azure application:
   • In your app, either via the Authentication menu or the redirect URL shortcut navigate to and add the redirect to TIB in the Web category i.e. http://localhost:3000/auth/{PROFILE-NAME-IN-TIB}/openid-connect/callback.
   
4. Go to Overview and add a secret in Client Credentials. Don’t forget to copy the secret value, not the secretID.

​

Configuration at Dashbaord

1. Log in to your dashboard and select Identity Management, located under System Management
2. Create a profile and select OpenID Connect as the provider type
3. Under Profile Configuration, paste the secret value, clientID, and well-known endpoint URL from the Azure site.
   • Profile Configuation may look something like this:
   
   • The well-known endpoint URL is created by Azure and can be located by selecting Endpoints on their site
   

​

Test your Azure Login:

• If it’s working you’ll be redirected to Azures’s web page and asked for your username and password.
• If it’s working you’ll be redirected to Azures’s web page and asked for your username and password.

​

Enhancements

User group mapping

• Identity provider role
• Tyk User Group: This can be created from the User Groups section of the dashboard (reference a link to a page in tyk docs here to show how to create a user group). When creating your User Group, one can also select and adjust the permissions for each group.

​

OpenID Connect Example

1. Add the redirect url found on the OpenID Connect site to the redirect urls found under the Web section
2. Copy the OpenID Connect endpoint from the Azure site
3. On the OpenID Connect site select Edit. In the Server Template dropdown menu select the Custom option and paste the endpoint in the Discovery Document URL.
4. Press the Use Discovery Document button and this will autofill Authorization Token Endpoint, Token Endpoint, and Token Keys Endpoint
5. Copy and paste the Client ID and Client Secret from the Azure site to your ConnectID. Scope is autofilled for you and save the configuration.
6. Press start at the bottom of the Request window and if done correctly, this should prompt you to sign in to your Azure account.
7. You should then be redirected back to OpenID Connect where you’ll be shown the Exchange Code. This needs to be turned into an access token. Press the exchange button under the request and then press Next.
8. We can then verify this by pressing the verify button. We can also view the information or scope of what is being returned by heading to jwt.io and viewing the payload: data there.
9. We are given an object with key, value pairs and we can pass in the key ie. name to our Custom User Group and the value of to our Identity Provider Role in our Tyk dashboard as shown in the example above.

​

OIDC with Okta

• You already have authorized access to Tyk’s Dashboard. If you haven’t, get the authorization key by following this doc.
• For simplicity, you are running TIB locally on port 3010
• You are able to edit TIB’s configuration file.

​

Configuration at Okta

1. Create a developer account on the Okta Developer site. You’ll get a domain such as https://<okta-org>.okta.com/.well-known/openid-configuration
2. Login and create a Web Application as follows:
   • Under Application, click Add Application
   • Choose Web
   • Change the name of the app
   • Tick Authorization Code
   • Click Done
   Note: These instruction are for the new Okta’s Developer Console, for the Classic UI instructions are slightly different.
3. Add a callback to TIB in your application:
   • Under General, click Edit and update the Login redirect URIs field with the endpoint on TIB http://localhost:3010/auth/{PROFILE-NAME-IN-TIB}/openid-connect/callback.
   • {PROFILE-NAME-IN-TIB} - this can be any string you choose, as long as you use the same one for the profile in TIB.
4. Permissions to login via Okta: Under the Assignments tab, make sure group assignments is set to everyone (for now, you will change this later!).
5. This is how it should look like after step #4

​

Configuration at TIB

6. Set the profile in profiles.json as follows:
   • Copy from your Okta client the cliend ID to ProviderConfig.UseProviders[].key
   • Copy from your Okta client the Client secret to ProviderConfig.UseProviders[].secret
   • Add Okta’s discovery url "https://<okta-org>.okta.com/.well-known/openid-configuration" to ProviderConfig.UseProviders[].DiscoverURL
   Example of a profiles.json file:

[{
  "ActionType": "GenerateOrLoginUserProfile",
  "ID": "{PROFILE-NAME-IN-TIB}",
  "OrgID": "5a54a74550200d0001975584",
  "IdentityHandlerConfig": {
    "DashboardCredential": "{DASHBOARD-SECRET}"
  },
  "ProviderConfig": {
    "CallbackBaseURL": "http://{TIB-DOMAIN}:{TIB-PORT}",
    "FailureRedirect": "http://{DASHBOARD-DOMAIN}:{DASHBOARD-PORT}/?fail=true",
    "UseProviders": [
    {
      "Key": "{Okta-App-Client-ID}",
      "Secret": "{Okta-App-Client-SECRET}",
      "Scopes": ["openid", "email"],
      "DiscoverURL": "https://<okta-org>.okta.com/.well-known/openid-configuration",
      "Name": "openid-connect"
    }
  ]
  },
  "ProviderName": "SocialProvider",
  "ReturnURL": "http://{DASHBOARD-DOMAIN}:{DASHBOARD-PORT}/tap",
  "Type": "redirect"
}]

7. Start TIB by running the binary (profiles.json is in the same CWD) See Install TIB for detailed instructions on how to install TIB
8. Test that it works: From the broswer call http://localhost:3010/auth/{PROFILE-NAME-IN-TIB}/openid-connect
   • If it’s working you’ll be redirected to Okta’s web page and will be asked to enter your Okta user name and password.
   • If you were successfully authenticated by Okta then you’ll be redirected to the Tyk Dashboard and login into it without going through the login page. Job’s done!
9. If you need to update your profile then you can use TIB’s REST API as follows:

curl http://{TIB-DOMAIN}:{TIB-PORT}/api/profiles/{PROFILE-NAME-IN-TIB} -H "Authorization: {MY-SECRET}" -H "Content-type: application/json" -X PUT --data "@./my-new-dashboard-profile.json" | prettyjson

• POST and DELETE calls apply as normal
• You can post a few profiles to TIB.
• See TIB REST API for more details.

​

Understanding the flow

1. The initial call to the endpoint on TIB was redirected to Okta
2. Okta identified the user
3. Okta redirected the call back to TIB endpoint (according to the callback you set up on the client earlier in step 3) and from TIB
4. TIB, via REST API call to the dashboard, created a nonce and a special session attached to it.
5. TIB redirected the call to the dashboard to a special endpoint /tap ( it was defined on the profile under ReturnURL) with the nonce that was created.
6. The Dashboard on the /tap endpoint finds the session that is attached to the nonce, login the user and redirect to the dashboard first page

​

Enabling MFA and SSO

SSO login into the Dashboard via a login page

• set up a web server with a login page and a form for user and password
• Update tyk_analytics.conf to redirect logins to that url Explicit details are in steps 6-7

Multi-Factor-Authentication (MFA) Support

1. While trying to login to the Dashboard, Okta enforced the MFA and asked me to use the Google Authenticator:

2. I had to download the Google Authenticator and identify with the generated code

3. I successfully authenticated with Google Authenticator

​

Common Error

• On Okta’s app - Login redirect URIs: http://localhost:3010/auth/{PROFILE-NAME-IN-TIB}/openid-connect/callback.
• The endpoint to test - http://localhost:3010/auth/{PROFILE-NAME-IN-TIB}/openid-connect

​

OIDC with Auth0

• A free account with Auth0
• A Tyk Self-Managed or Cloud installation
• Our Tyk Identity Broker (TIB). You can use the internal version included with a Tyk Self-Managed installation and Tyk Cloud, or an external version. See Tyk Identity Broker for more details.

​

Create a new user in Auth0

1. Log in to your Auth0 account.
2. Select Users from the User Management menu.

3. Click Create User and complete the new user form, using the default Username-Password-Authentication Connection method.
4. Click Create to save your new user.

​

Create an Auth0 application

1. Select Applications from the Auth0 menu.

2. Click Create Application.
3. Give your application a name and select Regular Web Application from the applications types.

4. Click Create.
5. After you application has been created select the Basic Information tab.

6. You will use the Domain, Client Id and Client Secret values in the Identity profile you create next in the Tyk Dashboard.

​

Create an Identity Management profile in your Dashboard

1. Log in to your Tyk Dashboard as an Admin user.
2. Select Identity Management from the System Management menu.

3. Click Create Profile.
4. In the Profile action section enter a name for your profile and make sure the Login to Tyk Dashboard option is selected.

5. Click Next. In the Provider type section, select OpenID Connect.

6. Click Next. Copy the Client ID value from your Auth0 application > Basic Information and paste it in the Client ID / Key field.
7. Copy the Client Secret value from your Auth0 application > Basic Information and paste it in the Secret field.
8. You need to add a Discover URL (well known endpoint). Use the following URL, replacing <<your-auth0-domain>> with the Domain value from your Auth0 application > Basic Information. https://<<your-auth0-domain>>/.well-known/openid-configuration
9. Copy the Callback URL and paste it into the Allowed Callback URLs field in your Auth0 application > Basic Information.

10. Click Save Changes to update your Auth0 Application.
11. Click Create Profile to save your Identity profile in your Tyk Dashboard.

​

Test your Auth0 Login

1. From your Identity Management Profiles click the profile you created to open it.

2. Click the Login URL.

3. You will now see the Auth0 login form in a browser tab.

4. Enter the email address and password of your Auth0 user.
5. You may be asked to authorize your Auth0 application.

6. Click Accept.
7. You will now be taken to the Tyk Dashboard.

​

OIDC with Keycloak

​

Configuration at KeyCloak

1. In your desired Realm, create a client of OpenID Connect type, and set your desired Client ID.
2. Enable client authentication, then save the client.
3. Retrieve the Secret (from the credentials tab) of the Client you just created. You will need the Client ID and Secret in later steps.
4. Retrieve the discovery endpoint of the realm, https://<your-keycloak-host-and-realm>/.well-known/openid-configuration. This is accessible from “Realm Settings” > “General” Tab > OpenID Endpoint Configuration. You will need it in later steps.

​

Configuration at Dashboard

1. Log in to your Dashboard and select Identity Management, located under System Management
2. Create a profile, give it a name and select “Login to Tyk Dashboard”
3. Set the provider type as “OpenID Connect”
4. Fill in the Client ID, Client Secret and Discovery URL/endpoint from Keycloak (from steps 3 and 4 in Keycloak’s Side)
5. Copy the callback URL from Tyk and then you can click “Create Profile” to save the profile.
6. Go to Keycloak, and paste the callback URL you just copied to “Valid redirect URIs” in the Keycloak Client, and then save the client. This can be accessed by selecting the “Settings” tab when viewing a Keycloak client.

​

Test Keycloak Login

1. From your Identity Management Profiles click the profile you created to open it.
2. Copy the Login URL and paste it into a browser tab
3. You will now see the Keycloak login form.
4. Enter the email address and password of your Keycloak user.
5. You should now be redirected to the Tyk Dashboard and logged in

​

SSO with SAML

{
    "ActionType": "GenerateOrLoginUserProfile",
    "ID": "saml-sso-login",
    "OrgID": "{YOUR_ORGANIZATION_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"
}

​

Video Demonstration

​

SSO with LDAP

​

The High Level TIB Flow:

1. User makes an authentication request against the TIB endpoint, passing their credentials
2. TIB makes request against IDP using the credentials provided
3. TIB interprets the IDP response:
   • If successful then TIB creates a user session in the Dashboard and redirects the user to the Dashboard
   • If unsuccessful, TIB redirects the user to a failure URL

​

Steps for Configuration

1. Download TIB You can download TIB from the releases page of the TIB repository on GitHub. The release names contain the architecture and version i.e. tib-linux-<architecture>-<version>.tar.gz. This example uses amd64 and 0.2.1 for all the commands, but you should update them to use the latest version and relevant architecture for your platform. First step is to download TIB onto the environment:
   Copy

   Ask AI

   wget https://github.com/TykTechnologies/tyk-identity-broker/releases/download/v0.2.1/tib-linux-amd64-0.2.1.tar.gz
   

2. Extract and store TIB As the other Tyk components are installed in your /opt directory, we recommend you install TIB there too:
   Copy

   Ask AI

   tar -xvzf tib-linux-amd64-0.2.1.tar.gz
   

   TIB will now be extracted to the directory tib-0.2.1, let’s move this to /opt and change to that directory:
   Copy

   Ask AI

   sudo mv tib-0.2.1 /opt
   cd /opt/tib-0.2.1
   

3. Configure TIB There are two configuration files for TIB:
   1. tib.conf for the main application configuration settings
   2. profiles.json to configure the profiles which TIB will attempt to authenticate against
   Out of the box you don’t need to change much, but there are several attributes you should check to make sure they are correct for your environment:
   • Secret: The REST API secret used when configuring TIB remotely
   • TykAPISettings.GatewayConfig.Endpoint: The URL through which TIB can communicate with your Tyk Gateway
   • TykAPISettings.GatewayConfig.Port: The port through which TIB can communicate with your Tyk Gateway
   • TykAPISettings.GatewayConfig.AdminSecret: The secret required for TIB to communicate with your Tyk Gateway REST API - must match the secret property in your Gateway’s tyk.conf
   • TykAPISettings.DashboardConfig.Endpoint: The URL through which TIB can communicate with your Tyk Dashboard
   • TykAPISettings.DashboardConfig.Port: The port through which TIB can communicate with your Tyk Dashboard
   • TykAPISettings.DashboardConfig.AdminSecret: The secret required for TIB to communicate with your Tyk Dashboard Admin REST API - must match the admin_secret property in your Dashboard’s tyk_analytics.conf
   The tib.conf for this example is as follows (yours might require different values):
   Copy

   Ask AI

   {
     "Secret": "352d20ee67be67f6340b4c0605b044b7",
     "HttpServerOptions": {
       "UseSSL": false,
       "CertFile": "./certs/server.pem",
       "KeyFile": "./certs/server.key"
     },
     "BackEnd": {
       "Name": "in_memory",
       "ProfileBackendSettings": {},
       "IdentityBackendSettings": {
         "Hosts" : {
             "localhost": "6379"
         },
         "Password": "",
         "Database": 0,
         "EnableCluster": false,
         "MaxIdle": 1000,
         "MaxActive": 2000
       }
     },
     "TykAPISettings": {
       "GatewayConfig": {
         "Endpoint": "http://localhost",
         "Port": "8080",
         "AdminSecret": "352d20ee67be67f6340b4c0605b044b7"
       },
         "DashboardConfig": {
           "Endpoint": "http://localhost",
           "Port": "3000",
           "AdminSecret": "12345"
         }
     }
   }
   

4. Set up the LDAP profile TIB ships with a default profiles.json file which contains many example configuration for different scenarios. This guide is focused on LDAP authentication for the Dashboard, so we will update profiles.json to contain a single profile for this purpose. The key attributes for LDAP profile are:
   • ID: The ID by which we will activate the profile by calling the appropriate TIB endpoint
   • OrgId: The organization id which the profile is connected to - make sure this is the correct id for your organization (see the Dashboard Admin API documentation for details on how to retrieve this)
   • IdentityHandlerConfig.DashboardCredential: The Dashboard API Access credential which is used as authorization header
   • ProviderConfig.FailureRedirect: The URL which TIB will redirect to if the authentication fails
   • ProviderConfig.LDAPPort: The port through which TIB can communicate with your LDAP server
   • ProviderConfig.LDAPServer: The URL through which TIB can communicate with your LDAP server
   • ProviderConfig.LDAPUserDN: The distinguished name which TIB will use to identify the user - this should be updated to match your LDAP installation and must retain the *USERNAME* token as this is replaced by the actual username at runtime
   • ReturnURL: The URL which TIB will redirect to if the authentication succeeds - this should be the /tap endpoint of your Tyk Dashboard
   The profiles.json for this example is as follows (again, update values for your environment):
   Copy

   Ask AI

   [
     {
       "ActionType": "GenerateOrLoginUserProfile",
       "ID": "1",
       "OrgID": "59bfdf5b56c02c065d24638e",
       "IdentityHandlerConfig": {
           "DashboardCredential": "bb5735026be4400e67ed9801c2f1e2f9"
       },
       "ProviderConfig": {
         "FailureRedirect": "http://my-tyk-instance.com:3000/?fail=true",
         "LDAPAttributes": [],
         "LDAPPort": "389",
         "LDAPServer": "ldap.forumsys.com",
         "LDAPUserDN": "cn=*USERNAME*,dc=example,dc=com"
       },
       "ProviderName": "ADProvider",
       "ReturnURL": "http://my-tyk-instance.com:3000/tap",
       "Type": "passthrough"
     }
   ]
   

   Notice that this is a JSON array object with a single element; an LDAP profile. The LDAP server referenced by this profile is the freely-available service provided forumsys.com. See their documentation for more information. You can use any OpenLDAP compatible server.
5. Start TIB Start TIB by executing the TIB binary. This will produce an output log into the console which you can use to watch TIB process requests. Since TIB looks for the config file in the local directory, you should execute the application from there too.
   Copy

   Ask AI

   cd /opt/tib-0.2.1
   ./tib
   

   If all is well you should see TIB output a few messages when it starts:
   Copy

   Ask AI

   toth/tothic: no SESSION_SECRET environment variable is set. The default cookie store is not available and any calls will fail. Ignore this warning if you are using a different store.
   INFO[0000] Tyk Identity Broker v0.2
   INFO[0000] Copyright Martin Buhr 2016
   
   DEBU[0000] [MAIN] Settings Struct: {{http://localhost 8080 352d20ee67be67f6340b4c0605b044b7} {http://localhost 3000 12345}}
   INFO[0000] [MAIN] Initialising Profile Configuration Store
   INFO[0000] [IN-MEMORY STORE] Initialised
   INFO[0000] [MAIN] Initialising Identity Cache
   INFO[0000] [REDIS STORE] Initialised
   INFO[0000] [FILE LOADER] Loaded: 1 profiles from profiles.json
   INFO[0000] [MAIN] Broker Listening on :3010
   

   Start a new shell session to carry on with the remaining process.

6. Create a login page TIB works by having credentials sent to it, so a login page must be made in order to fulfill this requirement. For this example we will create a basic login form hosted by Nginx. We can’t just place the login page in our Dashboard directory as the Dashboard is not a standard web server, it only serves the pages which it has been compiled to serve. Any non-compiled page will produce a 404 response. Install Nginx and start it:
   Copy

   Ask AI

   sudo apt-get install nginx
   sudo service nginx start
   

   Nginx will now serve pages out of the default web root directory /usr/share/nginx/www. We now need to create a web page there. This command will pipe the echoed text into a file called login.html which is stored in the web root:
   Copy

   Ask AI

   echo \
   "<html> \
       <head> \
         <title>Tyk Dashboard LDAP login</title> \
       </head> \
       <body> \
         <form method="post" action="http://my-tyk-instance.com:3010/auth/1/ldap"> \
           username: <input type="text" name="username"/> <br/> \
           password: <input type="text" name="password"/> <br/> \
           <input type="submit" value="login"> \
         </form> \
       </body> \
   </html>" \
   | sudo tee /usr/share/nginx/www/login.html > /dev/null
   

   The login form contains two inputs named username and password. TIB looks for these exact parameter names when processing the request, so if you are creating your own login page you must use these input names. Please make sure you are using POST method in the form, to avoid browser caching. The form action http://my-tyk-instance.com:3010/auth/1/ldap is the TIB endpoint which will start the authentication process. The URL can be broken down as follows:
   • http://my-tyk-instance.com: The method and hostname used to connect to TIB - you should use HTTPS to prevent confidential data from being exposed
   • 3010: The default port for TIB
   • auth: The special TIB endpoint which accepts authentication requests
   • 1: The number of the profile which we are using - matches against the ID property of the profile in profiles.json
   • ldap: We need to add a string to the end of the request, so we have used ldap here
7. Update the Dashboard config Update the Dashboard config so that any unauthenticated requests are redirected to your custom login page. We do this by updating the sso_custom_login_url property of the Dashboard’s tyk_analytics.conf file, which by default is located in the /opt/tyk-dashboard directory. For example (ommitting all other lines in the config file and trailing comma):
   Copy

   Ask AI

   "sso_custom_login_url": "http://my-tyk-instance.com/login.html"
   

   Since the Dashboard runs on port 3000 by default, this URL will use the default HTTP port of 80 which will be handled by Nginx.
8. Test that it works Now that we have TIB installed and configured, Nginx installed and hosting our custom login page, and the Dashboard configured to redirect to that login page we can now test the solution. Remember that this example is using the LDAP provided at forumsys.com, so if you are using your own LDAP then substitute the username and password with appropriate values from your system.
   1. Open a web browser (if you’re already logged in to the Dashboard, logout now) and attempt to access the Dashboard - http://my-tyk-instance.com:3000
   2. This should be redirected to the custom login page - http://my-tyk-instance.com/login.html
   3. Enter read-only-admin as the username
   4. Enter password as the password
   5. Submit the form
   6. You should now be logged in to the Dashboard

​

Advance LDAP Configuration

​

Log into the Dashboard using LDAP

{
  "ActionType": "GenerateOrLoginUserProfile",
  "ID": "4",
  "OrgID": "{YOUR-ORG-ID}",
  "IdentityHandlerConfig": {
		"DashboardCredential": "ADVANCED-API-USER-API-TOKEN"
  },
  "ProviderConfig": {
    "FailureRedirect": "http://{DASH-DOMAIN}:{DASH-PORT}/?fail=true",
    "LDAPAttributes": [],
    "LDAPPort": "389",
    "LDAPServer": "localhost",
    "LDAPUserDN": "cn=*USERNAME*,cn=dashboard,ou=Group,dc=test-ldap,dc=tyk,dc=io"
  },
  "ProviderName": "ADProvider",
  "ReturnURL": "http://{DASH-DOMAIN}:{DASH-PORT}/tap",
  "Type": "passthrough" 
}

1. Two form fields called “username” and “password”
2. A basic auth header using the Basic Authentication standard form

​

Generate an OAuth token using LDAP

{
  "ActionType": "GenerateOAuthTokenForClient",
  "ID": "6",
  "IdentityHandlerConfig": {
    "DashboardCredential": "{DASHBAORD-API-ID}",
    "DisableOneTokenPerAPI": false,
    "OAuth": {
      "APIListenPath": "{API-LISTEN-PATH}",
      "BaseAPIID": "{BASE-API-ID}",
      "ClientId": "{TYK-OAUTH-CLIENT-ID}",
      "RedirectURI": "http://{APP-DOMAIN}:{PORT}/{AUTH-SUCCESS-PATH}",
      "ResponseType": "token",
      "Secret": "{TYK-OAUTH-CLIENT-SECRET}"
    }
  },
  "MatchedPolicyID": "POLICY-ID",
  "OrgID": "53ac07777cbb8c2d53000002",
  "ProviderConfig": {
    "FailureRedirect": "http://{APP-DOMAIN}:{PORT}/failure",
    "LDAPAttributes": [],
    "LDAPPort": "389",
    "LDAPServer": "localhost",
    "LDAPUserDN": "cn=*USERNAME*,cn=dashboard,ou=Group,dc=ldap,dc=tyk-ldap-test,dc=com"
  }
  "ProviderName": "ADProvider",
  "ReturnURL": "",
  "Type": "passthrough"
}

​

Log into the Developer Portal using LDAP

{
  "ActionType": "GenerateOrLoginDeveloperProfile",
  "ID": "5",
  "IdentityHandlerConfig": {
    "DashboardCredential": "822f2b1c75dc4a4a522944caa757976a"
  },
  "OrgID": "53ac07777cbb8c2d53000002",
  "ProviderConfig": {
    "FailureRedirect": "http://{PORTAL-DOMAIN}:{PORTAL-PORT}/portal/login/",
    "LDAPAttributes": [],
    "LDAPPort": "389",
    "LDAPServer": "localhost",
    "LDAPUserDN": "cn=*USERNAME*,cn=dashboard,ou=Group,dc=test-ldap,dc=tyk,dc=io"
  },
  "ProviderConstraints": {
    "Domain": "",
    "Group": ""
  },
  "ProviderName": "ADProvider",
  "ReturnURL": "http://{PORTAL-DOMAIN}:{PORTAL-PORT}/portal/sso/",
  "Type": "passthrough"
}

​

Using advanced LDAP search

• LDAPBaseDN - base DN used for doing LDAP search, for example cn=dashboard,ou=Group
• LDAPFilter - filter applied to the search, should include the *USERNAME*variable. For example: ((objectCategory=person)(objectClass=user)(cn=*USERNAME*))
• LDAPSearchScope - This specifies the portion of the target subtree that should be considered. Supported search scope values include: 0 - baseObject (often referred to as “base”), 1 - singleLevel (often referred to as “one”), 2 - wholeSubtree (often referred to as “sub”)

{
	"ActionType": "GenerateOAuthTokenForClient",
	"ID": "2",
	"IdentityHandlerConfig": {
		"DashboardCredential": "ADVANCED-API-USER-API-TOKEN",
		"DisableOneTokenPerAPI": false,
		"OAuth": {
			"APIListenPath": "oauth-1",
			"BaseAPIID": "API-To-GRANT-ACCESS-TO",
			"ClientId": "TYK-OAUTH-CLIENT-ID",
			"RedirectURI": "http://your-app-domain.com/target-for-fragment",
			"ResponseType": "token",
			"Secret": "TYK-OAUTH-CLIENT-SECRET"
		}
	},
	"MatchedPolicyID": "POLICY-TO-ATTACH-TO-KEY",
	"OrgID": "53ac07777cbb8c2d53000002",
	"ProviderConfig": {
		"FailureRedirect": "http://yourdomain.com/failure-url",
		"LDAPAttributes": [],
		"LDAPBaseDN": "cn=dashboard,ou=Group,dc=ldap,dc=tyk-test,dc=com",
		"LDAPEmailAttribute": "mail",
		"LDAPSearchScope": 2,
		"LDAPFilter": "(&(objectcategory=user)(sAMAccountName=*USERNAME*)(memberOf=CN=RL - PAT - T1-00002,OU=Role,OU=Security Roles,DC=company,DC=net))",
		"LDAPPort": "389",
		"LDAPServer": "ldap.company.com",
		"LDAPUserDN": "*USERNAME*@company.com"
	},
	"ProviderName": "ADProvider",
	"ReturnURL": "",
	"Type": "passthrough"
}

​

Custom Proxy Identify Provider

1. Response code: e.g. if this is an API request, a simple 200 response would suffice to act as a successful authentication.
2. Response body exact match: You can have a base64 encoded body that you would expect as a successful match, if the two bodies are the same, then the request will be deemed successful.
3. Regex: Most likely, the response might be dynamic (and return a response code, timestamp or other often changing parameter), in which case you may want to just match the response to a regex.

​

JSON Data and User names

​

Log into the Dashboard with the Proxy Provider

{
  "ActionType": "GenerateOrLoginUserProfile",
  "ID": "7",
  "OrgID": "{YOUR-ORG-ID}",
  "ProviderConfig": {
    "AccessTokenField": "access_token",
    "ExtractUserNameFromBasicAuthHeader": false,
    "OKCode": 200,
    "OKRegex": "",
    "OKResponse": "",
    "ResponseIsJson": true,
    "TargetHost": "http://{TARGET-HOSTNAME}:{PORT}/",
    "UsernameField": "user_name"
  },
  "ProviderName": "ProxyProvider",
  "ReturnURL": "http://{DASH-DOMAIN}:{DASH-PORT}/tap",
  "Type": "redirect"
}

​

JSON Web Encryption with OIDC

• Tyk Identity Broker v1.6.1+ or Tyk Dashboard v5.7.0+ (JWE feature is available from these versions and in all subsequent releases).
• An Identity Provider (IdP) that supports JSON Web Encryption (JWE)
• A certificate with a private key for Tyk (used to decrypt the ID token)
• A public key file for the IdP (used to encrypt the ID token)

​

Steps for Configuration

1. Prepare Encryption Keys

• Load the certificate with the private key into Tyk:
  • For embedded TIB in Dashboard: Use Tyk Dashboard’s certificate manager. In the below image you can see the module in dashboard that allows to upload certificates:
  • For standalone TIB: Store the certificate as a file accessible to Tyk
• Load the public key into your IdP for ID token encryption (process varies by IdP)

2. Configure the Identity Provider

• Create a new client in your IdP for Tyk Identity Broker

3. Setup OIDC Profile

• Create a new TIB profile:
  • Select Social > OIDC as the provider
  • Enter the client key and client secret from the IdP
  • Copy the callback URL from TIB and add it to the IdP client’s allowed redirect URLs
  
• Test the basic SSO flow to ensure it’s working correctly

4. Enable JWE

• Updated the TIB profile via API
  • Add the following fields to the ProviderConfig section:
    Copy

    Ask AI

    ...
    "ProviderConfig": {
      "JWE": {
        "Enabled": true,
        "PrivateKeyLocation": "CERT-ID"
      },
    ...
    

  • Set PrivateKeyLocation to either:
    • The certificate ID from the certificate manager, or
    • The file path where the certificate and private key are stored
• Update the IdP client configuration
  • Enable JWE for the client
  • Provide the public key for encryption

5. Verification

• Test the complete flow with JWE enabled to ensure proper functionality.

​

Troubleshooting

1. oauth2: error decoding JWT token: jws: invalid token received, not all parts available it means that JWE is not enabled in the profile and the IDP is already using JWE.
2. JWE Private Key not loaded Tyk encountered some issues while loading the certificate with the private key. Ensure that the path or certId are correct.