Client applications

Introduction to client applications

Indicium main administrator

A client application is an external application that you authorize to access your Thinkwise application. You can register a client application in Intelligent Application Manager (IAM) and configure how it authenticates and what it can access. The two main access types are machine-to-machine access and user-delegated access using OpenID Connect authentication. For more information, see Access types.

The Thinkwise Platform can act as the OpenID client or as the OpenID provider:

• The Thinkwise Platform as OpenID client - Authenticate users through Microsoft Entra ID, Google, GitHub, Facebook, and many other authentication providers. See OpenID (SSO).
• The Thinkwise Platform as OpenID provider - Indicium acts as the OpenID provider. External applications can authenticate users registered in IAM.

tip

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

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 (for example: automatic price updates, access to orders, hour registration, invoices, data manipulation).

  For more information, see Machine-to-machine API access.

• User-delegated API access (OpenID) - Instead of giving a client application full access to an API, you can limit the access to specific resources and actions. To do this, you need to set up OpenID Connect authentication and assign access delegation roles to the client application. When a client application requests access, the user can select which roles to delegate in the consent screen (for example: 'Allow the application to access your email?' or 'Allow the application to post messages on your behalf?')

  For more information, see OpenID Connect authentication and User-delegated API access (OpenID).

Prerequisites for configuring a client application

Before you can configure a client application, the following prerequisites must be met:

• 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.

• In some cases, you need to configure the certificate storage for client applications. For more information, see Certificate storage for client applications.

• 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 this case, set Load user profile to True in the application pool settings in IIS.

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

note

For finer control of the API access scope, use OpenID Connect authentication in combination with user-delegated API access.

To configure machine-to-machine API access:

menu Client apps > Client applications > tab Form

1. Enter a Client ID and Title.
2. Select the Enabled checkbox, so the client application can be used.
3. Clear the checkbox Support OpenID Connect.
4. In field Grant type, select Client credentials. As a result, API access becomes mandatory and is set to Full access (deprecated).
5. Optional. Only clear the checkbox Require PKCE 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. In field User, select a user. Usually, this is a service account. The client application will use it for authentication.
7. Optional. Add a Logo. For machine-to-machine API access, Required consent and Allow remember consent are not required.
8. Go to the tab Secrets and execute the task Add secret (encrypted) to add a secret. Share this secret with the client application to allow access.
   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

Check the connection

main administrator

Once you have configured the client application in IAM, check if the connection is working correctly. It can take up to a minute for Indicium to pick up the changes.

To check the connection, visit the following URL in the browser:

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

• If no JSON document is shown, 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 (OpenID)

You can scope the user-delegated API access for a client application with OpenID Connect. Access delegation roles allow you to limit the access to specific resources and actions. If the API access is limited, users will see a consent screen with the specific resources and actions every time the client application requests access to the API.

Prerequisites for user-delegated API access

Before you can set up user-delegated API access, the following prerequisites must be met:

• OpenID Connect authentication must be configured for the client application. See Configure OpenID Connect authentication.
• The user account must be allowed to delegate access. The user can also be a service account. See Select an authentication type for a user.
• The application must be allowed to delegate access and roles must be made available for delegation. See Make roles available for API access delegation.

Assign access delegation roles for a client application

To assign access delegation roles for a client application:

menu Client apps > Client applications > tab Form > group Access > tab Access delegation roles

This tab displays the roles for each application that are available for delegation to the client application. The application must be online to be available in this screen (see Bring an application online).

When a client application with limited access requests access, it has to request scopes. These should be requested in the format {application alias}/{role id}. The supported scopes are the roles that you marked available in Access delegation roles for the client application. These can be found at https://<base_url>/indicium/.well-known/openid-configuration.

The scopes that are requested by the client application are shown to the user in the consent screen.

Use the checkboxes to configure the following settings for each role:

• Enabled - This role is available for delegation to the client application. When a client application requests access, the user can select which roles to delegate in the consent screen.
• Required - This role is required for delegation to the client application. The client application must request this role when requesting access. The user cannot deselect this role in the consent screen, but can still choose to deny access entirely.

note

You can set up additional roles in the Software Factory. After making them available for delegation, you can assign them to the client application. For more information, see Create roles and Make roles available for API access delegation.

Assign access delegation roles for a client application

OpenID Connect authentication

main administrator

With OpenID Connect, the Thinkwise Platform acts as the OpenID provider, authenticating users on behalf of the client application (the OpenID client) using an existing account. Alternatively, it is possible to use the Thinkwise Platform as an OpenID client, with another website as the authentication provider. For more information, see the OpenID guide.

tip

It is recommended to read about Certificate storage for client applications before configuring OpenID Connect authentication.

To configure OpenID Connect authentication for a client application:

menu Client apps > Client applications > tab Form

1. Select the checkbox Support OpenID Connect. As a result, the Grant type is set to Authorization code.
2. Optional. Select the checkbox Offline access. If selected, the client application can request a refresh token during authentication. This allows the application to obtain new access tokens after they expire, without requiring the user to sign in again.
3. Optional. Select the API access from the dropdown list.

   • No access - Default. The client application can only authenticate the user with OpenID Connect.

   • Limited access (recommended) - The client application can authenticate the user with OpenID Connect and access the API on behalf of the user. Access is scoped using access delegation roles.

     note

     The setting Limited access requires additional setup. For more information, see User-delegated API access with OpenID Connect.

   • Full access (deprecated) - The client application can authenticate the user with OpenID Connect and get full access to the API on behalf of the user. This option is deprecated and will be removed in a future version. It is recommended to use Limited access instead.

4. Optional. Only clear the checkbox Require PKCE 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.
5. 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.
6. Optional. In the group Consent, configure the following settings:
   • Required consent - If selected, the user must explicitly grant consent before the client application can access data on their behalf.
   • Allow remember consent - If selected, the user can choose to remember their consent for future access by the client application.
7. Optional. Configure the following settings:
   • Always include user info in token
   • In the group Default resources, select the default resources that the client application can access.
8. Go to the tab Secrets and execute the task Add secret (encrypted) to add a secret. Share this secret with the client application to allow access.
   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. Optional. Set up Allowed login redirects and Allowed logout redirects in their respective tabs to add one or more URI redirects for logging in or out. These are whitelists of URLs to which the client can redirect after being granted access.
10. Optional. If Required consent is enabled, 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?
11. Go to tab Custom resources and configure which custom resources need to be shared with the visited website. See also, Configure custom resources.

OpenID Connect authentication

Configure custom resources

main administrator

If the Thinkwise Platform acts as an 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

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 GUI 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.