Skip to main content

Celonis Product Documentation

Registering your OAuth client in Celonis Platform

OAuth can be used as an authentication method for Celonis Platform, which offers a more secure and flexible way of granting permissions to clients (applications) compared to API keys.

For an overview of the differences between OAuth 2.0 and using Application or API Keys, see: Using OAuth 2.0.

 

To register your OAuth clients in Celonis Platform:

Create_applications.png

Tip

The UI shows all applications and their type split into two categories: customer-configured and Celonis-configured applications. Customer-configured applications are managed by customer admins and are created when, for example, the admin needs to integrate another application with the team. Celonis-configured applications are configured and managed by Celonis services to integrate seamlessly with the team. For example: Task Mining creates an OAuth client every time a device is activated. The On-Premise Client is used to bootstrap extraction whenever it is installed on an on-prem device.

  1. Go to Admin & Settings > Applications.

  2. Click Add new application and select OAuth Client.

    Adding a new OAuth client.
  3. Configure the OAuth client with the following fields:

    • Name: An internal reference to this client.

    • Grant type: Defaults to Client Credentials.

    • Authentication methods

      • Client secret basic: With this method, the client uses the Authorization header to send the client_id and client_secret in the following format: Authorization: Basic encoded_credentials.

        Here the value of encoded_credentials corresponds to the base64 encoding of OAuth client’s client_id:client_secret.

      • Client secret post: The client authenticates itself by providing the client_id and client_secret in the HTTP request body as a form parameter.

  4. Click Define scopes.

    Scopes allow you to define areas to which the client should have access within its current permissions. You can't grant additional permissions to a client using scopes. For the complete list of scopes, see OAuth scopes.

  5. Select resource types within Celonis Platform to which the clients will have access based on granted permissions. Chosen scopes give the client access to specific Celonis Platform APIs.

  6. Click Create.

As scopes only allow access to the APIs, the created OAuth client should now be assigned permissions to resources behind those APIs. After creating a client in Celonis Platform, developers receive client credentials: client ID and client secret. Every scope should have a name and a description, which unambiguously explains which APIs can be accessed with the scope based on the permissions granted to the client.

  1. In your Celonis Platform, go to Admin & Settings > Permissions.

  2. Locate the service you need and click Edit.

    In this example, we’re updating the User Provisioning service.

    A screenshot showing where the edit button is located within the permissions area.
  3. Select the required template for your application and, if required, enable SCIM permissions.

    In this example, we are granting our application with manage permissions and enabling SCIM permissions.

  4. Click Save.

  5. Add the access token to the authorization header of your requests using the following format:

    Authorization: Bearer ACCESS_TOKEN

Your application now has the correct permissions within your Celonis Platform.

For security reasons, you may want to regenerate the client secret using the following steps:

  1. In your Celonis Platform instance, go to Admin & Settings > Applications.

  2. Find your OAuth client and click the three-dot menu next to it.

  3. Select Regenerate secret.

    For security reasons, you can regenerate the client secret from this menu.

Once you generate a new client secret, make sure to update the secret in all integrations that use that client.

During OAuth authorization flows, users can give consent to OAuth clients to access resources on their behalf. To view which OAuth clients have been granted consent, go to Edit Profile and then to the section OAuth Client Management. From there you can view which applications (OAuth clients) have been granted consent and revoke that consent.

After registering your OAuth client and assigning it the necessary permissions in your Celonis Platform team, you can now use a REST API client such as Postman to make a POST request for your access token.

To do this, you need your token URL:

https://<team>.<cluster>.celonis.cloud/oauth2/token

And in Postman:

After registering your OAuth client and assigning it the necessary permissions in your Celonis Platform team, you can use a REST API client such as Postman to make a POST request for your access token.

You then need to append at least two query parameters to your token URL:

  • Grant type: This must be 'client_credentials' as this is currently the supported grant type for OAuth clients.

  • Scope: This should be the Celonis platform services that you have granted permissions to (based on the service string). In our example, we've included Studio:

https://<team>.<cluster>.celonis.cloud/oauth2/token?grant_type=client_credentials&scope=studio

And in Postman:

After you append two query parameters to your token URL, they appear like this in Postman.

You can then configure the Authorization. In this example, we're using a basic authentication using a username (the client ID) and password (the client secret):

Configure the Authorization. In this example, we're using basic authentication with a username (the client ID) and password (the client secret).

This configuration gives you an OAuth request such as:

curl --request POST \
  --url https://<team>.<cluster>.celonis.cloud/oauth2/token \
  --header 'content-type: multipart/form-data' \
  --form client_id=<client id> \
  --form client_secret=<client secret> \
  --form grant_type=client_credentials \
  --form scope=<scope1 scope2 scopeN>

And running the request returns a response that includes your access token:

{
	"access_token": "randomizedAcessToken",
	"scope": "scope1 scope2 scopeN",
	"token_type": "Bearer",
	"expires_in": 899
}

This access token can then be used with a bearer token authentication method to request access to and information from the Celonis Platform services you need:

The bearer token. Use this with the access token to request access to the Celonis Platform services you need.

Scopes allow you to define areas to which the client should have access within its current permissions. Here's a list of available scopes.

studio

Gives access to studio based on granted permissions.

user-provisioning.scim

Gives access to the SCIM API based on granted permissions.

audit.log:read

Gives read-only access audit logs based on granted permissions.

integration.data-pools

Gives access to data pools based on granted permissions.

integration.data-pools:data_push

Gives access to push data to data pools based on granted permissions.

integration.data-pools:continuous_data_push

Gives access to continuously push data to data pools based on granted permissions.

platform-adoption.tracking-events:read

Gives read-only access to platform-adoption tracking-events based on granted permissions.

team.login-history:read

Gives read-only access to team login history based on granted permissions.