Hybrid Flow: General Information

When you implement OpenID Connect (OIDC) in a client application to make the application work with MYOB Acumatica, you can use the Hybrid flow. This authorization flow is a combination of the Authorization Code flow and the Implicit flow. As with the Authorization Code flow, with the Hybrid flow, the client application requests the authorization code at the authorization endpoint. As with the Implicit flow, with the Hybrid flow, the client application requests the ID token, access token, or both at the token endpoint. The Hybrid flow allows an application to have immediate access to an ID token while providing secure retrieval of access and refresh tokens.

Learning Objectives

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

Applicable Scenarios

You implement the Hybrid flow in a client application that can securely store client secrets when the application needs to immediately access information about the user, but must perform some processing before gaining access to protected resources for a long period.

Hybrid Flow

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

1. Obtaining tokens from the authorization endpoint

   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.

   If the user has successfully signed in to MYOB Acumatica and has granted the access, a response is sent to the redirect URI specified in the authorization request. The response can contain an ID token, access token, and authorization code.

   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 details on the requesting of tokens from the authorization endpoint, see Hybrid Flow: Obtaining of an Authorization Code, Access Token, and ID Token from the Authorization Endpoint.

2. Obtaining tokens from the token endpoint

   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 Hybrid Flow: Obtaining of an Access Token and ID Token from the Token Endpoint.

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.

Hybrid Flow Diagram