OpenID

Introduction to OpenID

Indicium main administrator

Indicium supports authentication through third-party authentication providers that allow OpenID. The Thinkwise Platform can be used as the OpenID client or as the OpenID provider:

• The Thinkwise Platform as OpenID client - Authenticate users through Azure Active Directory, Google, GitHub, Facebook, and many other authentication providers.

  • Integrate one or more external OpenID identity providers. See Register OpenID Identity Providers.
  • Use provisioning. See Provisioning.

• The Thinkwise Platform as OpenID provider - Indicium acts as the OpenID provider, allowing external websites to authenticate the accounts registered in IAM.
  See the Client applications guide.

OpenID identity providers

Register OpenID identity providers

Indicium main administrator

note

OpenID Connect defines several authentication flows, but only Identity Providers that use the OAuth Authorization code grant type can be integrated into Indicium.

It is possible to integrate multiple external Identity Providers.

To register an OpenID identity provider:

menu Authorization > OpenID providers > tab Form

1. Enter an Identity provider name. You can freely choose a name for each configuration, for example, "Microsoft", "Google", or "Azure AD".

2. Enter the Metadata endpoint. This is the location of the OpenID configuration at the identity provider's server. This URL always ends with /.well-known/openid-configuration. For more information about the endpoints in Azure AD, see Azure Active Directory endpoints.

3. Enter the Client ID as retrieved from the OpenID provider.

4. Enter the Client secret as retrieved from the OpenID provider.

   3-TIER ONLY

   You can encrypt a client secret in a 3-tier setup, where IAM is used in the Universal GUI. See Encrypt a secret for more information.

5. Select an Identifying claim. When the identity provider receives proof of authentication, IAM uses the identifying claim to find the user. Generally, you should select the sub claim here. Only deviate from sub with caution. See Identifying claim to find a user.

Register OpenID providers

Encrypt a secret

Indicium 3-tier IAM in the Universal GUI main administrator

You can encrypt the client secret for OpenId providers in the database.

3-TIER ONLY

Encryption is only available in a 3-tier setup, where the Software Factory and IAM are used in the Universal GUI. It is not available for the Software Factory and IAM for the 2-tier Windows or Web GUIs because it requires Indicium support and configuration.

Prerequisite for storing a client secret: configure the encryption in Indicium (appsettings.json) for the platform you are using. See Indicium encryption.

To store the client secret for OpenId Providers:

menu Authorization > OpenID providers > tab Form

1. Execute the task Encrypt OpenID provider to add an encrypted client secret to a provider.

Prompt for OpenID login

Indicium main administrator

To select what happens when a user logs in with an OpenID identity provider:

menu Authorization > OpenID providers > tab Form

1. Select a Prompt:

   • Consent - Opens a consent dialog after signing in, asking the user to grant permissions.
   • Login - Forces the user to enter their credentials, undoing 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 everyone to log in

Indicium main administrator

If you do not know who is going to log in to your application, you can create a public login screen. Use this, for example, in a business-to-anyone, a business-to-business, or a business-to-consumer situation.

To allow everyone to log in:

menu Authorization > OpenID providers > tab Form

1. Create a Metadata endpoint with a common, organizations, or consumers tenant. See Azure Active Directory endpoints.
2. Select Allow all issuers.

Limit who can log in

Indicium main administrator

If you have two or more tenants and want to allow only users known to your organization to log in to your application, you can restrict who can log in.

To restrict who can log in to your application:

menu Authorization > OpenID providers > tab Form

1. Create a Metadata endpoint with an organizations tenant. See Azure Active Directory endpoints.

   tip

   If you only have one tenant, use the GUID reference to your tenant in the metadata endpoint instead of the organizations tenant. If you use the GUID reference, clear the Allow all issuers and Clear all issuers checkboxes.

2. Select Allow additional issuers and save this setting.

3. Navigate to the tab Valid issuer and add two or more issuers.

Additional issuers

Enable provisioning

Indicium main administrator

With provisioning, users are automatically created and updated based on the information provided by the OpenID provider when a user logs in.

