Authorize external requests using authorization code grant

Level: intermediate

OAuth 2.0 is one of the supported authorization types in Creatio. This technology does not pass Creatio logins and passwords to external apps. Identity Service implements OAuth 2.0 in Creatio and authorizes external apps and web services you integrate with Creatio using OAuth 2.0. OAuth 2.0 also lets you restrict Creatio permissions for the integrated apps. For example, you can use OAuth 2.0 authorization to integrate webhook service, Power BI Connector, Clio, Creatio.ai add-in for Outlook with Creatio. Learn more: official vendor documentation (OAuth 2.0).

Before you authorize external requests to Creatio, set up OAuth authorization of authorization code grant. Instructions: Set up authorization code grant (user documentation).

This article covers setup procedure to authorize external requests using authorization code grant. Creatio also supports client credentials grant. Learn more: Authorize external requests using client credentials grant.

General procedure

1. Retrieve an authorization code. Read more >>>
2. Retrieve access and refresh OAuth tokens. Read more >>>

1. Retrieve an authorization code

Learn more about authorization code: Authorization Code (OAuth 2.0 Authorization Framework).

To retrieve an authorization code:

1. Find the endpoint to retrieve an authorization code. To do this, access the {CreatioURL}/0/.well-known/openid-configuration URL from the browser. This discovery endpoint displays a list of all OAuth endpoints available for your Creatio instance. The authorization_endpoint parameter includes the endpoint to retrieve an authorization code.

   If an external app to integrate with Creatio supports the discovery endpoint or you develop a custom external app, you can use the discovery endpoint to receive OAuth endpoints dynamically without storing this value in your external app.

2. Create a request.

   1. Access the /connect/authorize endpoint.

   2. Fill out the parameters of the request string.

      Parameter	Description
      client_id*	The ClientId parameter value retrieved while configuring authorization code grant. Find the parameter value in the Client Id field on the integration page. Learn more: Generate OAuth 2.0 client credentials (user documentation).
      redirect_uri*	Redirect URIs to receive authorization codes when authorizing an integrated app. Find the parameter value in the Authorized redirect URIs expanded list on the integration page.
      response_type*	Requires the code parameter value.
      scope*	The scope of the request execution. Represents the list of permissions that the external app receives after granting the consent. Creatio supports the following scopes: offline access to work with OAuth refresh token application access to access Creatio instance inside context of user who grants consent. Application access value is unique for each Creatio instance. Find the parameter value in the Name column of the OAuth resource lookup. Since version 8.3.4, the ApplicationAccess scope is not required in the authorization code grant request. Creatio adds it to the issued token by default after authorization. To use this functionality, enable the AddApplicationAccessScopeAutomatically additional feature. Use percent-encoded space ("%20") as a delimiter of scope list.
      state*	If you use an existing external app, the external app must populate the state parameter value. If you use a custom external app, implement business logic that generates an arbitrary sequence of characters every time you use the state parameter to ensure CSRF protection. Ensure that Creatio returns the same value of the state parameter to the custom external app after the user confirms access to Creatio from the integrated app. If returned and sent parameter values are different, recognize it as a potential attack.

      The following example requests an authorization code below.

      Request string

      GET {CreatioURL}/0/connect/authorize?client_id=7******3&redirect_uri=https://SomeRedirectURL&response_type=code&scope=offline_access%20ApplicationAccess_2******e&state=xyz

3. Execute the request.

   • For a browser external app, execute the request in a new browser tab or perform redirect in the current tab.
   • For a desktop external app, open a separate browser window whose size is no smaller than 730x560 pixels to display the consent page.

As a result:

1. The user will be redirected to the Creatio login page.
2. When the user logs in to the Creatio instance, Creatio will confirm the validity of the user credentials and redirect the user to the consent page.
3. When the user confirms access to Creatio from the integrated app, Creatio will pass the authorization code to the external app using the specified redirect URI.

You can now retrieve access and refresh OAuth tokens. Learn more: Access Token, Refresh Token (OAuth 2.0 Authorization Framework).

2. Retrieve access and refresh OAuth tokens

1. Find the endpoint to retrieve access and refresh OAuth tokens. To do this, access the {CreatioURL}/0/.well-known/openid-configuration URL from the browser. This discovery endpoint displays a list of all OAuth endpoints available for your Creatio instance. The token_endpoint parameter includes the endpoint to retrieve access and refresh OAuth tokens.

2. Create a request.

   1. Access the /connect/token endpoint.

   2. Fill out the parameters of the request string.

      Parameter	Description
      client_id*	The ClientId parameter value retrieved while configuring authorization code grant. Find the parameter value in the Client Id field on the integration page. Learn more: Generate OAuth 2.0 client credentials (user documentation).
      client_secret*	The Client secret parameter value retrieved while configuring authorization code grant. Find the parameter value in the Client secret field on the integration page. Learn more: Generate OAuth 2.0 client credentials (user documentation).
      grant_type*	OAuth 2.0 authorization type. Find the parameter value in the Grant type column on the OAuth integrated applications page. Requires the authorization_code value of the grantType parameter to retrieve access and refresh OAuth tokens for authorization code grant.
      scope*	The scope of the request execution. Represents the list of permissions that the external app receives after granting the consent. Creatio supports the following scopes: offline access to work with OAuth refresh token application access to access Creatio instance inside context of user who grants consent. Application access value is unique for each Creatio instance. Find the parameter value in the Name column of the OAuth resource lookup. Since version 8.3.4, the ApplicationAccess scope is not required in the authorization code grant request. Creatio adds it to the issued token by default after authorization. To use this functionality, enable the AddApplicationAccessScopeAutomatically additional feature. Use percent-encoded space ("%20") as a delimiter of scope list.
      redirect_uri*	Redirect URIs to receive authorization codes when authorizing an integrated app. Find the parameter value in the Authorized redirect URIs expanded list on the integration page.
      code*	The authorization code retrieved on the previous step.
      content-type*	Requires the application/x-www-form-urlencoded parameter value.

      The following example requests access and refresh OAuth tokens below.

      Request string

      POST {CreatioURL}/0/connect/token?client_id=7******3&client_secret=2******6&grant_type=authorization_code&scope=offline_access%20ApplicationAccess_2******e&state=xyz&redirect_uri=https://SomeRedirectURL&code=0******F
      
      Content-Type: application/x-www-form-urlencoded

