Migrating to OAuth 2.0

OAuth 2.0 is an industry-standard framework that allows different applications to securely interact with each other on behalf of users without sharing sensitive credentials. More about OAuth here.

At Celonis, we are in the process of moving away from long term API and Application keys and rapidly moving towards OAuth. This section highlights what Celonis APIs today already support OAuth and how you can migrate your applications that call these APIs using API/Application keys to OAuth.

Celonis APIs that currently support OAuth 2.0:

*SCIM API does not support Microsoft EntraID with OAuth yet. We are in the process of adding this support.

OAuth scopes restrict which APIs are accessible by OAuth clients, while Permissions give access to the individual resources offered by these APIs. For a detailed explanation of what access you get with each OAuth scope listed in the table above, refer to Registering your OAuth Client.

Migrating applications calling Celonis APIs to OAuth 2.0 from API/Application keys

If you have any application in your Celonis environment using any of the above APIs, then we strongly recommend that you migrate your applications to OAuth 2.0 and move away from long term API/Application keys as Celonis is moving away from these long term keys in the future.

Given below is an example of how you can migrate to OAuth. In this example, we have used Audit log API, Team Login history API and Platform adoption API to show you how you can migrate an application that was previously calling these APIs using an application key to now calling the same APIs using OAuth 2.0.

Connecting audit log, login history, and Studio adoption APIs to Celonis Platform using OAuth 2.0

Within Admin & Settings you can view your audit log, team login history, and studio adoption statistics. However, these views are limited with standardized user interfaces. To run a more in-depth analysis of this data, you can connect to their respective APIs and then use a data extractor to feed this information back into the Celonis Platform. This then lets you create your own views in Studio.

To connect to the APIs and create an extractor, follow these procedures in order:

• Creating an application and granting it API permissions
• Testing OAuth Credentials
• Migrating your Application to OAuth from Appkey/API key
• Troubleshooting
• Additional Info: Creating an extractor and an extraction for APIs .

Once the data is extracted, you can then create a data model using this data. You are then ready to go to Studio and create a view using the data from the API.

Creating an application and granting it API permissions

To start, create an OAuth client in your team and grant this client API permissions.

1. Go to Admin & Settings and select Applications .
2. Click the Add New Application button and then select "OAuth client" to create your OAuth client.

When creating your OAuth client, use the following configurations:

• Authentication method : Client secret post
• Scopes to select :
  • audit.log:read (for the Audit Log API)
  • platform-adoption.tracking-events:read (for the Studio Adoption API)
  • team.login-history:read (for the Login History API)

3. Click Create and then copy the client ID and client secret for later use.
4. Click Permissions and then edit the Team permissions.

5. Assign Audit Log API, Login History API, and Studio Adoption APIs permissions to your newly created application as required.

6. Click Save .
7. Choose the studio for which you want to give permissions. For example, right-click on package > permissions > select your application > use package .

The OAuth client now has the relevant API permissions, but you also need to request an OAuth access token.

Tip

Alternatively, you can create an application key and assign the following permissions: Audit Log API, Login History API, and Studio Adoption APIs.

For more information, see: Registering Application Keys in Celonis Platform.

Testing OAuth credentials

There are multiple ways to test Oauth credentials in Celonis:

Testing OAuth using Postman or command line

The created OAuth credentials can be best tested in Postman or via the command line tool curl (it is installed in most workstations or can be found in the machine learning workbench in Celonis).

Follow the steps outlined in Requesting OAuth access tokens while using the required scopes.

When the credentials are set up correctly you should receive a scope similiar to:

    {
        "access_token": "randomizedAccessToken",
        "scope": "scope 1 scope 2 scopeN",
        "token_type": "Bearer",
        "expires_in": 899
    }

Testing OAuth using Swagger UI

You can now test your APIs with Swagger UI. To do this, you need your team name and environment cluster and your OAuth client from the earlier procedure. You can find your team name and environment cluster from any URL, for example from the Permissions page from the procedure above.

https://[teamname].[realm].celonis.cloud/ui/team/permissions

With your team name and environment cluster, you can then access the Swagger UI using this URL:

