Implicit Flow

When you implement OAuth 2.0 or OIDC authorization in a client application to make the application work with MYOB Advanced, you can use the implicit flow, which is a simplified variant of the authorization code flow.

With the implicit flow, the client application never gets the credentials of the applicable MYOB Advanced user. When the user is authenticated in MYOB Advanced, the client application does not receive an authorization code (as with the authorization code flow); instead, the client application directly receives an access token, and then uses the access token to work with data in MYOB Advanced. The access token is valid for a limited period of time and cannot be renewed.

The following diagram illustrates the implicit flow, whose steps are described in the sections later in this topic.
Figure 1. Implicit flow


This flow can be used for clients using a scripting language (such as JavaScript) or for mobile clients. 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.

Granting Permission to a Client Application

Before an OAuth 2.0 or 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 Implicit Flow. After the registration, you have the client ID 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 and 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 flow. For OAuth 2.0, it must be set to token. For OIDC, it must be set either to id_token or 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.
    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 granted, the OpenID Connect protocol is used. Without this scope, the OAuth 2.0 protocol is used.

    • api: Requests access to a web services API or OData interface. If a user grants this scope to the application, the client application can work with the following types of the web services API: contract-based SOAP API, screen-based SOAP API, or contract-based REST API.

      Important: For the contract-based API request, you must specify api for the scope parameter.

      If this scope is granted and the api:concurrent_access scope is not granted, MYOB Advanced manages the sessions of the application through tokens. The system uses a single session for each access granted to the client application.

    • api:concurrent_access: Requests permission for the concurrent use of multiple types of web service APIs. If a user grants this scope to the application, the client application can access data in MYOB Advanced in concurrent mode. In this case, MYOB Advanced can maintain multiple sessions for the client application, managing session IDs through cookies. We recommend that the client application request this scope only if concurrent access is required for the client application. For details about the license limitations related to the number of sessions for client applications, see License Restrictions for API Users.
    Note: The offline_access scope is not supported by the implicit flow.
An example of the HTTP request is shown below. (Line breaks are for display purposes only.)
http://localhost/AcumaticaDB/identity/connect/authorize?
response_type=token
&client_id=4B1DFD71-C5EE-0B21-A6BE-9A1F060A93BD
&redirect_uri=http%3A%2F%2Flocalhost%2Fclientapp%2F
&scope=api

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.

Obtaining the Access Token

Once the user grants access to the requested scopes, MYOB Advanced redirects the client application to the redirect_uri address, which was specified in the request, and adds the access token in the URL parameters. The redirect URL includes the following URL parameters.
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.
Note: Refresh tokens are not supported by the implicit flow.

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

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.