OpenID in Indicium

Signing OpenID Server certificates

When Indicium is used as an OpenID server, it must add a signature to the access token to prove that it was created by an authorized Indicium instance. Indicium automatically creates a certificate that is used to sign the access token if OpenID clients are configured in IAM.

By default, Indicium stores this certificate locally, on the web server. In the case of a single Indicium instance (i.e. not load-balanced) this will work fine. However, when there are multiple instances of Indicium, the certificate must be stored elsewhere, since all servers must use the same certificate. If not, the access tokens created by instance A will not be authorized by instance B (or vice versa). Should the certificate be lost or replaced, all access keys will become unusable, but they can be easily requested again by the third party.

The Thinkwise platform has several options for centralizing the storage of this certificate.

• Sign certificates on Azure.
• Sign certificates on-premise.
• Sign certificates on-premise with Azure Key Vault.
• Sign certificates on AWS.

Sign certificates on Azure

When using Indicium on Azure, the OpenID Server certificate must be stored in a Key Vault:

1. Create a Key Vault on the Azure Portal.

2. Add an "Access Policy" to it to allow the Indicium instance Web App access.

3. Select the Identity menu in the Indicium Web App.

4. Check whether the Identity setting System Assigned is enabled.

5. In the Key Vault, select +Add Access Policy from the Access Policy menu on the left-hand side.

6. In the Secret permissions field, select the "Get" permission.

7. In the Certificate permissions field, select the “Import” permission.

8. In the Select principal field, select your Indicium Web App.

9. Click Add. You are automatically returned to the Access Policy screen.

10. Click Save to save the new access policy.

Add access policy

To use the newly created Key Vault, you must set the KeyVaultCertificateUrl setting in the Indicium Web App.

In the appsettings.json configuration file, this KeyVaultCertificateUrl setting can be configured directly:

  "OpenIDServerSigningSettings": {
    "AzureKeyVault": {
      "KeyVaultCertificateUrl": "<key vault certificate url>"
    }
  }

Alternatively, you can store this setting in the App Service:

1. In the App Service, select Settings > Configuration from the menu.

2. Add the following Application settings:

Name: OpenIDServerSigningSettings:AzureKeyVault:KeyVaultCertificateUrl

Value: https://<name-of-the-key-vault>.vault.azure.net/certificates/<openid-server-certificate-name>

You can add a name to the certificate. This is how it will appear in the Azure Key Vault after it has been created by Indicium. It will be created only if OpenID clients are configured in IAM.

1. To allow Indicium to generate the certificate, add setting: website_load_certificates with value “*”.

2. Restart Indicium. This is required to automatically create the signing certificate.

Sign certificates on-premise

When using Indicium as an OpenID Server in a VM, the certificate is automatically created in the Certificate Store. If you have multiple servers behind a load balancer, you must synchronize this IndiciumOpenID certificate manually, as follows:

1. Export the IndiciumOpenID certificate from one web server.
2. On each other web server, overwrite the IndiciumOpenID certificate with the exported one.

You must also set Load User Profile to true:

1. In IIS, right click on your Application Pool.

2. Open the Advanced Settings.

3. Set Load User Profile to True.

Sign certificates on-premise with Azure Key Vault

You can also use on-premise with Azure Key Vault. This consists of:

• Create a new "App registration" in the Azure portal.
• Create an Azure Key Vault.
• Configure some settings in the appsettings.json configuration file.

1. In Azure Active Directory, select App registrations to create the registration.

After creating the registration, you can find the Application (client) ID and the Tenant id in the Overview menu. These IDs will be used later.

1. From the Certificates & secrets menu, add a new "Client secret".

2. Copy or make a note of the secret value (not the secret id), this value is used in the last step.

3. Create a Key Vault from the Azure Portal.

4. Add an "Access Policy" to it to allow the Indicium instance Web App access.

5. In the Key Vault, select +Add Access Policy from the Access Policy menu on the left-hand side.

6. In the Secret permissions field, select the "Get" permission.

7. In the Certificate permissions field, select the “Import” permission.

8. In the Select principal field, select the "App registration" you created in the first step.

9. Click Add. You are automatically returned to the Access Policy screen.

10. Click Save to save the new access policy.

11. To use the newly created Key Vault, add the following section to the appsettings.json configuration file, and specify the values for TenantId, ClientId, and ClientSecret.

  "OpenIDServerSigningSettings": {
    "AzureKeyVault": {
      "TenantId": "<tenant id>",
      "ClientId": "<client id>",
      "ClientSecret": "<tenant id value>",
      "KeyVaultCertificateUrl": "<key vault certificate url>"
    }
  }

