Skip to main content
Version: 2024

Client applications

Introduction to Client applications​

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

Before you start configuring client applications, you need to configure the certificate storage for these applications. See Certificate storage for client applications.

Certificate storage for client applications​

Indicium automatically creates certificates for client applications that have been configured in IAM. The Thinkwise Platform has several options for centralizing the storage of these certificates.

warning

Due to license restrictions for the external IdentityServer component, a maximum of five client applications are allowed. Please contact Thinkwise if you need more than five client applications.

See:

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.

​To allow a client application machine-to-machine 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.

    • Support API access becomes mandatory.

  4. In field Grant type, select 'Client credentials'.

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

  6. Save these settings and navigate 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.

    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

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.

    • Support API access becomes mandatory.

  4. In field Grant type, select Authorization code.

  5. If Proof of Key for Code Exchange (PKCE) is not required, clear the Require PKCE checkbox.

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

    • Support refresh tokens
    • Logo
    • Consent

  7. Save these settings and navigate 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, navigate to the tabs Allowed login redirects and Allowed logout redirects to add one or more URI redirects for logging in or out. This is a whitelist of URLs that the client can redirect back to after the access token request.

  10. If consent is required, navigate 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. If Proof of Key for Code Exchange (PKCE) is not required, clear the Require PKCE checkbox.

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

    • Support refresh tokens
    • Logo
    • Consent
    • Token
    • Default resources

  4. Save these settings and navigate to tab Secrets.

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

  6. If necessary, navigate to tabs Allowed login redirects and Allowed logout redirects to add one or more URI redirects for logging in or out.

  7. If consent is required, navigate 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?

  8. Navigate 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.
  2. Select the Support API access checkbox.

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

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 page helpful?