Skip to main content

Client applications

Introduction to Client applications​

tip

For more information about which authentication method to use, see Authentication.

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 Microsoft Entra ID (formerly: Azure Active Directory), Google, GitHub, Facebook, and many other authentication providers. See the OpenID (SSO) guide.

  • The Thinkwise Platform as OpenID provider - Indicium acts as the OpenID provider, allowing external websites to authenticate the accounts registered in IAM (described here in the Clients applications guide). See also Access types.

Access types​

main administrator

You can authorize another application (the client) to access your application in several ways:

  • Machine-to-machine access - Use the Client credentials grant type. This allows a client application with a service account direct access to an API. Human permission (consent) is not required. This grant type is used mainly for system APIs.
    Examples: automatic price updates, access to orders, hour registration, invoices, data manipulation.
    See:

  • Delegated authentication or API access - Use the Authorization code grant type. This allows a client application to access an API on behalf of a specific user. This user must be logged in and grant permission to the client application to access the API.
    Examples: "Will you allow this system to access your email?" or "Will you allow this system to post messages on your behalf?"
    If you use this grant type in combination with OpenID, access is granted to personal information for authentication instead of or in addition to an API. The information usually contains data like email, phone number, or address. User consent and API access are optional.
    See:

    • User-delegated API access
    • OpenID Connect authentication
      • When you are using delegated OpenID access as described in this guide, the Thinkwise platform is used as the OpenID provider. It is also possible to use the Thinkwise Platform as an OpenID client and another website as authentication provider. See the OpenID guide.

Prerequisites​

Certificate storage​

In some cases, before you start configuring client applications, you need to configure the certificate storage for these applications.

For more information, see Certificate storage for client applications.

Load user profile​

If you are running your application on-premise, an additional setting is required in IIS in the following situation:

  • You have configured OpenID clients in IAM.
  • And: you do not use an Azure Key Vault or AWS Secrets Manager for storing the client secrets.

In that case, set Load user profile to True in the application pool settings in IIS.

Database pool user permissions​

The database pool user needs full access to all the databases in IAM, including the IAM database itself. Therefore, it should have the role 'db_owner' for the IAM database and all end application databases.

Machine-to-machine API access​

main administrator

Machine-to-machine API access grants another application direct access to your own application, using the Client credentials grant flow of the OAuth2 protocol. Use this, for example, to enable automatic price updates, or access orders, hour registration, invoices, data manipulation, etc.

Human consent is not required. We recommend using a service account instead of a personal account.

Configure machine-to-machine API access​

​To configure machine-to-machine API access:

menu Client apps > Client applications > tab Form

  1. Enter a Client ID and Title.

  2. When ready for use, select the Enabled checkbox.

  3. Clear the Support OpenID Connect checkbox.

    • API access becomes mandatory.

  4. In field Grant type, select Client credentials.

  5. In field User, select a user. This is usually a service account. The client application will use it for authentication.

  6. Save these settings and go to tab Secrets.

  7. Add a client secret. You can make one up yourself. It is shared with the client application to allow access via the Client credentials grant type.

  8. Always restart Indicium after you added or changed a client application.

    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.

machine to machine api access Machine-to-machine API access

Check the connection​

main administrator

Once you have configured the client application in IAM and restarted Indicium:

  1. Check if you can visit the following URL in the browser:

    https://<base_url>/indicium/.well-known/openid-configuration

    • If no JSON document is shown, you forgot to restart Indicium or something is wrong with the routing or processing of the request at the web server level.

    • If the JSON document is shown, it contains a token_endpoint with the access token URL. It should look like this:

      https://<base_url>/indicium/connect/token

    • If it looks different (for example, http instead of https, a different domain, or a different /indicium base path), the reverse proxy settings may be misconfigured or missing.

User-delegated API access​

main administrator

Delegated API access grants another application access to your own application on behalf of a user, using the Authorization code grant flow of the OAuth2 protocol.

The user providing delegated API access will be involved in granting the client application access. This requires the user to be authenticated or to authenticate and may involve providing consent.

​To allow a client application delegated API access to your application:

