Token certificates on-premise

OpenID Connect

Indicium

OpenID connect can be configured in IAM. For more information, see the OpenID guide.

note

For Thinkwise Platform version 2022.1 and older, the OpenID Connect settings were available in Indicium's appsettings.json file. See the OpenID Connect guide. This documentation is no longer maintained.

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.

This manual describes how to centralize the storage of this certificate on-premise.

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.

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

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

4. Create a Key Vault from the Azure Portal.

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

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

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

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

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

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

11. Click Save to save the new access policy.

12. 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>"
    }
  }

OAuth 2.0 Bearer Tokens

Indicium

A client application configured in IAM can be used to request JSON Web Tokens (JWT). Users can use these tokens for the OAuth Bearer authentication scheme. The tokens usually contain a set of claims for resources. A user needs to grant an application access to these resources through a scope.

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

OAuth 2.0 can request additional scopes for a user. Currently, the following scopes are available:

• Support API access (full_api_access) - Grants access to all the APIs available to the user. Access tokens are valid for one hour.
• Support refresh tokens - Requests a new access token for OAuth if the old one is expired.

For more information about client application settings and scopes, see the Client applications guide.

If bearer tokens are used, you must add the external URL of Indicium as the authority for which the bearer tokens are valid. This is explained in the example below.

OAuth Bearer token example

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

menu Client apps > Client applications

1. Select a client application that uses the Authorization code grant type.

2. Select the Support API access checkbox. This enables the full_api_access scope.

3. Save this setting and navigate to tab Secrets.

4. Add a client secret.

5. On the tabs Allowed login redirects and Allowed logout redirects, add redirect URIs. This configuration acts as a whitelist of URLs that a third-party client can redirect back to after the access token request.

6. Save this configuration.

   Then, configure the Authority URL:

7. Open Indicium's appsettings.json.

8. 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"
}

10. Then, request an access token. In this example, the API tool 'Insomnia' has been used:

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.

• 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 the client application in IAM has been configured to require consent, the following consent page will appear. Only after the user's consent, Indicium will hand out the access token.

Consent page