OAuth application common setup issues
This article contains an overview of several typical issues that you may encounter when setting up integration with a web service using authentication via OAuth 2.0. More information is available in the “Setting up an OAuth 2.0 application” article.
Contents
•Connection settings are invalid or out-of-date
•Incorrect Redirect URL is specified in the integrated third-party application
•Insufficient permissions (scopes) to perform an operation
•The scopes must be specified in the integrated application
•The scopes requested by Creatio are denied during login
•Other access limitations have been set up in the integrated service
•The application is awaiting the client ID and client secret in the other part of the query
•“Missing refresh token” on login
Connection settings are invalid or out-of-date
The connection settings are different from those in the integrated application. The error may appear in the Client ID, Client secret, authentication and token URLs and Scopes.
When does the error appear
-
The error appears when adding a user on the OAuth application page.
-
The error appears when calling the web service (i.e., Creatio attempts to obtain access using invalid settings).
How to fix
Verify each setting on the OAuth application setup page in Creatio, make sure that they match the corresponding settings in the integrated third-party application. After that, attempt to add a new user again.
Incorrect Redirect URL is specified in the integrated third-party application
OAuth authentication setup must be performed both on Creatio side and on the side of the integrated application. Security requirements often involve specific URL for redirecting after access token is issued by the authentication server. Also, the domain for redirection URL often requires separate verification.
The proper redirect URL is displayed on the OAuth application setup page in Creatio (Fig. 1).
Fig. 1 Redirect URL on the OAuth application setup page in Creatio
This URL must be copied to the corresponding settings of the integrated third-party application (Fig. 2).
Fig. 2 Entering a redirect URI in Google API
If the link specified in the integrated third-party application does not match the one on the OAuth application setup page in Creatio, access token will not be issued.
When does the error appear
The error appears when adding a user on the OAuth application page.
How to fix
Specify correct redirect URL by copying the URL from the OAuth application setup page in Creatio to the corresponding field in the integrated third-party application.
Insufficient permissions (scopes) to perform an operation
In OAuth 2.0, the access token is often issued with specific limited permissions to call functions of the integrated application. For example, applications may have a separate scopes for reading and modifying data. In this case, the list of needed scopes must be specified in Creatio, the integrated service, or upon user login.
The scopes must be specified in Creatio, on the [Scopes] detail of the OAuth application setup page. Creatio will be requesting these scopes when the user logs in to authentication server. If the needed scope has not been added to the [Scopes] detail, it is likely that the user will not be able to log in.
When does the error appear
When attempting to call the integrated web service, for example, to modify its data without sufficient scopes, the integrated application will return an error.
How to fix
1.Add all needed scopes to the [Scopes] detail.
2.Delete the integrated service user from Creatio, so that the previously issued access token is revoked.
3.Revoke access for Creatio application in the integrated service (e.g., you can disable access to specific applications from your Google account settings).
4.Add the user once again.
The scopes must be specified in the integrated application
Sometimes, the scopes must be specified in the integrated application. For example, the extent of permissions can be specified during the application setup in the integrated service. In this case, the scopes specified in Creatio must correspond to those permitted for this application in the integrated service.
When does the error appear
Depending on the architecture of the integrated application, the following scenarios are possible if scopes specified in Creatio exceed those permitted in the integrated service:
-
The user will be unable to log in.
-
When attempting to call the integrated web service to modify its data, the integrated application will return an error.
How to fix
If the user is unable to log in:
1.Add the needed scope in the integrated application.
2.Attempt to log in again.
If the integrated application returns an error when attempting to call the integrated web service to modify its data:
1.Add the needed scope in the integrated application.
2.Delete the integrated service user from Creatio, so that the previously issued access token is revoked.
3.Revoke access for Creatio application in the integrated service (e.g., you can disable access to specific applications from your Google account settings).
4.Add the user once again.
The scopes requested by Creatio are denied during login
The properly specified scopes in Creatio may be denied during login attempt. In some applications, e.g., Facebook, the list of scopes that are actually issued can be modified by the user of the integrated service during login.
For example, reading and modifying the data (2 records on the [Scopes] detail) are permitted in the application settings by default. On login, the user cleared checkbox for modifying data. In this case, when Creatio requests access to reading and modifying the data, the application will issue the token only with the permission to read data, which will be added to Creatio.
When does the error appear
When attempting to call the integrated web service to modify its data, the integrated application will return an error.
How to fix
1.Delete the integrated service user from Creatio, so that the previously issued access token is revoked.
2.Revoke access for Creatio application in the integrated service (e.g., you can disable access to specific applications from your Google account settings).
3.Add the user to Creatio again, this time selecting all needed scoped during login.
The “Use authentication” checkbox is not selected in the web service method or wrong authentication method selected
This is not an OAuth-specific issue, rather it refers to the entire web service integration setup process. Its symptom is “Web service replies with 403 Unauthorized” error.
When does the error appear
The error appears when calling the web service (i.e., Creatio attempts to connect without passing of an access token).
How to fix
Set proper authentication type on the [Authentication] tab of the web service setup page and/or select the "Use authentication" checkbox in web service methods.
Other access limitations have been set up in the integrated service
Some services may limit access by IP or domains. For example, Facebook may limit access by domains.
When does the error appear
The error appears when adding a user on the OAuth application page.
How to fix
Add and verify your Creatio application IP and/or domain on the integrated service side.
The application is awaiting the client ID and client secret in the other part of the query
When requesting or updating token, Creatio by default includes client id and client secret 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
Most services, e.g., Google, Linkedin, JIRA, etc. will process such request.
However, there may be a service, which would not accept client id and client sectet in the request body. OAuth permits variations in this case.
For example, QuickBooks, Docusign, GoToWebinar pass client id and client secret in the form of basic authentication.
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"
This method is covered in RFC, as an alternative to the approach supported by Creatio.
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.
When does the error appear
When the user attempts to log in to application. In this case, the login fail.
How to fix
Currently, there are no other ways of sending client id and client secret in Creatio.
“Missing refresh token” on login
Refresh token is required to update access token automatically. As a result, integration will be working for as long as the token stays updated, without the need to confirm access. The refresh token is not always used. Depending on the architecture of the integrated application, this may or may not constitute an actual integration error.
There are three typical cases:
Application token does not expire
The integrated application issues an access token, which does not expire (no need to update it). This is a rare case. Despite the warning, the integration may be operational for long periods of time.
How to fix
Study the documentation of the integrated service. Make sure that it actually does not issue refresh tokens and does issue access tokens that do not expire. In this case, you may disregard the warning and continue working with intergated service.
Application was not built to update its access tokens
The integrated application issues an access token, which will eventually expire, but cannot be updated due to limitations of the integrated application. This is often the case with billing applications which by design should not grand long-term access.
Such applications will not work with shared user, as common user is a means of not having each Creatio user log in separately to the integrated application.
How to fix
Study the documentation of the integrated service. Make sure that it actually does not issue refresh tokens and does issue access tokens that do expire.
Token updating must be enabled in the application settings
The integrated application issues an access token, which will eventually expire. The token cannot be updated due to the integrated application current settings. For example, application may have a separate scope for requesting refresh token.
How to fix
1.Study the documentation of the integrated service. Make sure that it actually does issue refresh tokens.
2.Find out which settings permit issuing refresh tokens and implement them.
3.Revoke the current token.
4.Add a common user in Creatio.
Application issues a refresh token only once per user
External application may issue a refresh token only once. I.e., the corresponding user is already logged in to the application, has already received a refresh token, and is not eligible for a second refresh token.
Case
Creatio administrator added a token for the same integrated application.
The administrator has deleted the token from Creatio without revoking it (e.g., delete the the token from the database without populating the [Revoke URL] field).
When the administrator adds a new token in Creatio, the integrated application will not issue a second refresh token, as it has already issued the first token that has not been revoked yet.
Alternatively, the administrator may log in to the same integrated application from a different system, and then attempts to log in from Creatio.
How to fix
Study the documentation of the integrated service. Make sure that it actually does issue refresh tokens. Find out how to revoke access to the web service. Usually, integrated services have some form of UI to manage third-party access. Delete the token of the application that the user adds to Creatio (e.g., remove integration with Creatio).
After this, the integrated application will issue a refresh token upon adding an access token to Creatio.
The refresh token has been invalidated in the integrated application, while Creatio still stores the invalidated token
This may occur if administrator logs in to Creatio and the integrated application, and then deletes access on the token management page of the integrated service. As a result, Creatio will store outdated access token and refresh token.
When does the error appear
The authentication error appears when the web service is called.
How to fix
1.In Creatio, delete the user from the OAuth application setup page.
2.Add the user once again.
See also
