Identity provider configuration
The Token Server has no user management. The Token Server depends on external identity providers (IdP) to identify a user. The Token Server supports multiple integrations with identity providers out of the box. Custom integrations are also supported.
Go to Configuration
and then to Identity providers
to configure identity providers in the admin console.
- General configuration
- Configure a SAML Identity Provider
- Configure a Header Identity Provider
- Configure a Two way OTP Identity Provider
- Configure an OAuth Identity Provider
- Configure a custom Identity Provider
- Configure a Two way OTP API Identity Provider
- Configure a Custom API Identity Provider
- Configure User Info endpoint
- Attribute mapping
General configuration
The following properties can be set for each type of identity provider:
- Type: the type of this identity provider. The type cannot be changed later.
- Identifier: the id of the identity provider. This uniquely identifies the IdP and cannot be changed later.
- Name: a human readable name of the identity provider. This name is not shown to the end user, only to administrators.
- Default: an identity provider can be assigned to an application. When no identity provider is specified for an application, the default identity provider is used.
- Enabled: flag to enable/disable this identity provider.
Additionally, for those identity providers that expose identity via API, it is possible make Token Server aware of this API. See Configure User Info endpoint for further details.
Configure a SAML Identity Provider
By default the endpoints required for SAML in the Token Server are disabled. These endpoints should be enabled via SAML Service Provider Configuration SAML Service Provider enabled
to use the SAML IdP integration.
When the SAML IdP functionality is used the Token Server acts as a SAML service provider. The metadata of the service provider can be configured via SAML Service Provider Configuration. In the SAML IdP the Token Server has to be configured as service provider. Please refer to Configuring the Metadata of the SAML Service Provider for more information.
The Entity ID must be configured in the Token server for a SAML IdP. The Entity ID in the configuration of Token Server should be equal to the Entity ID in the metadata of the IdP.
There are two options to specify the IdP metadata:
- 'Dynamic via URI' - the metadata is automatically fetched from provided url - typically Saml Identity Provider. This is the recommended option as the refresh of the metadata is handled automatically.
- 'Static XML' - the complete XML representing Saml metadata is provided directly as a static text. When using this option make sure that metadata has sufficient expiry date and keys within the metadata are up-to-date.
The Token Server supports multiple certificates in the metadata in order to migrate to a new certificate smoothly.
The Token Server supports IdP initiated SAML Single Logout (SLO). By enabling SLO, the IdP is able to terminate sessions at the Token Server. This means that when a user logs out at the identity provider, the Token Server will receive a request to revoke all access tokens and grants associated with that session. This feature is only available for web clients that do not make use of refresh tokens.
Note: The SLO enabled checkbox is available in the form if and only the SAML Service Provider Configuration
SLO enabled
is enabled.
By default only the user id of the user is mapped based on the name id available in the SAML assertion. By adding an attribute mapping more user attributes
from the SAML assertion can be used. When creating an attribute mapping both the Name
or FriendlyName
of a SAML attribute can be used. Example:
The Token Server supports free format attribute names. All attributes (including the non default ones) are available in the token introspection response and in the consent template. A set of default attributes is available that can lead to different behavior in the Token Server:
- userId
- authenticationLevel
- firstName
- lastName
- phoneNumber
- languageCode
Configure a Header Identity Provider
When using the header IdP, the identity of the end-user must be provided via HTTP-headers to the Token Server. The headers must be set by a trusted entity in the network. For example a WebSEAL instance or another kind of reverse proxy. This entity is responsible for stripping headers which are set by untrusted parties (e.g. coming from the internet).
Headers can be mapped to user attributes based on the configured attribute mapping. A default attribute mapping is available out of the box. Only mappings that differ from the default mapping have to be configured. A non standard user attribute can also be defined using an attribute mapping.
Default mapping:
User attribute | Header | Description |
---|---|---|
userId | userId | The identifier of the user |
authenticationLevel | authenticationLevel | A value indicating the authentication level of the user, this value is free format and should be interpreted by external systems |
firstName | firstName | First name of the user |
lastName | lastName | Last name of the user |
The email address of the user | ||
phoneNumber | phoneNumber | The phone number of the user |
localeCode | languageCode | The locale of the user, used to localize the pages served by the Token Server. |
A language code can also be provided via a cookie value. When the cookie is specified it will overrule the language code set in the header. The cookie name used for to overrule the language code header and the default language code can be set via the following Docker Compose environment variables.
Configure a Two way OTP Identity Provider
A Two way One Time Password (OTP) IdP generates two random strings. The first one is generated in the session on the mobile device. A second one is generated when the users starts a new session on a system that knows the identity of the user, for example a self service environment. An api is available for this system to interact with the Token Server. By entering the generated values in the different sessions a user can be linked to a mobile device.
A description on how to configure the access to the api can be found in the API configuration topic.
Optionally a scope validation service can be used to verify that a user has access to the requested scopes. A scope validation service can be configured via Docker Compose environment variables. This is only the first step of enabling scope validation services. For the second part of the scope validation configuration see the scopes topic.
Attribute mappings are not used in this IdP.
A user has limited time to complete the identification process using the two way otp IdP. When this time has exceeded the user is presented with the failure
without recovery (dead end) page
The process uses a cookie to identify the authentication transaction. The authentication transactions are kept in memory
on the server side for a limited amount of time. The amount of time the transaction exists server side (and the cookie expiry time) can be configured via the User authentication session TTL
property.
Configure an OAuth Identity Provider
The Token Server can act as an OAuth client for an identity provider that acts as an OAuth authorization server. The Token Server then uses the OAuth authorization code flow to obtain an access token and uses that access token to get user information.
The following properties can or must be set for the OAuth Identity Provider:
Property | Example | Required | Description |
---|---|---|---|
Client ID | jeguighreuwih8792459uht893 | Yes | The identifier for the Token Server in the OAuth IdP. |
Secret | fjerfr9uf089rf908f90refeef | Yes | The secret for the Token Server in the OAuth IdP. |
Authorization URL | https://example.com/oauth/authorize | Yes | URL to start the authorization without request parameters. These are added by the Token Server. |
Token URL | https://example.com/oauth/token | Yes | URL to exchange the access grant for an access token without request parameters. These are added by the Token Server. The URL is called via HTTP POST. The client id and secret are sent via the HTTP Authorization header (Basic authentication). |
Profile URL | https://example.com/me | Yes | URL for an OAuth resource call that returns a user profile. The URL is called via HTTP POST. The access token is sent via the HTTP Authorization header with a Bearer token. |
Scopes | profile | No | Scopes that are needed for getting the user profile. Multiple scopes must be separated by a space. An empty value is allowed. |
The host, protocol and context are taken from a Docker Compose environment variable TOKEN_SERVER_COMMON_ENGINE_BASE_URI
and must denote the public hostname on which the Token Server instance can be reached from the internet. The context root of the Token Server engine can optionally be set via Docker Compose environment variable:
TOKEN_SERVER_COMMON_ENGINE_CONTEXT_ROOT
.
During the OAuth authorization flow the user is redirected back from the OAuth IdP to the Token Server. This redirect URL is the engine base URI + the engine
context root + /oauth-idp/callback
.
Example: https://token-server.example.com/oauth/oauth-idp/callback
.
Attribute mappings are currently not supported in this IdP. The Token Server expects the profile in the following structure to extract the user identifier:
{
"userId" : "user-1234"
}
Configure a custom Identity Provider
For a custom IdP only general IdP properties can be set via the Token Server admin console. Other configuration must be set as described in the documentation of this custom identity provider.
The type of the custom IdP is set by specifying its Spring bean name via a Docker Compose environment variable.
Configure a Two way OTP API Identity Provider
This identity provider gives nearly identical functionality to the browser based Two way OTP Identity Provider but uses an API approach. This is useful for the app developers as they can implement Two way OTP without using a browser and provide a more cohesive user experience.
For more information on the Identity Provider refer to the Two way OTP API topic guide.
Configure a Custom API Identity Provider
Custom API Identity Providers can be either One Step
or Two Step
. These Identity Providers utilize the Extension Engine to execute custom JavaScript to
validate the registration. Scripts should be supplied when configuring this Identity Provider. Two Step
requires an Init registration
and
Complete registration
script while One Step
only requires a Complete registration
script. Both can have an optional script for
Backchannel communication
, but that is not required.
For more information on the Identity Provider refer to the Custom Registration topic guide.
See the Example Scripts for help creating the scripts.
Configure User Info endpoint
For any type of the Identity Provider, it is possible to configure an endpoint which the Token Server will use as a source of user identity attributes. It is used to expose UserInfo and populate ID Token with claims in OpenID Connect flows or in the Token Introspection response. This endpoint needs to be compliant with the Person API. The reference implementation of this API is provided by CIM. Refer to CIM documentation for API specification and instructions how to enable it.
- Enabled: indicates whether identity attributes may be retrieved via API
- Identity source URL: Url of the Person API compliant endpoint
- Username: username that shall be used when accessing API
- Password: password that shall be used when accessing API
The calls to the API are cached. The TTL of this cache can be configured as described in Cache Configuration
Attribute mapping
Identity Provider attributes
Some of the identity providers are capable of providing user attributes during authorization. These attributes are associated with respective access tokens and are available as a key-value pair for an inspection via Token Introspection API.
By default the attributes are stored under the original keys, but it is possible to override that behaviour by defining a custom mapping. If at least one custom mapping is defined, only those attributes that are configured are mapped. Name of the attributes are case-sensitive.
Since these attributes are stored during authorization, the Token Server has no means to resynchronize them afterwards. This results in the data potentially being stale. To overcome this limitation, please consider leveraging the Person API integration.
Person API attributes
If the Person API integration is enabled, the Token Introspection API returns both the identity provider attributes and all non-empty attributes from Person API. Here is a list of currently supported attributes:
first_name
last_name
gender
birth_date
locale
email
email_verified
phone_number
phone_number_verified
street_name
house_number
house_number_addition
city
region
country
postal_code
Attributes provided by both the identity provider and the Person API can be remapped using custom mappings. If at least one custom mapping is defined, only those attributes that are configured are mapped. Name of the attributes are case-sensitive.