JDBC Driver for Acumatica

Build 22.0.8462

Creating a Custom OAuth App

Acumatica uses the OAuth authentication standard, which requires the authenticating user to interact with Acumatica via the browser. The driver facilitates the OAuth exchange in various ways as described below.

Register an OAuth Application

You can follow the procedure below to obtain the OAuth client credentials, the OAuthClientId and OAuthClientSecret.

  1. You use the Connected Applications (SM303010) form to register an OAuth 2.0 or OpenID Connect client application. To register a client application in Acumatica ERP, you need to know the OAuth 2.0 flow that this application implements.
  2. When you are registering the client application, you have to be logged in to the tenant whose data the client application needs to access.
  3. On the System tab, click Integration. In the navigation pane, navigate to Configure > Connected Applications.
  4. In the Client Name box, type the name of the registered application.
  5. In the OAuth 2.0 Flow box, select Authorization Code.
  6. On the Secrets tab, do the following for each client secret you want to add:
    1. On the tab toolbar, click Add Shared Secret. The Add Shared Secret dialog box opens.
    2. In the Description box, type the description of the shared secret.
    3. Optional: In the Expires On (UTC) box, enter the date and time on which the secret expires.
    4. Copy and save the value that is displayed in the Value box. The client application should use this client secret for authentication in Acumatica ERP.
  7. Click OK to save the secret and close the dialog box.
  8. On the Redirect URIs tab, do the following for each redirect URI you want to add: On the tab toolbar, click Add Row. In the Redirect URI column of the new row, type the exact redirect URI to which Acumatica ERP should redirect the client application after the client application has been authorized. The redirect URI must be absolute and must not have the fragment part (the part preceded with #). On the form toolbar, click Save. Notice that the client ID has been generated in the Client ID box. The client application should use this client ID along with the client secret for authentication in Acumatica ERP.

Authenticate to Acumatica from a Desktop Application

In order to obtain a token, the client application needs to call the Oauth2 endpoint using various grants depending on the authentication scenarios required. The default OAuthGrantType is CODE, which requires you to follow the steps below. After setting the following connection properties, you are ready to connect:

  • OAuthClientId: Set this to your clientId.
  • OAuthClientSecret: Set this to your clientSecret.
  • InitiateOAuth: Set this to GETANDREFRESH. You can use InitiateOAuth to avoid repeating the OAuth exchange and manually setting the OAuthAccessToken connection property.
  • CallbackURL: Set this to the redirect URI configured in the oauth application.
When you connect, the driver completes the OAuth process:
  1. Extracts the access token from the CallbackURL.
  2. Obtains a new access token when the old one expires.
  3. Saves OAuth values along with geolocation in OAuthSettingsLocation to be persisted across connections.

Authenticate to Acumatica from a Web Application

In the Web OAuth flow, set the following connection properties and follow the steps below to call stored procedures to obtain the access token.

  • OAuthClientId: Set this to the clientId in your app settings.
  • OAuthClientSecret: Set this to the clientSecret in your app settings.

When connecting via a Web application, or if the driver is not authorized to open a browser window, you need to exchange a verifier code for the OAuthAccessToken.

  1. Call GetOAuthAuthorizationURL. The stored procedure returns the URL to the OAuth endpoint.
  2. Go to that URL and log in to authorize the application. Afterwards, you are redirected back to the callback URL.

    When you are redirected, the callback URL contains the code query string parameter.

  3. Set the following parameters and call GetOAuthAccessToken:

    NameValue
    AuthModeWEB
    VerifierSet this to the verifier code.

To make requests to Acumatica, set OAuthAccessToken to the values returned in step 3.

To automatically refresh the token when it expires, set InitiateOAuth to REFRESH.

Copyright (c) 2023 CData Software, Inc. - All rights reserved.
Build 22.0.8462