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.
Contents
•Connection settings are invalid or out-of-date, compared to those in the integrated application
•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 bpm’online are denied during login
•Shared user was not configured in the OAuth application
•Other access limitations have been set up in the integrated service
•“Missing refresh token” on login
Connection settings are invalid or out-of-date, compared to 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., bpm'online attempts to obtain access using invalid settings).
How to fix
Verify each setting on the OAuth application setup page in bpm'online, make sure that they match 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 bpm’online 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 bpm’online (Fig. 1).
Fig. 1 Redirect URL on the OAuth application setup page in bpm’online
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 bpm’online, 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 bpm’online 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 bpm’online, the integrated service, or upon user login.
The scopes must be specified in bpm’online, on the [Scopes] detail of the OAuth application setup page. Bpm’online 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 bpm’online, so that the previously issued access token is revoked.
3.Revoke access for bpm’online 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 bpm’online 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 bpm’online 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 bpm’online, so that the previously issued access token is revoked.
3.Revoke access for bpm’online 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 bpm’online are denied during login
The properly specified scopes in bpm’online 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 bpm’online 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 bpm’online.
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 bpm’online, so that the previously issued access token is revoked.
2.Revoke access for bpm’online application in the integrated service (e.g., you can disable access to specific applications from your Google account settings).
3.Add the user to bpm’online 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., bpm’online 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 "Use authentication" checkbox in web service methods.
Shared user was not configured in the OAuth application
When does the error appear
The error appears when calling the web service (i.e., bpm’online attempts to connect without passing of an access token).
How to fix
Add a common user on the OAuth application setup page.
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 bpm’online application IP and/or domain on the integrated service side.
“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 bpm’online 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 bpm’online.
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.
Example
Bpm’online administrator added a token for the same integrated application.
The administrator has deleted the token from bpm’online 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 bpm’online, 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 bpm’online.
How to fix
Study the documentation of the integrated service. Make sure that it actually does issue refresh tokens. Find a way to revoke access: usually, integrated services have some form of UI to manage third-party access. Delete the token of the application that the user adds to bpm’online (e.g., remove integration with bpm’online).
After this, the integrated application will issue a refresh token upon adding an access token to bpm’online.
The refresh token has been invalidated in the integrated application, while bpm’online still stores the invalidated token
This may occur if administrator logs in to bpm’online and the integrated application, and then deletes access on the token management page of the integrated service. As a result, bpm’online 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 bpm’online, delete the user from the OAuth application setup page.
2.Add the user once again.
Next
