Authorization Code Flow: General Information

When you implement OAuth 2.0 or OpenID Connect (OIDC) in a client application to make the application work with MYOB Acumatica, you can use the Authorization Code flow. With this authorization flow, the client application never gets the credentials of the applicable MYOB Acumatica user. After the user is authenticated in MYOB Acumatica, the client application receives an authorization code, exchanges it for an access token, and then uses the access token to work with data in MYOB Acumatica.

Learning Objectives

In this chapter, you will learn how to implement a client application that uses the Authorization Code flow.

Applicable Scenarios

You implement the Authorization Code flow in a client application when you want to securely obtain an access token without exposing the user's credentials to the client application.

Authorization Code Flow

For the support of the Authorization Code flow, you implement the following general steps in the application:

1. Obtaining an authorization code

   The client application connects to the authorization endpoint of MYOB Acumatica.

   The authorization endpoint directs the user of the client application to the sign-in page of MYOB Acumatica, where the user should enter the credentials to sign in to a tenant configured in the MYOB Acumatica instance.

   Note: The user must sign in to the tenant that was specified in the client_id URL parameter passed to the authorization endpoint. (This tenant is selected by default on the sign-in page.)

   If the credentials are accepted by MYOB Acumatica, the system displays the consent form, where the user can confirm that the application has access to the requested scopes. Only the scopes that were requested by the application are displayed on the consent form.

   Once the user grants access to the requested scopes, MYOB Acumatica redirects the client application to the address that was specified in the request, and adds the authorization code in the URL parameter.

   For details on the request for the authorization code, see Authorization Code Flow: Obtaining of an Authorization Code.

2. Obtaining an access token and ID token

   If the client application uses JSON Web Token (JWT) bearer tokens, the application generates a JWT and signs it with the private key.

   The client application connects to the token endpoint of MYOB Acumatica, submits the authorization code, and provides a signed JWT or a shared secret. If a JWT is provided, MYOB Acumatica verifies the JWT signature by using the public key (which was specified during the registration of the client application in MYOB Acumatica) and validates the JWT payload. If a shared secret is provided, MYOB Acumatica verifies the provided application credentials.

   If verification is completed successfully, MYOB Acumatica issues the access token, the ID token, and the refresh token if these tokens have been requested by the application. The client application should provide the access token with each data request to MYOB Acumatica.

   If the ID token is retrieved, the client application validates it by using the key that is available on the OpenID Connection Preferences (SM303030) form. The client application can obtain the key through a GET request to the following URL: [<MYOB Acumatica instance URL>]/identity/.well-known/openid-configuration/jwks. The ID token contains the claims to which the user has granted access.

   For more information on this process, see Authorization Code Flow: Obtaining of an Access Token and ID Token.

3. Optional: Retrieving the user information

   The client application requests user information from MYOB Acumatica and provides the access token with this request. MYOB Acumatica returns the information for which the user has provided the consent. For details about this request, see OAuth 2.0 and OIDC: Obtaining of the User Data.

   Attention: The recommended way of obtaining the user data is to parse the validated ID token, which contains the same claims as the ones that are obtained through this request.
4. Optional: Working with data in MYOB Acumatica

   The client application requests data from MYOB Acumatica and provides the access token with this request. MYOB Acumatica returns the requested data. For details on this process, see OAuth 2.0 and OIDC: Working with Data in MYOB Acumatica.

When the access token expires, the client application can request a new access token by providing a refresh token, as described in OAuth 2.0 and OIDC: Refreshing of an Access Token.

For details on the OAuth 2.0 authorization mechanism, see the specification at https://tools.ietf.org/html/rfc6749. For details on the OIDC authorization mechanism, see the specification at https://openid.net/specs/openid-connect-core-1_0.html#Authentication.

Authorization Code Flow Diagram