Sign certificates on AWS

When using Indicium as an OpenID Server on AWS, Indicium can store the OpenID Server certificate in the AWS Secrets Manager.

To give the Elastic BeanStalk EC2 instance access to the Indicium OpenID Server certificate:

1. In your Elastic Beanstalk EC2 instance, select the Security tab.

2. Click the Identity and Access Management (IAM) link.

3. Click Add permissions.

4. Click Create inline policy.

5. In the JSON tab, paste the JSON code fragment below.

6. Click Save to save the new policy. Indicium can now access the AWS Secrets manager.

{
    "Version": "2012-10-17",
    "Statement": [
        {
            "Sid": "VisualEditor0",
            "Effect": "Allow",
            "Action": [
                "secretsmanager:GetSecretValue",
                "secretsmanager:CreateSecret"
            ],
            "Resource": "arn:aws:secretsmanager:<region>:<account-id>:secret:<secret-prefix>-*"
        }
    ]
}

In the above JSON code fragment:

• Replace region with, for example, “eu-west-1”.
• Replace account-id with your account number.
• Replace secret-prefix with the prefix you want your OpenID Server certifcate in the Secrets Manager to be named.

For example, if your prefix is “indicium/openid-server-test”, you should give access to “indicium/openid-server-test-*” with the wildcard character.

1. In the appsettings.json configuration file, add the following code:

  "OpenIDServerSigningSettings": {
    "AwsSecretManager": {
      "SecretName": "indicium/openid-server-test"
    }
  }

OpenID Connect

Indicium

Deprecated

Deprecated as of Thinkwise Platform version 2022.2. These settings are now available in IAM. See OpenID.

Indicium supports authentication through third party authentication providers that support OpenID Connect. This makes it possible to authenticate users through Azure Active Directory, Google, GitHub, Facebook and many other authentication providers.

note

OpenID Connect defines several authentication flows, but only Identity Providers that use the Authorization Code flow can be integrated into Indicium.

Topics available on OpenID:

• Integrate an external Identity Provider into Indicium
• Multiple external Identity Providers
• Redirect immediately to the Indicium login page

note

For more information about OpenID authentication in Indicium and its configuration, see also this blog on the Thinkwise Community.

Integrate an external Identity Provider into Indicium

Deprecated

Deprecated as of Thinkwise Platform version 2022.2. These settings are now available in IAM. See OpenID.

To integrate an external Identity Provider into Indicium, configure the following settings in the appsettings.json file.

{
  "OpenIDConnect": {
    "IdentityProviders": {
      "Microsoft": {
        "MetadataEndpoint": "",
        "ClientId": "",
        "ClientSecret": "",
        "ButtonIcon": "microsoft.png",
        "ButtonText": "Sign in with Microsoft",
        "AlwaysPromptLogin": true
      },
      "Google": {
        "MetadataEndpoint": "",
        "ClientId": "",
        "ClientSecret": "",
        "IncludeEmailScope": true,
        "UserIdClaimType": "",
        "ButtonIcon": "google.png",
        "ButtonText": "Sign in with Google",
        "AlwaysPromptLogin": true
      }
    }
  }
}

• MetadataEndpoint - This property refers to the OpenID Connect metadata endpoint, which always ends with /.well-known/openid-configuration. Indicium uses this metadata to determine the other endpoints such as the authorize endpoint and the token endpoint.
• PromptLogin - Optional. If you want to use any prompt setting supported by the Identity Provider, and not only the "login" prompt, you can specify a string here, for example, select_account. This setting takes precedence over AlwaysPromptLogin.
• AlwaysPromptLogin - Optional. By default, its value is false. When set to true, the login screen will always appear. If the specified OpenID is the only login option available and the value of AlwaysPromptLogin is false, Indicium will automatically log you out when clicking the button to go to the logout page.
• IncludeEmailScope - Optional. By default, Indicium uses the 'email' claim type to map the signed in user to a user in IAM. Some Identity Providers (such as Google) will only provide the 'email' claim type if the 'email' scope is specifically requested by the client. For those Identity Providers it is necessary to set this property to true.
• UserIdClaimType - Optional. By default, Indicium uses the 'email' claim type to map the signed in user to a user in IAM. If you want to use another claim type, such as the 'sub' claim type or perhaps even a proprietary claim type, then this property can be used to indicate which claim type should be used instead.
• IncludeProfileScope - Optional. By default, its value is true. Indicium default requests the openid and profile scopes for external Identity Providers. However, not all Identity Providers support the profile scope. Set to false if your Identity provider does not support the profile scope.

