Set up authorization code grant

OAuth 2.0 is one of the supported authorization types in Creatio. Learn more: OAuth 2.0 authorization types overview.

This article covers setup procedure of authorization code grant. Creatio also supports client credentials grant. Learn more: Set up client credentials grant.

The authorization code grant builds OAuth integration on behalf of a specific user and provides access to Creatio data and API directly for integrated apps inside the user context without granting to their credentials for authentication (Fig. 1). Learn more: official vendor documentation (OAuth 2.0).

Fig. 1 Workflow of authorization code grant

The authorization code grant works with OAuth access and refresh tokens. Learn more: Access Token, Refresh Token (OAuth 2.0 Authorization Framework).

General procedure

1. Perform preliminary setup (for Creatio on-site). Read more >>>
2. Generate OAuth 2.0 client credentials. Read more >>>
3. Connect an integrated app to Creatio. Read more >>>

1. Perform preliminary setup (for Creatio on-site)

Identity Service implements OAuth 2.0 in Creatio and authorizes external apps and web services you integrate with Creatio using OAuth 2.0. Creatio uses Identity Service when processing requests to authorize integrated apps using authorization code grant.

• If you use Creatio in the cloud, the Identity Service is deployed out of the box.
• If you use Creatio on-site, deploy the Identity Service and connect it to Creatio. Instructions: Deploy the Identity Service, Connect the Identity Service to Creatio.

2. Generate OAuth 2.0 client credentials

Important

Generate dedicated OAuth 2.0 client credentials for each external app and web service you need to authorize using authorization code grant.

To generate OAuth 2.0 client credentials:

1. Open the System Designer. To do this, click in the top right.

2. Open the OAuth integrated applications page (Fig. 2). To do this, click OAuth 2.0 integrated applications in the Import and integration block.

   Fig. 2 OAuth integrated applications page

   

3. If you use Creatio on-site, make sure that all checkboxes on the Diagnostic tab are selected (Fig. 3).

   Fig. 3 Diagnostic tab

   

   If at least one of the checkboxes is cleared, identify potential issues or errors in the Identity Service or OAuth setup and usage. Instructions: OAuth health monitoring.

4. Click New → On behalf of a user (authorization code). This opens a new record window.

5. Fill out primary parameters of the external app (Fig. 4).

   Fig. 4 Fill out primary parameters of the external app

   

   Parameter	Parameter value
   Name*	Name of the integration that Creatio and logs will use. Required.
   Application URL	The URL of the external app or web service.
   Description	The purpose of the integration.

6. Save the changes. This opens the integration page (Fig. 5).

   Fig. 5 Integration page

   

7. Open the Settings tab.

8. Fill out additional parameters of the external app.

   Parameter	Parameter value
   Application logo	Logo of integrated app. Application logo is used on the External applications tab of the user profile page and on the consent page when integrating an external application. To upload the file: Click . Select the image file on your device. Save the changes.
   Authorized redirect URIs	Redirect URIs to receive authorization codes when authorizing integrated app. Each URI must match the redirectUrl parameter used in the OAuth request from integrated app. This ensures secure redirection after a user grants access. Specify one or more redirect URIs. If no URI is authorized to receive authorization code, the request will be rejected. To add the redirect URI: Click . Enter the URI. Save the changes. To delete the redirect URI, click → Delete. Once you delete the redirect URI, Creatio will no longer be able to send authorization codes to a deleted redirect URI.
   Permitted users	Creatio users who are permitted to authorize integrated app via authorization code grant. Users omitted from the Permitted users expanded list are blocked on the consent page. After the permitted user grants access, the external application receives access to data and functionality of this user. Creatio lets you update the list of permitted Creatio users at any time. To add a permitted Creatio user: Click . This opens the Select users for the OAuth client application window. Select the user. Save the changes.

9. Save the changes.

As a result:

• The "Client Id" and "Client secret" parameters will be populated and displayed on the Credentials expanded list (Fig. 5). Use these parameter values in external app or web service you integrate with Creatio using authorization code grant.

