Token certificates on-premise

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

OpenID Connect

Indicium

Deprecated

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

OAuth 2.0 Bearer Tokens

Indicium

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 apps > 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