3. Execute the request.

As a result, Creatio will confirm the validity of the authorization code and OAuth 2.0 client credentials and return the access and refresh OAuth tokens to authorize external requests using authorization code grant.

The access and refresh OAuth tokens used by authorization code grant have a finite lifetime out of the box:

• 3 minutes for access token
• 48 hours for refresh token

Update access and refresh OAuth tokens

Update access and refresh OAuth tokens to maintain the connection between the external app and Creatio. When the refresh token expires, retrieve it again. Read more >>>

To update access and refresh OAuth tokens:

1. Find the endpoint to update access and refresh OAuth tokens. To do this, access the {CreatioURL}/0/.well-known/openid-configuration URL from the browser. This discovery endpoint displays a list of all OAuth endpoints available for your Creatio instance. The token_endpoint parameter includes the endpoint to update access and refresh OAuth tokens.

2. Create a request.

   1. Access the /connect/token endpoint.

   2. Fill out the parameters of the request string.

      Parameter	Description
      client_id*	The ClientId parameter value retrieved while configuring authorization code grant. Find the parameter value in the Client Id field on the integration page. Learn more: Generate OAuth 2.0 client credentials (user documentation).
      client_secret*	The Client secret parameter value retrieved while configuring authorization code grant. Find the parameter value in the Client secret field on the integration page. Learn more: Generate OAuth 2.0 client credentials (user documentation).
      grant_type*	Requires the refresh_token parameter value.
      scope*	The scope of the request execution. Represents the list of permissions that the external app receives after granting the consent. Creatio supports the following scopes: offline access to work with OAuth refresh token application access to access Creatio instance inside context of user who grants consent. Application access value is unique for each Creatio instance. Find the parameter value in the Name column of the OAuth resource lookup. Since version 8.3.4, the ApplicationAccess scope is not required in the authorization code grant request. Creatio adds it to the issued token by default after authorization. To use this functionality, enable the AddApplicationAccessScopeAutomatically additional feature. Use percent-encoded space ("%20") as a delimiter of scope list.
      redirect_uri*	Redirect URIs to receive authorization codes when authorizing an integrated app. Find the parameter value in the Authorized redirect URIs expanded list on the integration page.
      refresh_token*	The OAuth refresh token retrieved on the previous step.
      content-type*	Requires the application/x-www-form-urlencoded parameter value.

      The following example updates an OAuth refresh token below.

      Request string

      POST {CreatioURL}/0/connect/token?client_id=7******3&client_secret=2******6&grant_type=refresh_token&scope=offline_access%20ApplicationAccess_2******e&state=xyz&redirect_uri=https://SomeRedirectURL&refresh_token=D******5
      
      Content-Type: application/x-www-form-urlencoded

3. Execute the request.

As a result, Creatio will return updated access and refresh OAuth tokens to authorize external requests using authorization code grant.

Revoke an OAuth refresh token

Revoke an OAuth refresh token to implement a logout feature in a custom external app that disconnects the external app from the Creatio account. To establish connection, retrieve an authorization code. Read more >>>

To revoke an OAuth refresh token:

1. Find the endpoint to revoke an OAuth refresh token. To do this, access the {CreatioURL}/0/.well-known/openid-configuration URL from the browser. This discovery endpoint displays a list of all OAuth endpoints available for your Creatio instance. The revocation_endpoint parameter includes the endpoint to revoke an OAuth refresh token.

2. Create a request.

   1. Access the /connect/revocation endpoint.

   2. Fill out the parameters of the request string.

      Parameter	Description
      client_id*	The ClientId parameter value retrieved while configuring authorization code grant. Find the parameter value in the Client Id field on the integration page. Learn more: Generate OAuth 2.0 client credentials (user documentation).
      client_secret*	The Client secret parameter value retrieved while configuring authorization code grant. Find the parameter value in the Client secret field on the integration page. Learn more: Generate OAuth 2.0 client credentials (user documentation).
      token*	The OAuth refresh token to revoke.
      token_type_hint	Requires the refresh_token parameter value.
      content-type*	Requires the application/x-www-form-urlencoded parameter value.

      The following example updates an OAuth refresh token below.

      Request string

      POST {CreatioURL}/0/connect/revocation?client_id=7******3&client_secret=2******6&token=2******1&token_type_hint=refresh_token
      
      Content-Type: application/x-www-form-urlencoded

3. Execute the request.

As a result, Creatio will return the following:

• 200 OK status code if the OAuth refresh token is revoked or non-existent.
• 4xx client error status code if an error occurs while processing the request.

---

See also

Set up authorization code grant (user documentation)

---

Resources

Official vendor documentation (OAuth 2.0 Authorization Framework)