Skip to content

Manually registering clients (applications) to the Authorization Service

Every application delegating authentication of users and services to the Authorization Service requires a registered client (often also called application). There exist two types of clients: public and confidential clients. Public clients are Single Page Applications or Rich Clients on a desktop, because a client secret cannot be securely hidden from a user. Confidential clients are daemon services such as the platform's configuration service. Those services run on a secured VM to that only authorized users have access and where the typical user cannot even see the configuration files.

When the platform installer is used to set up a system, it creates all clients that are required to run the platform automatically (unless you opted out of that behavior). In those cases, nothing needs to be done.

However, when you add a custom web client or new rich client, want to create a custom client for another Activity Server or need to recreate a client for a resource service of the platform, some things must be taken into consideration:

  • Is the client public or confidential as in "can it keep a secret"?
  • If it is a public web client, where is it hosted?
  • If it is a daemon application, does it need special permissions?

Important When using the authorization code flow with PKCE with a custom client application (for example your website), ensure to only expect a code response and use PKCE. The Authorization Server does not support the OAuth2.0 Implicit flow.

For convenience, we provide some example scenarios that help you to pick the correct configuration for your new client registration.

Important When using Redirect Uris keep in mind that they are case sensitive. The URIs "http://my.contoso.com/editor" and "http://my.contoso.com/Editor" are not the same and lead to error. We recommend to lowercase the redirect URIs on the client side and only register lowercased redirect URIs.

Example: Create a Client for an Activity Server

  1. Enter the New Client ID menu.
  2. Provide a client ID as well as a client secret.
  3. Select the Client credentials authorization mode and the additional permission Activity host.
  4. Create the client by clicking on Create Client ID.

Example: Create a client for an Activity Server as technical user

In the past, Activity Servers had the option to run as a technical user. While a windows service can still do that, it does not have any effect on the given permissions anymore. To re-create that scenario, you need to do the following steps:

  1. Enter the New Client ID menu.
  2. Provide a client ID as well as a client secret.
  3. Select the Client credentials authorization mode
  4. Do not select Allow introspection nor Additional permissions
  5. Under Windows Security Identifiers add the SIDs of a technical user or group that you use to configure access permissions.

Obtaining a windows user SID

To determine the SID of a windows user, you can use the Get-ADUser powershell commandlets. Please see https://docs.microsoft.com/en-us/powershell/module/activedirectory/get-aduser?view=windowsserver2022-ps for more information.

Another approach that works via powershell is the following:

$username='techUser'
$user = New-Object System.Security.Principal.NTAccount($username) 
$sid = $user.Translate([System.Security.Principal.SecurityIdentifier]) 
$sid.Value

Example: Create a Client to be used by a Website

SPAs are public by design since every piece of configuration is sent to an unknown browser on an unknown machine. The same is true for rich clients and may even be true for Asp.net Core MVC applications.

  1. Enter the New Client ID menu.
  2. Provide a client ID, but leave the client secret field empty. Web sites are public clients and cannot keep a secret.
  3. Select the Authorization code authorization mode.
  4. If the web app works with the platform, you must ensure enough scopes
    1. Set the interactive scope if the client is accessing interactive activities, also known as external activities
    2. Set the unattended scope if the client also must be able to access unattended activities, such as time driven, or document driven activities.
  5. Provide a Redirect Uri and a Post Logout Redirect Uri that are both valid and both point to paths that your website accepts. Usually, you use an OIDC client library that handles these tasks. Ensure that the web site uses the redirect uris only in lower case when sending them to the Authorization Server - Redirect URIs are case sensitive. If your websites sends "https://my.site.com/oidc-login" but only registered "https://my.site.com/" or "https://my.site.com/OIDC-login", the redirect uris do not match and the login does not work.
  6. Create the client by clicking on Create Client ID

Example: Create a Client for a Rich Desktop Application

Rich clients are public by design since all configuration must be on the user's local machine.

  1. Enter the New Client ID menu.
  2. Provide a client ID, but leave the client secret field empty. Rich clients are public clients and cannot keep a secret.
  3. Select the Authorization code authorization mode.
  4. If the web app works with the platform, you must ensure enough scopes
    1. Set the interactive scope if the client is accessing interactive activities, also known as external activities
    2. Set the unattended scope if the client also must be able to access unattended activities, such as time driven, or document driven activities.
  5. Set the Redirect Uri to http://localhost/. Setting localhost implicitly allows any port to be used, so that a rich client can spawn a web service listening on a random free port on the local OS.
  6. Leave the Post Logout Redirect Uri empty. This Uri must be matched explicitly and is of no use for a rich client application. Ensure that the rich client uses the redirect uris only in lower case when sending them to the Authorization Server - Redirect URIs are case sensitive.
  7. Create the client by clicking on Create Client ID

Example: Create a Client for a resource service of the Primus Process Management System (a daemon application)

Daemon applications are run without any user interaction and thus cannot use the authorization code flow. Leaving username and password in a configuration file on disk is also not recommended. Instead, you use a clientId and clientSecret that are not directly tied to any actualy user account and provide credentials necessary for a machine to authenticate itself when talking to another machine.

  1. Enter the New Client ID menu.
  2. Provide a client ID as well as a client secret.
  3. Select the Client credentials authorization mode and the additional permission Resource Service.
  4. Select Allow introspection - yes. The resource service must be able to verify access tokens it receives.
  5. Create the client by clicking on Create Client ID.

Example: Create a Client for an application that uses the password grant flow

Using this grant type is strongly discouraged as the client application would always get access to the username and password. Use the Authorization code with PKCE flow whereever possible.

  1. Enter the New Client ID menu.
  2. Provide a client ID, but no client secret. Like the Authorization code flow, the Password flow is used by public client applications that cannot keep a secret.
  3. Select the Password authorization mode.
  4. Create the client by clicking on Create Client ID.