OpenID
Introduction to OpenID
IndiciumIndicium supports authentication through third-party authentication providers that support OpenID. This makes it possible to authenticate users through Azure Active Directory, Google, GitHub, Facebook, and many other authentication providers. In that case, the Thinkwise Platform is the OpenID client.
- Integrate one or more external OpenID Identity Providers.
- It is possible to use provisioning.
Indicium can also act as the OpenID provider, allowing external websites to authenticate the accounts registered in IAM, delegating the authentication process to the Thinkwise Platform. In that case, the Thinkwise Platform is the OpenID provider.
- Enable websites to use the Thinkwise platform as OpenID provider.
- Control which information is shared with that website by configuring the claims of the OpenID resources.
- Indicium automatically creates a certificate if OpenID clients are configured in IAM. The Thinkwise platform has several options for centralizing the storage of this certificate.
If you are planning or have multiple Indicium instances, it is important to read this information. See: Signing OpenID Server certificates.
Register OpenID identity providers
- OpenID Connect defines several authentication flows, but only Identity Providers that use the
Authorization Code flow
can be integrated into Indicium. - Only main administrators can register OpenID providers.
It is possible to integrate multiple external Identity Providers. You can freely choose a name for each configuration, for example, "Microsoft", or "Google".
An environment can support both local accounts (IAM-, database- or Windows authentication) as well as external accounts (via one or more OpenID Identity providers). In that case, Indicium will show a login screen like the one below:
- If only one option is available, this page will not show at all, and the option will be handled as the default option. This allows for a seamless single-sign on experience where the user is always directly guided to the OpenID Provider during the authentication process.
- Remember my choice - a user can check this box to set a cookie for skipping the login page the next time. This way, each user can make their own choice.
- Sign in with local account - it is possible to disable signing in with a local account if, for instance, you only want to allow users to log in with an external Identity Provider. If signing in with a local account is disabled, no logout button is displayed for the local account either. See Disable signing in with a local account.
Multiple login options allowed
To register an OpenID identity provider:
menu Authorization > OpenID providers > tab Form
Enter the following General data:
Field | Description |
---|---|
Identity provider | The name to identify this provider. For instance, Azure AD. |
Metadata endpoint | The location of the OpenID configuration at the identity provider's server. This URL generally ends with /.well-known/openid-configuration . |
Client ID | To be retrieved from the OpenID provider. |
Client secret | To be retrieved from the OpenID provider. |
Identifying claim | Used to match users between the identity provider and IAM. When the identity provider receives proof of authentication, it uses the identifying claim to find the user in IAM. Generally, you should select the 'sub' claim here. Only deviate from 'sub' with caution. |
IAM uses the value of the Identifying claim (the user ID or the user's email address) to find the user.
- If the email address is a valid identification for users in IAM and the user ID is set arbitrarily (unrelated to OpenID), you may choose to select
email
as identifying claim. We do not recommend this, especially when using provisioning, since the user's email address may change over time. If that happens, it will be seen as a different user. - It is also possible to use an entirely different claim to match the authenticated user to an IAM account. The same rule applies: use with caution.
The following settings are available:
Setting | Description |
---|---|
Prompt | - Consent - Opens a consent dialog after signing in, asking the user to grant permissions. - Login - Forces the user to enter their credentials, negating single-sign on. - Select account - Sends the user to an account picker where all accounts remembered in the session will appear. - If left empty, the server decides. This offers a seamless login if a user is logged in already. |
Allow all issuers | If your organization has multiple Azure ADs, but wants a single sign-in button, select this checkbox to supply a list of tenants of all your AzureADs. |
Allow additional issuers | If you select this checkbox, you have to configure additional issuers in the tab Valid issuers. ![]() |
Provisioning enabled | Select this checkbox to automatically create and update users based on the information provided by the OpenID provider when a user logs in. You can configure a template before you enable provisioning. |
The following button options are available:
Option | Description |
---|---|
Sign in button icon | Select an icon for the sign-in button. |
Sign in button text | Select a text for the sign-in button. |
Sign out button icon | Select an icon for the sign-out button. |
Sign out button text | Select a text for the sign-out button. |
Register OpenID providers
Disable signing in with a local account
It is possible to disable signing in with a local account if, for example, you only want to allow users to log in with an external Identity Provider.
If signing in with a local account is disabled, no logout button will be available for the local account, either.
menu Settings > Global settings > tab Form > tab Global settings
- In the OpenID connect group, deselect Allow local accounts.
This only affects the end-user login flow when using a browser. Local accounts are still enabled and can still be used as service accounts when directly accessing services.
Log for login via OpenID providers
A log for login attempts is available, showing all attempts and providing extra information about any provisioning.
menu Authorization > OpenID providers > tab Login attempts
Here, you can also find errors that occurred during the creation or update of a user.
If an error occurs, a user will not be able to log in, but for one exception - when provisioning only fails to update the user's first- or last name, the login will continue as these values are not paramount for authentication or security.
Provisioning (OpenID providers)
Automatically create or update users
If you want to enable provisioning (see Register OpenID providers), you can set up a template to automatically create or update users in IAM, based on the claim values received from the OpenID provider. Users will be created and updated if they return authenticated from the OpenID provider.
You can configure the template before you enable provisioning.
menu Authorization > OpenID providers > tab User template
A number of fields in the user template are available for mapping.
- Claim values - User fields that you can set to the value of a claim.
- Default values - These will be applied when no value is received for the claim or if the provided claim value cannot be parsed to the right format.
Create a template for creating and updating users
Update scopes and claims
Scopes and claims can be updated in two ways.
After you have added a new OpenID provider or updated the metadata URL of an existing OpenID provider, you will be prompted to update the available scopes and claims using the metadata endpoint.
You can also reload the scopes and claims manually:
menu Authorization > OpenID providers > all tabs
Execute the Reload scopes and claims task
.
Select Yes to the following message to visit the URL and update the registered scopes and claims available for the provider.
"Do you want to load the scopes and claims using metadata endpoint
https://login.microsoftonline.com/name/version/.well-known/openid-configuration?
"
You can modify scopes and claims if the information cannot be loaded automatically from the metadata document.
Manually modify requested scopes
menu Authorization > OpenID providers > tab Scopes
The scopes allow you to request specific information about users. They may also request to allow certain privileges, so be aware not to enable more than needed. Not all scopes are necessary to retrieve the desired claims for user matching or provisioning. We advise you to request as few scopes as possible.
- openid - The openid scope is always requested.
- profile - Deselect if, for example, your Identity Provider does not support the profile scope.
- email - Some Identity Providers (such as Google) will only provide the email claim type if the email scope is requested specifically by the client.
See also Manually update mappable claims.
Modify scopes to request user information
Manually update mappable claims
menu Authorization > OpenID providers > tab Claims
Claims are bits of information about the user that become available when certain scopes are requested. Which scopes are required to retrieve the available claims is unknown and should be checked with the OpenID provider. For example, some OpenID providers include the email claim in the openid scope. Others require you to request the email scope to which the end-user may have to consent.
- sub - The sub claim (meaning: subject) has a value that uniquely identifies the user with the OpenID provider. This claim is always available as it is mandatory to include it in the openid scope.
- iss - The iss claim (meaning: issuer) is a special claim, only available if all issuers are allowed or additional issuers are allowed. This claim contains the issuer's URL.
The information you specify here, can also be used for mapping the values of a claim to known values in IAM.
- A cloud-based Azure AD Group that is not inherited from a local AD group only provides the Group ID, not a sAMAccountName.
- In Azure AD, you can add the groups claim in menu App registration > Token configuration > Add groups claim.
See also:
Manually modify requested scopes
Value mapping for categorical user fields.
Modify claims to specify the information you expect to retrieve, so it can be used for mapping
Add and map claims for Azure AD user provisioning
When setting up Azure AD User Provisioning, you need to add and map the following claims in IAM manually:
- given_name, mapping to First name in the IAM User Template.
- family_name, mapping to Surname in the IAM User Template.
- groups, mapping to User Group in the IAM User Group Template.
After adding claims, Indicium needs to be restarted.
Value mapping for categorical user fields
It is not always possible to directly use a Claim value as a Tenant, User id, Gender, Application language, or Time zone. These are categorical values in IAM, often not known by the OpenID provider and unlikely to be included in the same format in the claims. For example, you may want to map the iss (issuer URL) claim value to a tenant in IAM or a locale or country claim value to an application language in IAM.
To allow this, you can provide a value mapping for a number of categorical user fields:
menu Authorization > OpenID providers > tab User template
- Tenant - tab Tenant value mapping.
- Gender - tab Gender value mapping.
- Application language - tab Language value mapping.
- Time zone - tab Time zone.
In these tabs, you can map the values of the chosen claim to known values in IAM. A value mapping for these user fields will become available when the claim to be used has been set.
If the Claim value does not match any mapping, the Default value configured in the user template will be used. So, if a mapping is available, the claim value will not be used. In reverse, if a claim has been configured but no mapping specified, the Claim value will be used.
Tenant value mapping in a user template
For a value to be applied, the claim will have to equal the provided value or, if the claim is a JSON array, will have to contain an element that equals the value. So, multiple matches are possible, but only one value will be picked for the user to provision. In that case, the priority (ascending) will be used to pick a value.
Using the example below, if the locale claim contains the value {"en-GB", "de", "fr" }
, the application language DE will be selected, as it is the first
matched value with a higher priority than ENG.
The Application language and Time zone will only be set once and not be updated to prevent the provisioning mechanism from overriding user preferences.
Example: Language value mapping
User groups for provisioning
If you configure user groups, they can be automatically created or updated for the user.
You can specify a user group multiple times. If a user group is mapped via multiple conditions, only one of them needs to be satisfied.
menu Authorization > OpenID providers > tab User template > tab User groups
- User groups without a Condition will always be provided to the user.
- If a Condition is active, the claim will have to equal the provided value or, if the claim is a JSON array, contain an element that equals the value.
- A granted user group belonging to a tenant that does not match the assigned tenant for the user will be ignored.
Configure user groups
Enable websites to use the Thinkwise Platform as OpenID provider
With OpenID, you can use an existing IAM account to sign in to another website, allowing the other website to delegate the authentication process to the Thinkwise Platform as a provider. In that case, you need to configure these websites as OpenID clients.
menu OpenID > OpenID clients
Enter the required information.
- Require PKCE - Deselect if Proof of Key for Code Exchange (PKCE) is not required.
This option is by default enabled for new OpenID clients as of platform version 2022.2. For OpenID clients created earlier, it is by default disabled.
- Require PKCE - Deselect if Proof of Key for Code Exchange (PKCE) is not required.
Set which information is shared with the visited website. See Configure OpenID resources.
Configure OpenID clients
Configure OpenID resources
If the Thinkwise Platform acts as a provider, information is shared between IAM and the website, for example, name, department, or email address. You can control which information is shared with the visited website by configuring the OpenID resources claims.
Your (salted and hashed) password is known only by IAM. These data are used to confirm your identity at the websites you visit.
Other than IAM, no website ever sees your password.
menu OpenID > OpenID resources
Configure OpenID resources