Oauth2.0 Principes (web server app)

Introduction

Sage Active Public API V2 is secured by Oauth 2.0.

OAuth 2.0., short for “Open Authorization”, is an open standard protocol that allows authorization for secure API access.
It is often used to allow users to grant third-party access to their resources without sharing their passwords.
OAuth 2.0 allows a user to authorize an application to access their resources without sharing their login credentials.
Instead, the user grants access by authenticating with their login credentials and authorizing the application to access their resources.
OAuth 2.0 provides a secure way for applications to access resources on behalf of a user without exposing the user’s login credentials.

To avoid the risk of third parties intercepting and misusing these data, authorization for data transfers between Sage Active Public API V2 and the Sage Active application is therefore necessary.

Note on Implementation Libraries:

The purpose of this documentation is to provide a detailed understanding of the OAuth 2.0 authentication process for the Sage Active Public API V2, step by step.
It is essential for developers to grasp these fundamentals to ensure a secure and effective integration.

However, to streamline the integration process and reduce the complexity of directly handling HTTP requests, responses, and security procedures, developers are encouraged to utilize well-established OAuth client libraries.
These libraries are designed for various programming languages and frameworks, offering a more developer-friendly way to implement OAuth integration.

Using such libraries can significantly simplify the process, handling the intricate details behind the scenes.
They manage the creation of URLs, secure handling of state parameters, and the exchange of the authorization code for access tokens.
This approach not only reduces the amount of code developers need to write but also enhances the security and reliability of the application by adhering to established best practices.

See, for example, an authentication sample using OpenID Connect.

Access Token

For every request to Sage Active Public API V2, you must provide a valid Access Token in the authorization header.

Authorization: Bearer {Access Token}
Scopes

Your application will also need to authorize the necessary rights for it to function (scopes).

Warning! Only grant the necessary permissions.
For example, if your application does not plan to write data to Sage Active, it is not necessary to give the Write Sage Active Data permission.

Obtaining and Refreshing Access Tokens

The steps below detail the process for acquiring an access token for a server web application, as well as utilizing a refresh token to secure a new token upon the expiration of the existing one.

1. Authorization request

You must contact the authorization server of Sage Active by calling the authentication url with the GET method and the required parameters:

Auth URL prod
Query parameters Value
response_type This parameter must always contain code
state A value of your choice to prevent cross-site request forgery
client_id The Client ID that was generated when creating your app.
scope The required permissions for your application separated by a space %20:

  • RDSA - Reading accounting data
  • WDSA - Writing accounting data
  • offline_access - Access to refresh token, see below in this page : Renew a Refresh Token
redirect_uri The redirect url (Callback URL) you mentioned in your app.

Sample of the url to call

var url = `${sbcAuthUrl}/connect/authorize?client_id=${clientId}&response_type=code&scope=${scopes}&redirect_uri=${redirectUri}&state=1234;

img

If the call is successful, an HTTP response code 302 Found is returned and, in the provided authorization redirect URL, the following query parameters are returned:

Sample of the redirection to your redirect url with the query parameters

`http://your-redirect-uri.com/callback?code=AQzASDZZqxxxx...&scope=RDSA WDSA offline_access&iss=https://{sbcAuthUrl}&state=1234`
Possible errors

2. Resend authorization code to get access token

If the previous call is successful, you then need to make a POST call to get the Token:

Access Token URL prod
body parameters Value
grant_type This parameter must contain authorization_code
code The code returned by the GET call described earlier.
redirect_uri The redirect url (Callback URL) you mentioned in your app
client_id The Client ID that was generated when creating your app
client_secret The Client Secret that was generated when creating your app

If permission is granted, the response will return:

Sample of response

{
  access_token: "eyJhbGciOiJSUzI1NiIsImtpZCI6IjEyNTA2QjNGOTFFRxxxxxxxxxxxxx"
  expires_in: 28800
  refresh_token: "DF6FD016916A1263xxxxxxxxx"
  scope: "RDSA WDSA offline_access"
  token_type: "Bearer"
}
Remarks
Possible errors


3. Renew a Refresh Token

You can use renewing an access token to get a new access token if the current token has expired.
This means that your users are not required to authorize your application each time you request a new token.

Access Token URL prod
Settings Value
grant_type Must contain refresh_token
refresh_token Must contain the value of refresh_token returned by the Get Access Token response.
client_id The Client ID that was generated when creating your app
client_secret The Client Secret that was generated when your app was created

If permission is granted, the response will return, among other things:

Offline Access

This authentication service requires the offline_access scope to grant the use of refresh tokens.
This scope allows your application to obtain new access tokens without the need for user intervention when the current token expires.
To request offline access, include the offline_access scope when making your authorization request:

Settings Value
scope The required permissions for your application separated by a space %20:

  • RDSA - Reading accounting data
  • WDSA - Writing accounting data
  • offline_access - Access to refresh token

By adding offline_access to the list of requested scopes, the authorization server will issue a refresh token along with the access token, allowing your application to refresh the access token automatically when needed.

Do not forget that to renew the access token, you must exploit the refresh_token by sending a request with the grant_type refresh_token.
More info :


Revoke a Refresh Token

You can revoke a refresh token so that it is no longer valid for obtaining new access tokens.

Please note that you cannot revoke access tokens, they are valid for their lifetime.

Once a refresh token is revoked, it can no longer be used to obtain a new access token, so when the current access token expires, the user will need to log in again to access the application.

Revoke Token URL prod
Settings Value
token The value of the refresh_token you wish to revoke
client_id The Client ID that was generated when creating your app
client_secret The Client Secret that was generated when your app was created

If the operation was successful you will get a response with HTTP status 200.

Session Termination (Logout)

The process described here allows you to effectively log out a user by invalidating the refresh token, ensuring it can no longer be used to generate new access tokens.

When the refresh token is invalidated, any existing access tokens will remain valid until their set expiration but cannot be renewed. Consequently, the user will be prompted to re-authenticate once the access token expires.

Hereʼs how to perform the logout process:

Logout URL production

To complete the logout, follow these query parameters:

Settings Value
client_id The Client ID obtained during your application registration.
returnTo The logout URL listed in your application’s Logout URIs field within the associated solution.

img

Additionally, ensure to clear any stored access and refresh tokens from the client’s local storage to maintain security and prevent unauthorized use of stale tokens.

<  Authentication2. Oauth 2.0 Principles (mobile or desktop app)  >