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