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 endpoint to retrieve an authorization code.

   If external app to integrate with Creatio supports discovery endpoint or you develop custom external app, you can use 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	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 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 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. 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 custom external app, implement business logic that generates 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 custom external app after user confirm access to Creatio from integrated app. If returned and sent parameter values are different, recognize it as potential attack.

      View the example that 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 an 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. User will be redirected to Creatio login page.
2. When user logs in to Creatio instance, Creatio will confirm the validity of user credentials and redirect user to consent page.
3. When user confirms access to Creatio from integrated app, Creatio will pass the authorization code to the external app using 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 endpoint to retrieve access and refresh OAuth token.

2. Create a request.

   1. Access the /connect/token endpoint.

   2. Fill out the parameters of the request string.

      Parameter	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 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. Use percent-encoded space (%20) as a delimiter of scope list.
      redirect_uri*	Redirect URIs to receive authorization codes when authorizing 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.

      View the example that 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 authorization code and OAuth 2.0 client credentials and return the access and refresh OAuth tokens to authorize external requests using authorization code grant.

Each access and refresh OAuth tokens used by authorization code grant has 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 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 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	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 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. Use percent-encoded space (%20) as a delimiter of scope list.
      redirect_uri*	Redirect URIs to receive authorization codes when authorizing 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.

      View the example that 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 logout feature in custom external app that disconnects external app from 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 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	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.

      View the example that 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)