Authenticating users in Microsoft Azure Active Directory using tenants

Deprecated

Deprecated as of Thinkwise Platform version 2022.2. These settings are now available in IAM. See OpenID.

If you have an Azure account with an active subscription, you can use Microsoft Azure Active Directory to authenticate your users. 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.

The base configuration for OpenIDConnect for Microsoft is:

"Microsoft": { 
    "MetadataEndpoint": "https://login.microsoftonline.com/<tenant>/v2.0/.well-known/openid-configuration", 
    "ClientId": "client-id", 
    "ClientSecret": "client-secret", 
    "ButtonIcon": "windows_64px.png", 
    "ButtonText": "Sign in with Microsoft", 
    "SignOutButtonIcon": "windows_64px.png", 
    "SignOutButtonText": "Sign out of Microsoft", 
    "IncludeEmailScope": true 
} 

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

• consumers is an alias for Microsoft's own tenant GUID. You can see this as Microsoft's own Azure Active Directory containing all personal Microsoft accounts. If you use this tenant, you do not need to configure the ValidateIssuer and ValidIssuers options.
• organizations is an alias for all company-specific tenants together.
• common stands for organizations and consumers. This tenant can contain all Microsoft accounts.

In the organizations and common tenants, the authenticated user can come from any tenant that is not known in advance.

In all cases, the Microsoft account that tries to log in must be available in IAM. Otherwise, Indicium will not accept the authentication.

For more information, refer to the Microsoft OpenID Connect documentation.

• If you want to allow all work accounts to sign in, use the organizations tenant.
• If you want to allow all Microsoft accounts to sign in, use the common tenant.

In both cases, you cannot validate the issuer because it is not clear in advance which tenant a user is in. Therefore, you must disable the issuer validation:

"ValidateIssuer": false 

If you want to allow a list of tenants, for example because your organization has multiple Azure ADs but you want a single sign-in button, you should use the organizations tenant with the issuer validation enabled. You can use the ValidateIssuer settings to supply a list of tenants corresponding to all of your Azure ADs. This way, accounts of other organizations will not be able to sign in.

"MetadataEndpoint": "https://login.microsoftonline.com/organizations/v2.0/.well-known/openid-configuration",
 
"ValidIssuers": [
 
    "https://login.microsoftonline.com/<tenant-one>/v2.0", 
    "https://login.microsoftonline.com/<tenant-two>/v2.0"
 
] 

To enable users to sign in with personal accounts, specify consumers for <tenant>.

Multiple external Identity Providers

Deprecated

Deprecated as of Thinkwise Platform version 2022.2. These settings are now available in IAM. See OpenID.

It is possible to integrate multiple external Identity Providers at the same time. Each configuration must be given a name that can be chosen freely, such as "Microsoft" or "Google".

When multiple options are available for logging in, e.g. logging in with a local account against IAM, logging in through IIS with integrated Windows authentication, or logging in through external Identity Providers, Indicium will show a login screen like the one below:

• If only one option is available, this page will not be shown at all and the option will be handled as the default option.
• 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 will be displayed for the local account either. Add the following setting to the Indicium's configuration file (appsettings.json):

"LoginOptions": {
   "AllowLocalAccounts": false
}

Redirect immediately to the Indicium login page

Deprecated

Deprecated as of Thinkwise Platform version 2022.2. These settings are now available in IAM. See OpenID.

If OpenID is fully configured, the Universal GUI can redirect the user immediately to Indicium's login page. To do this, add the options loginOptionsDisabled and loginOptionsHidden and set them to true in the Universal GUI's configuration file (config.json).

{
   "defaultApplication": "",
   "defaultPlatform": 3,
   "loginOptionsDisabled": true,
   "loginOptionsHidden": true,
   "serviceURL": "https://localhost:5001/iam/iam"
}

If these login options are set to false, the user is allowed to change the login options before continuing to the Indicium login screen.

OpenID Single Log Out

Deprecated

Deprecated as of Thinkwise Platform version 2022.2. These settings are now available in IAM. See OpenID.

Indicium

Indicium Universal supports authentication through external Identity Providers with Single Logout (SLO). This means that it is possible to log out of the external Identity Provider in an integrated way from Indicium's log out page, provided you were logged in with an external Identity Provider (see OpenID connect).

Example: Single Log Out