• The new integration will be added to the OAuth integrated applications page (Fig. 6).

  Fig. 6 OAuth integrated applications page

  

3. Connect an integrated app to Creatio

1. Log in to the external app to integrate with Creatio.

2. Execute an action that launches authorization code grant. For example, click the link. This opens the Creatio login page.

3. Log in to Creatio. This displays consent page (Fig. 7).

   Fig. 7 Consent page

   

   The consent page includes the following:

   • application logo specified in the Application logo parameter on the integration page
   • name of the integration specified in the Name parameter on the integration page
   • URL of your Creatio instance that the external app can access
   • alerts about data and API available for the external app after granting access

4. Switch Creatio user if needed.

   1. Click Switch. This opens Creatio login page.
   2. Enter user credentials.
   3. Log in to Creatio.

   After successful login, Creatio redirects you to the consent page.

5. Grant access to Creatio data and API. To do this, click Accept.

As a result, consent page redirects you to the page specified in the Authorized redirect URIs expanded list on the integration page (Fig. 8).

Fig. 8 External app

If the error occurs when granting access (Fig. 9), the consent page displays one of the responses listed in the table below.

Fig. 9 Error occurs when granting access

Error	Description	Solution
Integration not found	Unable to launch authorization code grant because there is no registered active external app with the provided "Client Id" and authorized redirect URIs.	Contact system administrators (for Creatio on-site and custom OAuth integrations configured in Creatio in the cloud) or Creatio support (for out-of-the-box OAuth integrations) to execute the following actions: Make sure that external app is passing the correct client Id. Make sure that external app is passing the correct redirect URI. If the redirect URI is correct but omitted in the Authorized redirect URIs expanded list on the integration page, add the redirect URI. Read more >>>
Access to integration is not permitted	Unable to continue with granting access to Creatio data and API because your Creatio account is not permitted to use this integration.	Contact system administrators to make sure that Creatio user is added to the Permitted users expanded list on the integration page. Otherwise, add the user. Read more >>> Only internal users are permitted to grant access to external apps.
Authorization request expire	Unable to complete the authorization because time to pass the consent is limited and was omitted.	Relaunch the authorization code grant from external app.
Integration setup error	Unable to launch the authorization code grant because the request is incorrect. One or more required parameters are incorrect or omitted.	Contact system administrators (for Creatio on-site and custom OAuth integrations configured in Creatio in the cloud) or Creatio support (for out-of-the-box OAuth integrations) to execute the following actions: Using external app you integrate with Creatio or Network tab in browser debugging tools, make sure that the following required parameters are correct: client_id redirect_uri response_type scope state Fix the parameter that causes the error. Learn more: Authorize external requests using authorization code grant (developer documentation).

The next steps depend on your business goals. Use OAuth 2.0 client credentials in the following ways:

• Authorize ready-to-use external apps and web services you integrate with Creatio. For example, Creatio.ai add-in for Outlook.
• Provide OAuth 2.0 client credentials to colleagues or partners who need to work with your Creatio instance using API.
• Authorize self-developed external apps and web services you integrate with Creatio. Learn more: Authorize external requests using authorization code grant (developer documentation).

You can set up automated monitoring systems based on OAuth health monitoring. Instructions: OAuth health monitoring. If needed, use Postman to check the health of OAuth functionality. The Postman request collection that tests requests is available in Creatio API documentation.

Operations with OAuth integrations

Modify the integration parameters

If the settings of the external app change, you can modify the parameters of the previously created integration. To do this:

1. Open the System Designer. To do this, click in the top right.
2. Open the OAuth integrated applications page. To do this, click OAuth 2.0 integrated applications in the Import and integration block.
3. Open the page of integration whose parameters you want to modify.
4. Modify the needed parameters.
5. Save the changes.

As a result:

• The parameters for external app integration will be updated.
• The "Client Id" and "Client secret" parameters will remain unchanged.

