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

Introduction

Tyk Identity Broker (TIB) is a solution for integrating various Identity Management Systems (such as LDAP, Social OAuth, Okta) with your Tyk installation.

With TIB, you gain the flexibility to connect your existing user directories to Tyk Dashboard or Developer Portal, streamlining access management and enhancing security. Whether you’re looking to implement SSO, leverage social logins, or integrate with enterprise identity providers, TIB provides the tools and configurations to make it happen.

This page introduces general features of Tyk Identity Broker (TIB) and how to configure them. If you are looking for global configurations of the TIB deployment refer this config file.

What is Tyk Identity Broker (TIB)?

Tyk Identity Broker (TIB) is a component providing a bridge between various Identity Management Systems such as LDAP, Social OAuth (e.g. GPlus, Twitter, GitHub) or Basic Authentication providers, to your Tyk installation.

TIB can act as a bridge between the API Gateway, Tyk Portal or even the Tyk Dashboard, and makes it easy to integrate custom IDMs to your system.

Starting from Tyk v3.0 TIB has been added as a built-in feature of the Tyk Dashboard. You no longer have to setup a separated instance of the service to make it work with the Dashboard. You now have two options:

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.

What can you do with the Tyk Identity Broker (TIB)?

By using the identity broker in conjunction with an IDP you have the ability to perform actions such as:

• 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)

TIB provides a simple API through which traffic can be sent. The API will match the request to a profile which then exposes two things:

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

Identity providers can be anything, as long as they implement the tap.TAProvider interface. Bundled with TIB at the moment you have four provider types:

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

An identity handler will perform a predefined set of actions once a provider has validated an identity. These actions are defined as a set of action types:

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

TIB takes as input one or many profiles that are stored in mongo or a file (it depends on the type of installation), a profile is a configuration that outlines of how to match a identity provider with a handler and what action to perform (Example: enable Dashboard SSO using OpenID and Microsoft Azure as IDP). The Dashboard adds a user interface to manage the profiles.

Anatomy of a Profile

Each profile is outlined by a series of attributes that will describe: action to perform, IDP to connect, URL’s to redirect on success and failure, etc. In order to know and understand each of the attributes, implications as well as configure your own profile please consult the profile structure below:

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)

There are two ways to install 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

Pre-requisites

Below are the prerequisites of TIB:

• 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

For the embedded TIB you don’t have to do anything, only ensure that in the Dashboard’s config file identity_broker is not pointing to an external service, and identity_broker.enabled is set to true. For example:

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

This settings behaves as follows:

• 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

Below are the three deployment options to install TIB as a standalone application:

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

To secure session cookies within Tyk Identity Broker (TIB) when integrating with social providers, setting the TYK_IB_SESSION_SECRET environment variable is crucial. This variable plays a pivotal role in hashing session cookies, thereby enhancing security. By default, if this variable isn’t explicitly set, TIB falls back to using the Tyk Dashboard’s admin_secret when it’s embedded in the dashboard.

For a seamless and secure setup, start by generating a strong, unique secret string. It is recommended to use a string with 32 or 64 bytes to ensure optimal security, this string will be your session secret. In a Linux, Unix, or MacOS environment, you can set this variable by running the command export TYK_IB_SESSION_SECRET='your_secret'.

Setting Absolute Paths

No command line arguments are needed, but if you are running TIB from another directory or during startup, you will need to set the absolute paths to the profile and config files:

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")

See how to configure TIB

Exploring Tyk Identity Broker REST API

Refer to this document

Single Sign On (SSO)

SSO gives users the ability to log in to multiple applications without the need to enter their password more than once. Authentication protocols such as OpenID Connect and SAML enable 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).

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:

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

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