https://[teamname].[realm].celonis.cloud/swagger-ui/index.html?configUrl=/log/v3/api-docs/swagger-config

Once on the Swagger UI, follow these steps to test your API:

1. Click Authorize .
2. When using an OAuth client (Recommended), enter "Bearer" followed by a space and then copy the client ID you obtained for the client. For example: Bearer XxxxxxAxxxxBxxxxCxxxXBBBBX
3. Click Authorize . Once the authorization is successful, click Close .
4. Expand the GET call for the API you want to test and click Try it out .
5. Click Execute .

You will now see the response from the API, including the header that shows the Token and the URL.

Migrating your Application to OAuth from Application/API key

Go to the Data Pool where your Data Connection to the Celonis API lies and click on the menu of the data connection.

1. Go to Authorization , add additional authentication and select "OAuth2".
2. Select “Client Credentials” as the Grant type .
3. Add Request Body parameter with key “scope” and value the scopes relevant for the Celonis APIs (separated by blank space, example shows the scope audit.log:read)
4. Get bearer Token with the Endpoint to /oauth2/token.

Go to Data Connection Test:

1. Enter the client ID and client Secret.
2. Select the End point that you have also chosen for AppKey "authentication3".
   1. Define Endpoints: Configure a new endpoint and enter an endpoint name.
   2. Endpoint Configure Request: In URL enter {Connection.API_URL}/ [Enter what is shown in the Swagger doc URL after celonis.com.cloud] So the final text could read:
      Copy

      Copied

      `{Connection.API_URL}/log/api/external/audit?Request parameters and Headers can be completed after as needed).{Connection.API_URL}/log/api/external/audit?`

3. Click Save .
4. Click Build Response .
5. Click Test Connection .
6. Click Finish .
7. See the Troubleshooting section below to resolve any errors.

When the connection test was successful, save the connection. To run the extraction test, go to the data job and manually execute an extraction (e.g. delta extraction).

When the extraction was successful, you can go back to the customization of the extractor builder and delete API Key Authentication.

Troubleshooting

What are the most common errors during authentication and how to fix them.

• Wrong / missing scope
  • Postman
  • Extractor Builder
• Missing permission / 401 unauthorized
  • Postman
  • Extractor Builder
• Incorrect client ID / secret
  • Postman
  • Extractor Builder
• To send as params / request body
  • While creating Application based on the choice
  • Postman
    • If Client basic, send as request params
    • If Client Post, send as request body

Additional info on Creating an Extractor and an Extraction for API Endpoints

In case you are not familiar with how to create an extractor for Celonis APIs or how to create an extraction, then please see the sections below.

Creating an extractor builder for APIs

After testing your APIs, you now need to create an extractor. This extractor pulls detailed information from your team (via the API), allowing you to add this to your Studio views.

The extractor you create in the following steps is without both pagination and headers:

1. From your team, click Data - Data Integration .
2. Click New Data Pool > Create from scratch , add a name, and then click Save .
3. From the data integration diagram, click Connect to Data Source and then select Connect to Data Source .
4. Click Custom and then click the plus icon. Here you have three options:
   • Build a new Extractor
   • Customize a Celonis extractor
   • Import from File (For Audit logs with pagination use this JSON template , this template can also act as the foundation for the Login Log API and the Adoption API).
5. When building a new extractor using the four stage wizard, enter the following information:
   • Extractor name: This can be custom to your extractor.
   • Connection Parameters - Edit API URL: Enter your Celonis team URL in the following format - https://[Your Team].celonis.cloud

Creating an extraction

Once your extractor is built, you can configure delta loads by following these steps:

1. Click Add Extraction .
2. Click on the Parameters tab.
3. Click New Parameters and populate and save the parameters as follows:
   • Placeholder : LastUpdated
   • Name : Last Updated
   • Type : Dynamic
   • Table : AuthenticationEvents
   • Column : timestamp
   • Default value : 01/01/2000, 00:00:00
4. Click on the Tab configuration tab, scroll to Delta Filter Statement and add the following: = from = < %=LastUpdated%>
5. Now add a data model, a data model load and a schedule following the user interface.