Hybrid Flow

Client applications that can securely store client secrets may benefit from the use of the hybrid flow (defined in section 3.3 of the OIDC spec). The hybrid flow allows an application to have immediate access to an ID token while providing secure retrieval of access and refresh tokens. This can be useful in situations where 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.

When you implement OIDC authorization in a client application to make the application work with MYOB Advanced, 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 flow, with the hybrid flow, the client application requests the authorization code (and possibly other parameters) at the authorization endpoint. As with the implicit flow, with the hybrid flow, the client application requests the ID token or access token (or both) at the token endpoint. If the ID token is retrieved, the client application validates it by using the key that is generated on the OpenID Connection Preferences (SM303030) form.

Granting Permission to a Client Application

Before an OIDC client application can work with MYOB Advanced, you must register this application in MYOB Advanced and provide credentials to the application, as described in To Register a Client Application with the Hybrid Flow. After the registration, you have the client ID and the secret value of the client application.

Important:

According to the OAuth 2.0 specification, a secure connection between an OAuth 2.0 client application and the MYOB Advanced website with a Secure Socket Layer (SSL) certificate is required. Therefore, you have to set up the MYOB Advanced website for HTTPS before the OAuth 2.0 client application can work with data in MYOB Advanced. For more information, see Setting Up an HTTPS Service in Web Server (IIS).
When you are registering the client application, you have to be logged in to the tenant whose data the client application needs to access.

Connecting to the Authorization Endpoint

The client application connects to the authorization endpoint of MYOB Advanced with the GET method by specifying the following URL with parameters:

URL
The client application can use one of the following options:
- If the client application supports OpenID Connect Discovery, the client application can use the discovery endpoint address, which is https://<MYOB Advanced instance URL>/identity/. In this address, <MYOB Advanced instance URL> is the URL of the MYOB Advanced instance to which the client application is going to connect.
  For example, for a local MYOB Advanced instance with the name AcumaticaDB, the discovery endpoint address is https://localhost/AcumaticaDB/identity/.
  Note: We recommend that the client application use the discovery endpoint address, which eliminates the need to change the application if the authorization or token endpoint address changes.
- The client application can directly use the authorization endpoint address, which is https://<MYOB Advanced instance URL>/identity/connect/authorize. In this address, <MYOB Advanced instance URL> is the URL of the MYOB Advanced instance to which the client application is going to connect.
  For example, for a local MYOB Advanced instance with the name AcumaticaDB, the authorization endpoint address is https://localhost/AcumaticaDB/identity/connect/authorize.

URL Parameters

The client application should specify the following URL parameters.


Parameter	Description
response_type	The type of the response, which can be one of the following: `code id_token` `code token` `code id_token token`
client_id	The client ID that was assigned to the client application during the registration of the application in MYOB Advanced. The client ID must have the format in which the ID was generated during the registration of the application. That is, the client ID must include an auto-generated string and the ID of the company, such as `88358B02-A48D-A50E-F710-39C1636C30F6@MyCompany`. The client application will have access to the data of the company specified in the client ID.
redirect_uri	The URI in the client application to which the response to the request should be sent. The URI must exactly match one of the values specified for the application in the Redirect URI column on the Redirect URIs tab of the Connected Applications (SM303010) form.
response_mode	The type of the response, which can be either `form_post` or `fragment`.
scope	The access scope that is requested by the client application. The scope can be a combination of the following values, delimited by spaces: openid: If this scope is mandatory for the hybrid flow. email: Requests disclosure of user email address. profile: Requests disclosure of user profile information. address: Requests disclosure of user address. phone: Requests disclosure of user phone number. offline_access: Requests that a refresh token be granted. If a user grants this scope to the application, MYOB Advanced issues to the client application a refresh token along with the access token. (For information on issuing the access token, see Connecting to the Token Endpoint in this topic.) When the access token has expired, the client application can request a new access token by sending a request to the token endpoint and providing the refresh token. The whole chain for the refresh token expires 30 days after the initial authentication process.

An example of a URL with parameters is shown below. (Line breaks are for display purposes only.)

https://localhost/AcumaticaDB/identity/connect/authorize?
response_type=code@20id_token
&client_id=4B1DFD71-C5EE-0B21-A6BE-9A1F060A93BD
&redirect_uri=http%3A%2F%2Flocalhost%2Fclientapp%2F
&scope=openid@20profile%20offline_access

Authorizing a User in MYOB Advanced and Granting Access

The authorization endpoint directs the user of the client application to the login page of MYOB Advanced, where the user should enter the credentials to log in to a company configured in the MYOB Advanced instance.

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

If the credentials are accepted by MYOB Advanced, 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.

Authentication Response

If the user is successfully logged in to MYOB Advanced and has given his consent to access, a response is sent to the redirect URI specified in the authorization request.

If the response_mode parameter was set to form_post in the authorization request, the response has application/x-www-form-urlencoded format, and the method of the form attribute is POST. If the response_mode parameter was set to fragment in the authorization request, all response parameters are added to the fragment component of the redirect URI. The response includes the ID token (if the response_type parameter contained id_token), the refresh token, and the access token.

The access token and refresh token are saved to the MYOB Advanced database and can be used in the same way as by OAuth 2.0 client applications.

Connecting to the Token Endpoint

The client application connects to the token endpoint of MYOB Advanced with the POST method by specifying the following URL and the following parameters in the request body:

