Setting up an OAuth 2.0 application

To set up a new OAuth application for authentication with the web service:

1.Open the web service page and go to the [Authentication] tab.

2.In the [Authentication] field, select “OAuth 2.0”.

3.In the [Application] field, click [+] (Fig. 1).

Fig. 1 Adding a new OAuth application

 

Populate the OAuth application setup page (Fig. 2). The values are usually available in the web service documentation or via API of that service, e.g., access to Google APIs is available through the [Credentials] section of Google developer console, as well as in the API documentation.

Fig. 2 OAuth application setup page

 

Since different services have different terminology, API and documentation structure, the authentication setup will also be different. Common OAuth setup issues, their causes and cures are available in a separate article.

Below are general recommendations on populating OAuth setup parameters and tips on where to find values to populate these parameters with.

Attention

OAuth authentication setup must be performed both on Creatio side and on the side of the integrated application.

Name

In the [Name] field, enter the name for the new application, which will be displayed in the [Application] field when the users populate it on the [Authentication] tab. You can also select an image to be used as an icon for this OAuth application.

Client ID

In the [Client ID] field, enter the client identifier issued to you by the authorization server of the integrated web service. In the documentation and API of different web services, it may be referred to as:

• Application ID

• Consumer ID

• Public key

This will be the value of the client_id parameter of the request. Read more >>>

Case

Client ID for Google APIs is available in the “Credentials” section of Google APIs console (https://console.developers.google.com), in the “Client ID” field. Read more >>>

Client secret

In the [Client secret] field, enter the “client secret” issued to you by the authorization server. In the documentation and API of different web services, it may be referred to as:

• Application secret

• Consumer secret

• Secret key

This will be the value of the client_secret parameter of the request. Read more >>>

Case

Client secret for Google APIs is available in the “Credentials” section of Google APIs console (https://console.developers.google.com), in the “Client secret” field. Read more >>>

Auth code request URL

In the [Auth code request URL] field, specify the URL, which will serve as an endpoint for requesting an access from the user who can grant it. For example, when Google informs you that an application attempts to receive access to certain information, you act as the “user who can grant access”.

This is the auth_uri parameter of the request. Read more >>>

Case

Auth code request URL for Google APIs is “https://accounts.google.com/o/oauth2/auth”. You can get if from the documentation, describing the example of an OAuth application for integration with Google. Also, it is available in the json file with settings, which can be downloaded from the “Credentials” section of Google developer console.

Access token request URL

In the [Access token request URL] field, specify the URL, which will serve as an endpoint for requesting an access token to use for subsequent requests to the service. Read more >>>

Case

Access token request URL for Google APIs is “https://www.googleapis.com/oauth2/v3/token”. You can get if from the documentation, describing the example of an OAuth application for integration with Google. Also, it is available in the json file with settings, which can be downloaded from the “Credentials” section of Google developer console.

Redirect URL

When setting up OAuth authentication on the web service side, you need to specify URL where the authentication server will redirect users after authentication. This “redirect URL” is displayed on the OAuth application setup page (Fig. 3).

Fig. 3 Redirect URL on the OAuth application setup page in Creatio

 

Make sure that you specify this URL in the settings of the integrated service as the proper redirect URL.

Send client credentials in token request

Select which part of token request will contain the access token. Auth permits variations as to where the token can be passed. In the [Send client credentials in token request] field, you can select from the following available options: “As Basic auth header, “In the request body”, or “In query string as a GET request”. The option to choose depends on the specifics of the third-party system and is usually covered in its documentation.

In request body

A lot of popular services, e.g., Google, Linkedin, JIRA, etc. process requests where access token is passed in the request body.

Case

POST /token HTTP/1.1
Host: server.example.com
Content-Type: application/x-www-form-urlencoded

grant_type=refresh_token&refresh_token=tGzv3JOkF0XG5Qx2TlKWIA
&client_id=s6BhdRkqt3&client_secret=7Fjfp0ZBr1KtDRbnfVdmIw

As Basic auth header

Some services, such as QuickBooks, Docusign, GoToWebinar require that client id and client secret key are passed in the form of basic authentication and would not accept them in the request body. Read more in the IETF documentation.

Case

curl -X POST "https://api.getgo.com/oauth/v2/token" \
-H "Authorization: Basic {Base64 Encoded consumerKey and consumerSecret}" \
-H "Accept:application/json" \
-H "Content-Type: application/x-www-form-urlencoded" \
-d "grant_type=authorization_code&code=
{responseKey}&redirect_uri=http%3A%2F%2Fcode.example.com"

In query string as a GET request

Several services may handle authentication differently. For example, instead of POST request with parameters in body and headings, Facebook uses a token GET request with all parameters specified in the request URL.

Case

https://developers.facebook.com/docs/facebook-login/manually-build-a-login-flow/#confirm\
GET https://graph.facebook.com/v3.2/oauth/access_token?\
client_id={app-id}\
&redirect_uri={redirect-uri}\
&client_secret={app-secret}\
&code={code-parameter}

Revoke token URL

In the [Revoke token URL] field, specify the URL, which will serve as an endpoint for revoking the access token to deny subsequent requests to the service.

This is an optional parameter. In a regular scenario, a user who has access to the integrated service can revoke access to specific OAuth applications. For example, you can disable access to specific applications from your Google account settings.

Case

The URL for making a request to revoke a Google API token is “https://accounts.google.com/o/oauth2/revoke”. You can get if from the Google API documentation.

Log in

Click the [Log in] button, log in to the service using the shared user’s credentials and approve access for Creatio OAuth application.

Scopes

Scopes (also known as “permissions”) are used to grant an application different levels of access to data on behalf of the end user. Scope URLs are usually available in the service documentation. Each API may declare one or more scopes.

Case

Google API scopes, such as “https://www.googleapis.com/auth/gmail.readonly” (permission to view your email messages and settings) are available in the API documentation.