menu Client apps > Client applications > tab Form

  1. Enter a Client ID and Title.

  2. When ready for use, select the Enabled checkbox.

  3. Clear the Support OpenID Connect checkbox.

    • API access becomes mandatory.

  4. In field Grant type, select Authorization code.

  5. Require PKCE - Only clear this checkbox if the OAuth server does not support PKCE (Proof Key for Code Exchange). PKCE is a security feature to prevent CSRF and authorization code injection attacks.

  6. Where necessary for your setup, enter or change the other settings in this tab:

    • Logo
    • Consent

  7. Save these settings and go to tab Secrets.

  8. Add a client secret. You can make one up yourself. It is shared with the client application to allow access via the Authorization code grant type.

    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.

  9. If necessary, go to the tabs Allowed login redirects and Allowed logout redirects to add one or more URI redirects for logging in or out. These are whitelists of URLs to which the client can redirect after the access token request.

  10. If consent is required, go to the tab Default resource translation, and add translations for each supported language for:

    • Profile consent - Does the user allow the client application access to their required personal information?
    • Email consent - Does the user allow the client application access to their email?
    • API consent - Does the user allow the client application access to another application?

delegated api access Delegated API acces without OpenID

OpenID Connect authentication​

main administrator

OpenID Connect allows a client application to let users authenticate via the Thinkwise Platform. OpenID is used for authenticating the user; the authentication process is delegated to the Thinkwise Platform as a OpenID provider. The other application is the OpenID client. An existing account is used to sign in to the other application.

​To allow a client application delegated OpenID access to your application, the Authorization code grant flow of the OAuth2 protocol is used:

note

First read the topic about Certificate storage for client applications.

menu Client apps > Client applications > tab Form

  1. Select the Support OpenID Connect checkbox.

  2. Require PKCE - Only clear this checkbox if the OAuth server does not support PKCE (Proof Key for Code Exchange). PKCE is a security feature to prevent CSRF and authorization code injection attacks.

  3. Select whether the client application is a Public client.

    • Public - Select Public client. Clients cannot use registered client secrets, such as applications running in a browser or native apps on a device. This is only possible if the client application has no secrets.
    • Confidential - Clear Public client. Clients can keep their secrets confidential. They can authenticate to the authorization server.

  4. Where necessary for your setup, enter or change the other settings in this tab:

    • Logo
    • Consent
    • Token
    • Default resources

  5. Save these settings and go to tab Secrets.

  6. Add a client secret. You can make one up yourself. It is shared with the client application to allow access via the Authorization code grant type.

    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.

  7. If necessary, go to the tabs Allowed login redirects and Allowed logout redirects to add one or more URI redirects for logging in or out. These are whitelists of URLs to which the client can redirect after the access token request.

  8. If consent is required, go to tab Default resource translation, and add translations for each supported language for:

    • Profile consent - Does the user allow the client application access to their required personal information?
    • Email consent - Does the user allow the client application access to their email?
    • API consent - Does the user allow the client application access to another application?

  9. Go to tab Custom resources and configure which custom resources need to be shared with the visited website. To configure a custom resource, see Configure custom resources.

OpenID Connect authentication

OpenID Connect authentication and user-delegated API access​

main administrator

You can allow client applications to both authenticate the user with OpenID Connect and obtain access to the API, combining OpenID Connect and user-delegated API access.

menu Client apps > Client applications > tab Form

  1. Select the Support OpenID Connect checkbox.

    • The Grant type is always 'Authorization code'.

  2. Select the API access checkbox.

  3. Select whether the client application is a Public client.

    • Public - Select Public client. Clients cannot use registered client secrets, such as applications running in a browser or native apps on a device. This is only possible if the client application has no secrets.
    • Confidential - Clear Public client. Clients can keep their secrets confidential. They can authenticate to the authorization server.

OpenID Connect authentication with API access

Configure custom resources​

main administrator

If the Thinkwise Platform acts as a OpenID provider, information is shared between IAM and the client application. For example, the name, department, or email address. You can control which information is shared with the visited website by configuring the custom resources claims.

The shared data are used to confirm your identity at the websites you visit.

note

Your (salted and hashed) password is known only by IAM. Other than IAM, no website ever sees your password.

menu Client apps > Custom resources

resources Configure custom resources

Configure database access​

To ensure that Indicium can access the database and that authentication with an access token is possible, add settings for the /health endpoint to the appsettings.json file of Indicium. For more information about the /health endpoint, see Health check endpoint.

Without these settings, users without authentication or developer rights will only receive a Status: Unhealthy or Status: Degraded.

Encrypt a secret​

3-tier IAM in the Universal GUI main administrator

You can encrypt the secret for client applications 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 Client apps > Client applications

  1. Select the client application and go to the tab Secret.
  2. Execute the task Add secret (encrypted) to add an encrypted secret to a client application.
Was this article helpful?