URL
The client application can use one of the following options:
- If the client application supports OpenID Connect Discovery, the client application can use the discovery endpoint address, which is https://<MYOB Advanced instance URL>/identity/. In this address, <MYOB Advanced instance URL> is the URL of the MYOB Advanced instance to which the client application is going to connect.
  For example, for a local MYOB Advanced instance with the name AcumaticaDB, the discovery endpoint address is https://localhost/AcumaticaDB/identity/.
  Note: We recommend that the client application use the discovery endpoint address, which eliminates the need to change the application if the authorization or token endpoint address changes.
- The client application can directly use the token endpoint address, which is https://<MYOB Advanced instance URL>/identity/connect/token. In this endpoint, <MYOB Advanced instance URL> is the URL of the MYOB Advanced instance to which the client application is going to connect.
  For example, for a local MYOB Advanced instance with the name AcumaticaDB, the token endpoint address is https://localhost/AcumaticaDB/identity/connect/token.

Parameters in the Request Body

You specify the following parameters in the request body.


Parameter	Description
grant_type	The type of the OAuth 2.0 flow, which must be set to `authorization_code` for the authorization code flow.
client_id	The client ID that was assigned to the client application during the registration of the application in MYOB Advanced. The client ID must have the format in which the ID was generated during the registration of the application. That is, the client ID must include an auto-generated string and the ID of the company, such as `88358B02-A48D-A50E-F710-39C1636C30F6@MyCompany`. The client application will have access to the data of the company specified in the client ID.
code	The authorization code that the client application has received from the authorization endpoint.
client_secret	The value of the secret that was created for the client application during the registration of the application in MYOB Advanced.
redirect_uri	The URI in the client application to which the response to the request should be sent. The URI must exactly match one of the values specified for the application in the Redirect URI column on the Redirect URIs tab of the Connected Applications (SM303010) form.

Receiving the Access Token

MYOB Advanced verifies the provided application credentials and issues the access token, which the client application should provide with each data request to MYOB Advanced. During authentication in MYOB Advanced, if the user has granted to the client application the offline_access scope, MYOB Advanced issues the refresh token along with the access token. A successful response includes the following parameters in the response body.


Parameter	Description
token_type	The type of the access token, which is Bearer.
access_token	The access token.
expires_in	The period of time during which the access token is valid.
refresh_token	The refresh token. The parameter is returned only if the offline_access scope was granted.

Requesting Data with the Access Token

The client application should include the access token in the Authorization header of each subsequent request to MYOB Advanced, as shown in the following HTTP example.

GET /AcumaticaDB/entity/Default/18.200.001/SalesOrder/SO/000001 HTTP/1.1
Host: localhost
Authorization: Bearer cde78a99a2dc6388eb8c7242a90cf9bc

Refreshing the Access Token

The access token is valid for a specific period of time, which is specified in the response that returns the access token. When the access token expires, the client application can request a new access token by providing the refresh token to the token endpoint. To request a new access token, the client application should use the POST method and have the following URL and the following parameters specified in the request body:

URL
The client application can use one of the following options:
- If the client application supports OpenID Connect Discovery, the client application can use the discovery endpoint address, which is https://<MYOB Advanced instance URL>/identity/. In this address, <MYOB Advanced instance URL> is the URL of the MYOB Advanced instance to which the client application is going to connect.
  For example, for a local MYOB Advanced instance with the name AcumaticaDB, the discovery endpoint address is https://localhost/AcumaticaDB/identity/.
  Note: We recommend that the client application use the discovery endpoint address, which eliminates the need to change the application if the authorization or token endpoint address changes.
- The client application can directly use the token endpoint address, which is https://<MYOB Advanced instance URL>/identity/connect/token. In this endpoint, <MYOB Advanced instance URL> is the URL of the MYOB Advanced instance to which the client application is going to connect.
  For example, for a local MYOB Advanced instance with the name AcumaticaDB, the token endpoint address is https://localhost/AcumaticaDB/identity/connect/token.

Parameters in the Request Body

You specify the following parameters in the request body.


Parameter	Description
grant_type	The type of the request, which must be set to `refresh_token` for the request of the refresh token.
client_id	The client ID that was assigned to the client application during the registration of the application in MYOB Advanced. The client ID must have the format in which the ID was generated during the registration of the application. That is, the client ID must include an auto-generated string and the ID of the company, such as `88358B02-A48D-A50E-F710-39C1636C30F6@MyCompany`. The client application will have access to the data of the company specified in the client ID.
client_secret	The value of the secret that was created for the client application during the registration of the application in MYOB Advanced.
refresh_token	The refresh token that the client application received from the token endpoint along with the access token if the user granted the offline_access scope to the client application.

Receiving the New Access Token

MYOB Advanced verifies the provided application credentials and issues the new access token and the new refresh token. To request the access token once again, the client application should use the refresh token issued with the previous access token. A successful response includes the following parameters in the response body.


Parameter	Description
token_type	The type of the access token, which is Bearer.
access_token	The access token.
expires_in	The period of time during which the access token is valid.
refresh_token	The refresh token.

Logging Out from MYOB Advanced

To prevent issues with licenses that limit the number of concurrent user sessions, the client application should directly call the logout method of the MYOB Advanced web services API when the application finishes its work with MYOB Advanced. The client application does this by using the POST method, the ASP.NET_SessionId cookie with the value that corresponds to the session, and the following URL.

https://<Acumatica ERP instance URL>/entity/auth/logout

In this address, <Acumatica ERP instance URL> is the URL of the Acumatica ERP instance to which the client application is going to connect.