Before you enable provisioning, you can configure a template.

To enable provisioning:

menu Authorization > OpenID providers > tab Form

1. Select Provisioning enabled.

Client credentials communication

Indicium main administrator

The client ID and secret can be communicated to the identity provider in the request body or as a header. Most providers (for example, Azure AD) support both.

To select how the client credentials are communicated to an identity provider:

menu Authorization > OpenID providers > tab Form

1. Select In request body or As Basic Auth header.

Buttons for signing in or out

Indicium main administrator

menu Authorization > OpenID providers > tab Form

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.

tip

If you clear both the Sign out button icon and the Sign out button text, the sign out button will not be displayed. This is useful if your OpenID provider does not support signing out.

Identifying claim to find a user

Indicium main administrator

menu Authorization > OpenID providers > tab Form

IAM uses the value of the Identifying claim (the user ID or the user's email address) to find the user.

• Generally, you should select the sub claim here. Only deviate with caution.
• 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.

Disable signing in with a local account

Indicium main administrator

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.

Login screen for OpenID identity providers

An environment can support both local (IAM, database or Windows authentication) and 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 login screen will not be shown at all. Instead, the only 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.
• 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.
• Remember my choice - a user can select this checkbox to set a cookie for skipping the login page the next time. This way, each user can make their own choice.

Multiple login options allowed

Log for login via OpenID providers

Indicium main administrator

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.

Azure Active Directory endpoints

Indicium main administrator

note

This is additional information on the topic Register OpenID identity providers in IAM.

warning

The Microsoft account that tries to log in must always be available in IAM, or Indicium will not accept the authentication.

If you have an Azure account with an active subscription, you can use Microsoft Azure Active Directory to authenticate your users. See the Microsoft documentation.

Azure AD uses the concept of tenants. A tenant is a dedicated instance of Azure AD that represents an organization. A tenant is uniquely identified by a GUID.

Aside from each company-specific tenant identified by a GUID, Microsoft defines the following global tenants:

• consumers - An alias for Microsoft's own tenant GUID. You can see this as Microsoft's own Azure Active Directory containing all personal Microsoft accounts.
• organizations - An alias for all company-specific tenants together. The authenticated user can come from any tenant that is not known in advance.
• common - Organizations and consumers. This tenant can contain all Microsoft accounts. The authenticated user can come from any tenant that is not known in advance.

To add a metadata endpoint for an OpenID provider in IAM:

Authorization > OpenID providers > tab Form

1. Enter an endpoint in field Metadata endpoint. See Endpoint examples.
2. If you are using a global tenant instead of a GUID reference to a tenant: select if you want to allow everyone to log in or only users that are known to your organization. See Allow everyone to log in and Limit who can log in.

Endpoint examples

• To allow only users from your own, singular, Azure AD tenant, use the GUID reference to your tenant. Example:

  https://login.microsoftonline.com/00000000-0000-0000-0000-000000000000/v2.0/.well-known/openid-configuration

  Replace 000000000-0000-0000-0000-0000000000 with the GUID reference of your tenant.

• To allow all Microsoft accounts (work and personal) to sign in, use the common tenant. In addition, select the Allow all issuers checkbox (see Allow everyone to log in). Example:

  https://login.microsoftonline.com/common/v2.0/.well-known/openid-configuration

• To allow any Microsoft work account, use the organizations tenant. In addition, select the Allow al issuers or Allow additional users checkbox (see Allow everyone to log in and Limit who can log in. Example:

  https://login.microsoftonline.com/organizations/v2.0/.well-known/openid-configuration

• To enable users to sign in with any Microsoft personal account, use the consumers tenant. Example:

  https://login.microsoftonline.com/consumers/v2.0/.well-known/openid-configuration

Provisioning (OpenID providers)

Automatically create or update users

Indicium main administrator

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

Indicium main administrator

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

Indicium main administrator

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

Indicium main administrator

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

Indicium main administrator

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

Indicium main administrator

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

Indicium main administrator

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