Monitor list of users who granted access

Creatio lets you monitor list of users who granted access to Creatio data and API from integrated app. To do this:

1. Open the System Designer. To do this, click in the top right.
2. Open the OAuth integrated applications page. To do this, click OAuth 2.0 integrated applications in the Import and integration block.
3. Open the integration page.
4. Open the Monitoring tab.

As a result, the Monitoring tab will display the following information:

• a list of Creatio users who confirm access to Creatio from integrated app (the "User" column)
• exact date and time when the user granted access (the "Date of access sharing" column)
• status of access sharing for the user (the "Access active" column). If the Access active checkbox is selected, the integrated app is still authorized to access Creatio data and API. Otherwise, the integrated app is not authorized to access Creatio data and API.

Revoke the integration access

Creatio lets you revoke the integration access without deleting it. For example, when an integrated external app generates high-load requests, revoke the integration access temporarily to solve the issue. Creatio lets you revoke integration access in the following ways:

• revoke the integration access for Creatio instance
• revoke entire integration access for a dedicated Creatio user
• revoke current integration access for a dedicated Creatio user

Revoke the integration access for Creatio instance

1. Open the System Designer. To do this, click in the top right.
2. Open the OAuth integrated applications page. To do this, click OAuth 2.0 integrated applications in the Import and integration block.
3. Clear the Active checkbox for a dedicated integration.
4. Save the changes.

As a result, integration access will be revoked for Creatio instance temporarily.

To resume the integration, select the Active checkbox for a dedicated integration.

Revoke entire integration access for a dedicated Creatio user

We recommend using this option if you need to block integration access of some users completely.

If system administrators revoke integration access for a dedicated Creatio user entirely, integration is no longer displayed on the External applications tab of the user profile page and the user can no longer re-connect integrated app to Creatio. Only system administrators can resume integration access by re-adding user to the Permitted users expanded list so that the user can re-grant access to Creatio. Read more >>>

To revoke entire integration access for a dedicated Creatio user:

1. Open the System Designer. To do this, click in the top right.
2. Open the OAuth integrated applications page. To do this, click OAuth 2.0 integrated applications in the Import and integration block.
3. Open the integration page.
4. Open the Settings tab.
5. Go to the Permitted users expanded list.
6. Click → Delete for the user for whom you would like to revoke access.
7. Save the changes.

As a result:

• integration access will be revoked for a dedicated Creatio user entirely
• the Access active checkbox on the Monitoring tab of integration page will be cleared

Revoke current integration access for a dedicated Creatio user

We recommend using this option if you need to force users to re-consent to connect an external app to Creatio or fix some issues.

If system administrators revoke current integration access for a dedicated Creatio user, integration is still displayed on the External applications tab of the user profile page and user can re-grant the external app access to Creatio to resume integration access. Read more >>>

To revoke current integration access for a dedicated Creatio user:

1. Open the System Designer. To do this, click in the top right.

2. Open the OAuth integrated applications page. To do this, click OAuth 2.0 integrated applications in the Import and integration block.

3. Open the integration page.

4. Open the Monitoring tab.

5. Revoke integration access.

   • For a dedicated Creatio user, select the user for whom you would like to revoke access and click Revoke.
   • For all Creatio users, click → Revoke access for all users.

6. Save the changes.

As a result:

• the current integration access will be revoked for a dedicated Creatio user
• the Access active checkbox on the Monitoring tab of integration page will be cleared
• the integrated app will be moved from the Connected external applications expanded list to the Available external applications expanded list on the External applications tab of the user profile page

Additionally, you can revoke current integration access for a dedicated Creatio user using External applications tab of the user profile page. Instructions: Manage integrated apps on the user profile page.

---

See also

Deploy the Identity Service

Connect the Identity Service to Creatio

OAuth health monitoring

Authorize external requests using authorization code grant (developer documentation)

---

E-learning courses

Tech Hour - Integrate like a boss with Creatio, part 2 (Odata)