Set up the web service authentication
Depending on the web service specifics, you may need to authenticate the service before it becomes available. Creatio supports two authentication types for web service integrations:
- OAuth 2.0 Authorization — a secure authentication option supported by most popular service providers, including Facebook, Google, and Amazon.
- Basic HTTP authentication — an authentication option that passes a login and a password during the web service request. The HTTP authentication compares this data with the login details passed from Creatio during the web service integration setup. This authentication method is simpler to implement, but less secure.
Set up the basic authentication
To enable the HTTP authentication:
-
Retrieve the login credentials for the basic authentication. The way to retrieve the credentials depends on the web service.
-
Open the System settings section and add the following settings:
- A “Text” type system setting that stores the web service login.
- An “Encrypted string” type system setting that stores the web service password.
Creatio binds the system settings used during the authentication to the package that contains the web service integration settings.
ImportantSince Creatio does not populate the system settings when binding them to packages, Creatio will not save the login and password when moving the package to a different environment. As such, specify the login credentials in the system settings once again after deploying the package with the web service integration functionality to the environment.
-
Set the system setting values to the web service authentication login and password.
-
Open the web service page and go to the Authentication tab.
-
Select “Basic” in the Authentication dropdown.
-
Select the system settings that contain the web service login and password in the Username and Password fields (Fig. 1).
-
Click Save.
Set up the OAuth authentication
Set up the integration with an existing OAuth 2.0 application
If you have already set up the OAuth application (e. g., when installing a package with the web service integration settings), follow these steps to set up the OAuth authentication:
-
Go to the Studio workplace and open the Web services section. Open the web service page and go to the Authentication tab.
-
Select “OAuth 2.0” in the Authentication dropdown.
-
Select an existing OAuth application in the Application dropdown (Fig. 2).
-
Click Save.
Set up a new OAuth 2.0 application
To set up a new OAuth application with OAuth 2.0 authentication method:
- Go to the Studio workplace and open the Web services section. Open the web service page and go to the Authentication tab.
- Select “OAuth 2.0” in the Authentication dropdown.
- Click + in the Application field (Fig. 3).
Fill out the OAuth application setup page (Fig. 4). You can usually find the needed settings in the web service documentation or retrieve the settings via the service API. For instance, the data to access the Google API is available in the Credentials section of the Google developer console, as well as in the API documentation.
You have to set up the OAuth authentication both in Creatio in the external application.
If you are using Creatio on-site, the address of the relevant web service must be available on your server for the authentication to work properly.
See the general recommendations on filling out the OAuth setup parameters, as well as the tips on how to retrieve the correct parameter values, below.
-
Name — specify the name of the new application. Creatio will display the name on the Authentication tab in the Application field. You can also select an image that will serve as this application's icon.
-
Client ID — specify the client identifier issued by the integrated web service's authorization server. The web service documentation and API may also refer to the identifier as:
- Application ID
- Consumer ID
- Public key
This identifier will be the value of the client_id request parameter. Read more in the IETF Tools documentation. For example, you can find the Client ID for the Google API in the “Client ID” field of the Google API console's (https://console.developers.google.com) Credentials section. Read more in the Google documentation.
-
Client secret — specify the secret key provided by the authorization server. The web service documentation and API may also refer to the secret key as:
- Application secret
- Consumer secret
- Secret key
This key will be the value of the client_secret request parameter. Read more in the IETF Tools documentation. For example, you can find the Client secret for the Google API in the “Client ID” field of the Google API console's (https://console.developers.google.com) Credentials section. Read more in the Google documentation.
-
Auth code request URL — specify the URL that will serve as an endpoint to request access from the user who can grant it. For example, when Google informs you that an application attempts to gain access to certain data, you act as the “user who can grant access.”
This is the auth_url parameter of the request. Read more in the IETF Tools documentation. For instance, the auth code request URL for the Google API is https://accounts.google.com/o/oauth2/auth. You can find this URL in Google's OAuth application integration example. The URL is also available in the JSON settings file you can download from the “Credentials” section of the Google developer console.
-
Access token request URL — specify the URL that will serve as an access token request endpoint during the web service call. Read more in the IETF Tools documentation. For example, the access token request URL for the Google API is
https://www.googleapis.com/oauth2/v3/token
. You can find this URL in Google's OAuth application integration example. The URL is also available in the JSON settings file you can download from the “Credentials” section of the Google developer console. -
Redirect URL — specify the URL where the authentication server will redirect the users after successful authentication. Creatio displays this redirect URL on the OAuth authentication setup page (Fig. 5).
Make sure that you specify the correct redirect URL in the integrated service settings.
-
Send client credentials in token requests — specify the part of the token request that will contain the access token. The authorization allows for several ways to pass the token. You can select from several options in the Send client credentials in token requests dropdown. The option you need to select depends on the third-party system specifics and is usually covered in the system documentation.
-
“In request body.” Many popular services, e. g., Google, Linkedin, JIRA, etc., process requests with the access token in the request body. For instance:
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, e. g,. Docusign, GoToWebinar, require the client id and the client secret key to be passed as headers and will not accept them in the request body. Read more in the IETF documentation. For instance:
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.” Some services handle authentication differently. For example, Facebook uses a token GET request with all parameters specified in the request URL instead of a POST request with parameters in the body and headers. For instance:
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 — specify the URL that will serve as an access token revoke endpoint if the web service denies the respective calls. The field is not required. In a regular scenario, a user with access to the integrated web service can revoke access to specific OAuth applications. For example, you can disable access to specific applications from your Google account settings. The token revoke request URL for the Google API is
https://accounts.google.com/o/oauth2/revoke
. You can retrieve this URL from the Google API documentation. -
Log in — click this button to log in to the web service with the shared user's credentials and allow Creatio to access the third-party application.
-
Scopes — grant the application different data access levels on behalf of the end user. The Scope URLs are usually available in the web service documentation. Each API may declare one or more scopes. For instance, the Google API scopes, such as
https://www.googleapis.com/auth/gmail.readonly
(permission to view the email messages and settings), are available in the API documentation.
Since different services use different terminology and have different API and documentation structure, the authentication setup procedure may vary. Find the common OAuth setup issues and the ways to solve them below.
Common OAuth application setup issues
This is a list of common issues you may encounter when integrating the web services with OAuth 2.0 authentication.
The specified connection settings are invalid or out-of-date
The connection settings are different from those in the integrated application. The error may appear for the Client ID, Client secret, as well as the Auth code request URL, Access token request URL, and Access token revoke URL values.
The error may occur in the following cases:
- Adding a user to the OAuth application page.
- Calling the web service.
Make sure that you filled out all the fields on the OAuth application setup page and the values you specified are the same as the corresponding settings in the third-party application. After that, try adding a new user again.
There is an incorrect redirect URL in the external application
You have to set up the OAuth authentication both on Creatio's end and on the external application's end. Due to security requirements, a special URL has to redirect the user after the authentication server issues the access token. The redirect URL's domain often requires a separate verification.
The error may occur when adding a user to the OAuth application page.
Creatio displays the correct redirect URL on the OAuth application setup page (Fig. 6).
Copy this URL to the corresponding external application settings (Fig. 7).
If the link in the external service does not match the link on the OAuth application setup page in Creatio, it will be impossible to receive the access token.
As such, copy the correct redirect URL from the OAuth application setup page in Creatio to the corresponding field in the external application settings to resolve this issue.