{"componentChunkName":"component---src-templates-simple-markdown-js","path":"/celonis-apis/migrating-to-oauth/","matchPath":"","result":{"data":{"markdownRemark":{"html":"

Migrating to OAuth 2.0

\n

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.

\n

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.

\n

Celonis APIs that currently support OAuth 2.0:

\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n
API NameOAuth Scope
Audit Log APIaudit.log:read
Platform Adoption APIplatform-adoption.tracking-events:read
Team Login History APIteam.login-history:read
Team Members APIteam.user-group-info:read
Process Intelligence APIs (Knowledge Model API, EventSubscription API, Chat API, Tools API)intelligence.conversations:write, intelligence.tools:execute, intelligence.conversations:write, intelligence.subscriptions:manage
Standard Data Ingestion APIintegration.data-pools, integration.data-pools:data-push, integration.data-pools:continuous-data-push
Data Job Execution APIintegration.data-pools
Process Data Model APIintegration.data-pools
SCIM APIuser-provisioning.scim
\n

Important Update: SCIM API is now supported with Microsoft EntraID and OAuth.

\n

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.

\n

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

\n

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.

\n

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, Platform adoption API, and Member / User Group Info 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.

\n

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

\n

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.

\n

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

\n\n

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.

\n

Creating an application and granting it API permissions

\n

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

\n
    \n
  1. \nGo to Admin & Settings and select \nApplications\n.\n
    2. \n
  2. \nClick the \nAdd New Application\n button and then select \"OAuth client\" to create your OAuth client.\n
    3. \n
\n

\n \n \n

\n

When creating your OAuth client, use the following configurations:

\n\n

\n \n \n

\n
    \n
  1. \nClick \nCreate\n and then copy the \nclient ID\n and \nclient secret\n for later use.\n
    2. \n
  2. \nClick \nPermissions\n and then edit the \nTeam\n permissions.\n
    3. \n
\n

\n \n \n

\n
    \n
  1. \nAssign Audit Log API, Login History API, User Group Info API, and Studio Adoption APIs permissions to your newly created application as required.\n
    2. \n
\n

\n \n \n

\n
    \n
  1. \nClick \nSave\n.\n
    2. \n
  2. \nChoose the studio for which you want to give permissions. For example, right-click on \npackage > permissions > select your application > use package\n.\n
    3. \n
\n

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

\n

Tip

\n

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

\n

For more information, see: Creating and granting permissions to application keys.

\n

Testing OAuth credentials

\n

There are multiple ways to test Oauth credentials in Celonis:

\n

Testing OAuth using Postman or command line

\n

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

\n

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

\n

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

\n
\n
\n
Copy
\n
Copied
\n
\n 
    {\n        \"access_token\": \"randomizedAccessToken\",\n        \"scope\": \"scope 1 scope 2 scopeN\",\n        \"token_type\": \"Bearer\",\n        \"expires_in\": 899\n    }
\n
\n

Testing OAuth using Swagger UI

\n

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.

\n
\n
\n
Copy
\n
Copied
\n
\n 
https://[teamname].[realm].celonis.cloud/ui/team/permissions
\n
\n

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

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

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

\n
    \n
  1. \nClick \nAuthorize\n. \n\n \n \n \n
    2. \n
  2. \nWhen using an OAuth client (Recommended), enter \"Bearer\" followed by a space and then copy the client ID you obtained for the client. For example: \nBearer XxxxxxAxxxxBxxxxCxxxXBBBBX\n
    3. \n
  3. \nClick \nAuthorize\n. Once the authorization is successful, click \nClose\n .\n
    4. \n
  4. \nExpand the GET call for the API you want to test and click \nTry it out\n.\n
    5. \n
  5. \nClick \nExecute\n. \n\n \n \n \n
    6. \n
\n

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

\n

Migrating your Application to OAuth from Application/API key

\n

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

\n
    \n
  1. \nGo to \nAuthorization\n, add additional authentication and select \"OAuth2\".\n
    2. \n
  2. \nSelect “Client Credentials” as the \nGrant type\n.\n
    3. \n
  3. \nAdd an additional \nRequest Body\n parameter with the key “scope” and the value for the scopes relevant for the Celonis APIs (separated by blank space, example shows the scope \naudit.log:read\n) \nNOTE:\n The \"scope\" parameter must be added for OAuth. This parameter must be added in the \"Additional request parameter\" section, NOT in the \"Additional Request Header\" field. \n
    4. \n
  4. \nGet bearer Token with the Endpoint to /oauth2/token. \n\n \n \n \n
    5. \n
\n

Go to Data Connection Test:

\n
    \n
  1. \nEnter the client ID and client Secret.\n
    2. \n
  2. \nSelect the End point that you have also chosen for AppKey \"authentication3\".\n
      \n
    1. \nDefine Endpoints:\n Configure a new endpoint and enter an endpoint name.\n
      2. \n
    2. \nEndpoint Configure Request:\n In URL enter {Connection.API_URL}/ \n[Enter what is shown in the Swagger doc URL after celonis.com.cloud]\n So the final text could read: \n
      \n
      \n
      Copy
      \n
      Copied
      \n
      \n 
      `{Connection.API_URL}/log/api/external/audit?Request parameters and Headers can be completed after as needed).{Connection.API_URL}/log/api/external/audit?`
      \n
      \n
      3. \n
    \n
    3. \n
  3. \nClick \nSave\n.\n
    4. \n
  4. \nClick \nBuild Response\n.\n
    5. \n
  5. \nClick \nTest Connection\n. \n\n \n \n \n
    6. \n
  6. \nClick \nFinish\n.\n
    7. \n
  7. \nSee the \nTroubleshooting\n section below to resolve any errors.\n
    8. \n
\n

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

\n

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

  • \nExtractor Builder \n\n \n \n \n
    • \n\n\n
  • \nMissing permission / 401 unauthorized\n\n
    • \n
  • \nIncorrect client ID / secret\n\n
    • \n\n\n\n

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

    \n

    If you are not familiar with how to create an extractor for Celonis APIs or how to create an extraction, refer to the sections below.

    \n

    Creating an extractor builder for APIs

    \n

    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.

    \n

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

    \n
      \n
    1. \nFrom your team, click \nData - Data Integration\n.\n
      2. \n
    2. \nClick \nNew Data Pool > Create from scratch\n, add a name, and then click \nSave\n.\n
      3. \n
    3. \nFrom the data integration diagram, click \nConnect to Data Source\n and then select \nConnect to Data Source\n. \n\n