OpenID

Introduction to OpenID

Indicium

Indicium 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

note

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

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

1. In the OpenID connect group, deselect Allow local accounts.

note

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

1. Execute the Reload scopes and claims task .

2. 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.

note

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

note

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.

note

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

1. 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.

2. 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.

note

Other than IAM, no website ever sees your password.

menu OpenID > OpenID resources

Configure OpenID resources