The type of SLO that Indicium supports is called front-channel logout:

• Indicium redirects the user to the logout page of the external Identity Provider where the user can log out.

• Upon doing so, the external Identity Provider will send a logout-call back to Indicium before redirecting the user back.

Take the following steps to configure Single Log Out:

1. Add two properties (SignOutButtonIcon and SignOutButtonText) to the configuration in the appsettings.json. These properties allow you to configure the sign-out button that will appear on Indicium's logout page:

"OpenIDConnect": {
 "IdentityProviders": {
   "Microsoft": {
    "MetadataEndpoint": "",
    "ClientId": "",
    "ClientSecret": "",
    "ButtonIcon": "microsoft.png",
    "ButtonText": "Sign in with Microsoft",
    "AlwaysPromptLogin": true,
    "SignOutButtonIcon": "microsoft.png",
    "SignOutButtonText": "Sign out of Microsoft" 
  }
 }

2. Configure the logout call at the external Identity Provider.

   Taking Microsoft's Azure Active Directory as an example, the screenshot below shows how you can configure the front-channel logout URL. Just like how the post-sign in redirect URL is /signin-{name} — where {name} is the name of the Identity Provider in the appsettings.json — the front-channel logout URL is /signout-{name}.

   Example: Front-channel logout URL in MS Azure Active Directory

OAuth 2.0 Bearer Tokens

Indicium

Deprecated

Deprecated as of Thinkwise Platform version 2022.2. These settings are now available in IAM. See OpenID.

An OpenID Client configured in IAM can be used to request JSON Web Tokens (JWT), which users can use as a token for the Bearer authentication scheme. These tokens usually contain a set of claims for resources that the user has granted access to for the requesting application through a scope.

For example, to get access to the claims that would be sent when using OpenID, an application can request the access token endpoint for the openid scope. If the consent page is enabled for the corresponding OpenID client in IAM, the user sees a page that presents to which scopes the requesting application grants access. If the user grants the requesting application access to the listed scopes, it will receive an access token that it can use to make further requests on the user's behalf.

In contrast to using Indicium as an OpenID Connect identity provider, OAuth 2.0 can request additional scopes for a user, such as access to the API endpoints of applications. Currently, there is only one scope, called full_api_access. It grants access to all APIs available for the user.

This feature requires adding the external URL of Indicium as the authority for which the bearer tokens are valid, which is explained in the example below.

note

At this moment, Indicium only gives out access tokens. The exchange of a refresh token is not supported. Access tokens are valid for one hour.

API access example

To enable authentication through OAuth 2.0 Bearer Tokens, first configure the OpenID client in IAM:

menu OpenID > OpenID clients

1. Select an OpenID client.
2. Check the API box for this client. This checkbox enables the full_api_access scope.
3. Save this setting.
4. Open tab Configuration.
5. Under Redirects, add a redirect URI. This configuration acts as a whitelist of URLs that a third-party client can redirect back to after the access token request.
6. Under Secrets, add a client secret.
7. Save this configuration.

Then, configure the Authority URL:

8. Open Indicium's appsettings.json.
9. Add the location of the Authority, which is the external URL to Indicium, using the BearerTokenAuthority key. This Authority URL uses 'HTTPS', e.g.:

{
  "BearerTokenAuthority" : "https://localhost:5001"
}

Then, request an access token:

Example request for an access token (used API tool: Insomnia)

• Grant type: Indicium uses the OAuth 2.0 Authorization Code flow which exchanges an authorization code for a token. For more information, see https://auth0.com/docs/flows/authorization-code-flow. You can use PKCE if the client is deemed insecure.

• Authorization URL: to retrieve an authorization code via the browser. It involves authentication via the login prompt and (when required) consent. You can retrieve the Authorization URL by calling the following endpoint on the Authority URL:

  <Authority URL>/.well-known/openid-configuration

  Typically, the authorization URL looks like this:

  /connect/authorize

• Access token URL: to retrieve the access token. Just like the Authorization URL, you can retrieve the Access Token URL by calling the following endpoint on the Authority URL:

  /.well-known/openid-configuration

  Typically, the Access token URL looks like this:

  /connect/token

• Client ID, Client secret, and Redirect URL: client information stored in IAM from steps 1-5.

• Scope: This should include full_api_access to obtain an Access Token that gives API access. Other scopes, such as OpenId, profile, email, etc., can be requested simultaneously if necessary.

If in IAM is configured that consent is required, the following consent page will appear. Only after the user confirms to allow access will Indicium give out the access token.

Consent page