About TIB Profiles
Last updated: 7 minutes read.
What are the 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
| Field | Description | Required |
|---|---|---|
| ID | ID of the profile, is a string, use the name of the profile | |
| OrgID | Organization ID | Yes |
| ActionType | Which action is expected to be executed while using this profile, valid values are:
|
Yes |
| Type | Valid values are:
|
Yes |
| CustomEmailField | Name of the claim associated with the email value stored in the IDP (Identity Provider). | No |
| CustomUserIDField | Name of the claim associated with the User ID value stored in the IDP (Identity Provider). | No |
| IdentityHandlerConfig.DashboardCredential | API Key that will be used to consume the dashboard API to issue nonce codes and validate user data | yes |
| ReturnURL | Where to redirect and send the claims from the IDP on login. For dashboard SSO it would be http://dashboard-host/tap. For classic portal SSO it would be http://{portal-host}/sso |
yes |
| DefaultUserGroup | When mapping groups, if not found the group then to which one fallback | No |
| CustomUserGroupField | When mapping groups, if a group is not found, specify which group to fallback to. | No |
| UserGroupMapping | Map that contains the matching between Tyk groups and IDP group. | No |
| UserGroupSeparator | The IDP might send the groups to which the user belongs to as a single string separated by any symbol or empty spaces, with this field you can set which symbol to use to split as an array | No |
| SSOOnlyForRegisteredUsers | A boolean value to restrict the SSO only to users that already exists in the database. Users that do not exist in the database and successfully logins in the IDP will not have access to tyk | No |
LDAP profile fields
| Field | Description | Required |
|---|---|---|
| LDAPUseSSL | Whether to connect with the LDAP server via TLS, e.g. true or false | No |
| LDAPServer | LDAP Server address, e.g. ldap://hostname. | Yes |
| LDAPPort | LDAP Port, e.g. 389 or 636. | Yes |
| LDAPUserDN | Required to uniquely identify and locate a user’s entry in the LDAP directory | Yes |
| LDAPBaseDN | Distinguished Name from where the search will start | No |
| LDAPFilter | Used for filtering in the LDAP server | No |
| LDAPEmailAttribute | The name of the field in the LDAP schema that represents the user’s email. Defaults to mail. | No |
| LDAPFirstNameAttribute | The name of the field in the LDAP schema that represents the user’s first name. Defaults to givenName | No |
| LDAPLastNameAttribute | The name of the field in the LDAP schema that represents the user’s last name. Defaults to sn. | No |
| LDAPAdminUser | Admin user name | No |
| LDAPAdminPassword | Admin password | No |
| LDAPAttributes | List of attributes to return when a matching LDAP record is found, for example [‘cn’, ‘mail’, ‘ou’] | Yes. It can be an empty list |
| LDAPSearchScope | The scope is an integer value that determines the depth of the search in the directory hierarchy | No |
| FailureRedirect | In the event of a login failure this is the URL that the user will be redirected to. | Yes |
| DefaultDomain | Domain in which the LDAP is running. Used to build the username but not to perform the requests. | No |
| GetAuthFromBAHeader | A boolean value that, when set to true, instructs TIB to gather the user and password from the Authorization header when handling the request. | No |
| SlugifyUserName | When set to true enhance the username so that is URL friendly. | No |
ProxyProvider profile fields
| Field | Description | Required |
|---|---|---|
| TargetHost | URL of the server | Yes |
| OKCode | This is an integer represents the HTTP status code that represents a successful response from the target service. If the response code matches this value the identity broker treats it as a successful interaction. | No. But one of OKCode, OKResponse, or OKRegex should be filled |
| OKResponse | This field specifies a particular string that should match with the response body to be considered successful. | No. But one of OKCode, OKResponse, or OKRegex should be filled |
| OKRegex | Is used to validate the content of the response beyond just the HTTP status code. If the response body contains data that matches this regular expression, it is considered a successful response. | No. But one of OKCode, OKResponse, or OKRegex should be filled |
| ResponseIsJson | This parameter helps the identity broker understand how to interpret the response body from the target service. If ResponseIsJson is set to true, the broker will expect the response to be in JSON format and will process it accordingly. This includes parsing JSON data to extract relevant information. This is a boolean field. | No |
| AccessTokenField | The name of the field that contains the access token. | No |
| UsernameField | The name of the field that contains the username. | No |
| ExrtactUserNameFromBasicAuthHeader | A boolean value that, when set to true, instructs TIB to gather the user and password from the Authorization header when handling the request. | No |
Social profile fields
| Field | Description | Required |
|---|---|---|
| CallbackBaseURL | URL to be redirected on success login | Yes |
| FailureRedirect | URL to be redirected on failure | Yes |
| UseProviders.Name | Name of the provider to be used. Valid values: gplus, github, twitter, linkedin, dropbox, digitalocean, bitbucket, salesforce, openid-connect |
Yes |
| UseProviders.Key | Oauth Client key | yes |
| UseProviders.Secret | Oauth Client Secret | yes |
| UseProviders.DiscoverURL | used to dynamically retrieve the OpenID Provider’s configuration metadata, including endpoints and supported features, in JSON format from /.well-known/openid-configuration. | Only required when using openid-connect |
| UseProviders.Scopes | Specifies the level of access or permissions a client is requesting from the user and the authorization server, for example [“openid”,“email”]. | No, however when using openID the scope ‘openid’ should be added |
| UseProviders.SkipUserInfoRequest | Determines whether to bypass the UserInfo endpoint request, improving performance by relying on the ID token alone for user details. | No |
| JWE.Enabled | When set to true, JWE will be enabled, allowing Tyk to decrypt the ID token received from the IdP. If set to false, the ID token will not be decrypted. | No |
| JWE.PrivateKeyLocation | Specifies the path or identifier (certid) for the certificate that contains the private key used to decrypt the ID token when JWE is enabled. This certificate must be in PEM format and include both the public certificate and the private key. | Is only required if JWE is enabled |
SAML profile fields
| Field | Description | Required |
|---|---|---|
| IDPMetadataURL | This is a URL, e.g. https://login.microsoftonline.com/your-tenant-id/federationmetadata/2007-06/federationmetadata.xml, that links to XML metadata containing information necessary for interaction with SAML-enabled identity or service providers. The document contains example URLs of endpoints, information about supported bindings, identifiers and public keys. Once you create your TIB profile you can find the SP metadata file under {Dashboard HOST}/auth/{TIB Profile Name}/saml/metadata |
Yes |
| CertLocation | An X.509 certificate and the private key for signing your requests to the IDP. The value for CertLocation should be the path to a single file with the cert and key concatenated, e.g. /etc/ssl/certs/example_cert.pem. When used in an embedded TIB instance in the dashboard then the CertLocation value can be the certId from the certificate manager. For further details please refer to SSO with SAML |
Yes |
| SAMLBaseURL | The host of TIB, e.g. http://tyk-dashboard:3000/, 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. |
Yes |
| ForceAuthentication | Ignore any session held by the IDP and force re-login every request. Defaults to false | No |
| SAMLBinding | 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 | No |
| 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 | No |
| 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 | No |
| 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 | No |
| FailureRedirect | URL to redirect the user if the login is not successful | Yes |
| EntityId | It is used to distinguish between different entities (IDP & SP) and ensure proper routing and validation of SAML assertions and requests. Defaults to the value set in the field IDPMetadataURL |
No |
Examples
Depending on your authentication protocol you might find some working examples in the following links: