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.
- 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.
- When you are registering the client application, you have to be logged in to the tenant whose data the client application needs to access.
- On the System tab, click Integration. In the navigation pane, navigate to Configure > Connected Applications.
- In the Client Name box, type the name of the registered application.
- In the OAuth 2.0 Flow box, select Authorization Code.
- On the Secrets tab, do the following for each client secret you want to add:
- On the tab toolbar, click Add Shared Secret. The Add Shared Secret dialog box opens.
- In the Description box, type the description of the shared secret.
- Optional: In the Expires On (UTC) box, enter the date and time on which the secret expires.
- 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.
- Click OK to save the secret and close the dialog box.
- 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
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.
- Extracts the access token from the CallbackURL.
- Obtains a new access token when the old one expires.
- Saves OAuth values along with geolocation in OAuthSettingsLocation to be persisted across connections.