OAuth 2.0, which stands for Open Authorization 2.0, is an industry-standard protocol for authorization. It allows users to grant limited access to their protected resources without sharing their credentials, such as passwords.

The main purpose of OAuth 2.0 is to enable users to give permission to access their resources hosted on one website to a different website or application, without requiring them to disclose their login credentials. It provides a secure and standardized way for clients to access resources on behalf of the user.

Current ERP Systems using OAuth2.0 Integration

The following systems are already integrated for OAuth2.0 and are easy to setup:

ERP Live customer account
Evox Order processing

Install from the App Store

OAuth Endpoint: Endpoint to retrieve tokens.

OAuth Token life: Token life time (Should be less or equal to the real time)

OAuth Grant Type: Grant type's available (Client Credentials, User&Password, Refresh Token, Client Assertion:jwt-bearer). Depending on the selected the form/payload can change.

OAuth Client ID & OAuth Client Secret: Credentials used to retrieve tokens.

OAuth Resource Body Key: For the resource atribute used on the payload we allow different keys to be used (Depending on the preference).

OAuth resource: The value of the resource server.

OAuth scope: The permissions or actions allowed (Optional field).

Refresh token: Used to refresh the access token and optionaly the refresh token (When the refresh token life time is limited).

JSONata Token Response: JSONata expression, alowing to retrieve the access token with custom body response.

JSONata Refresh Token Response: JSONata expression, alowing to retrieve the refresh token with custom body response.

Install Using Grant Type Client Assertion

By selecting the Client Assertion type, the form changes. The screenshot below shows an example of a possible integration along with an explanation of the new fields.

JWT Algorithm: JWT Algorithms available (PS256). This will be used to encode the JWT token.
JWT Header: JSON JWT Header that will be used to create the JWT token.
JWT Payload: JSON JWT Payload: this field includes all the claims for the JWT. The claims iat (issued at time), exp (expiration time), and scope will be automatically filled.

Examples Request/Response for OAuth2.0:

Depending on the Grant Type the request and response can change.

Client Credentials
User & Password
Refresh Token
Client Assertion:jwt-bearer

Client Credentials

Request Header

Notes:

The Method for the endpoint should be POST.

Example Request Header:

Content-Type: application/json
Accept: application/json

Request Body

Notes:

client_id & client_secret are the credentials
resource (can use the audience key instead)
Scope is optional

Example Request Body

{
"grant_type": "client_credentials",
"client_id": "4157-db19-7d1e22be0b25",
"client_secret": "ka0dw1b.o32js1d",
"resource": "https://www.resource.com",
"scope": "customer order add.order change.order",
}

Response Body

Notes:

access_token is the only required field

Example Response Body

{
"access_token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiIsIng1dCI6Ii1LSTN..."
}

User & Password

Request Header

Notes:

The Method for the endpoint should be POST.

Example Request Header:

Content-Type: application/json
Accept: application/json

Request Body

Notes:

username & password are the credentials

Example Request Body

{
"username": "username",
"password": "*******",
}

Response Body

Notes:

access_token is the only required field

Example Response Body

{
"access_token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiIsIng1dCI6Ii1LSTN..."
}

Refresh Token

Request Header

Notes:

The Method for the endpoint should be POST.

Example Request Header:

Content-Type: application/json
Accept: application/json

Request Body

Notes:

client_id & client_secret are the credentials
refresh_token used to retrieve a new pair of keys.

Example Request Body

{
"grant_type": "refresh_token",
"client_id": "4157-db19-7d1e22be0b25",
"client_secret": "ka0dw1b.o32js1d",
"refresh_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJ...",
}

Response Body

Notes:

access_token is the token used for autorization
refresh_token is used to generate a new access token.

Example Response Body

{
"access_token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiIsIng1dCI6I1LSTN...",
"refresh_token": "eyJ0eXAiIUzI1NiIsInR5cOiVCJ9dCI6Ii1LSN..."
}

Client Assertion (jwt-bearer)

JWT Token

Note:

Claims is the JWT Payload + decrived field.
Client Secret is the privateKey.
Algorithm is the selected.
Header is the JWT Header.

Code sample

const jwt = require('jsonwebtoken');

jwt.sign(claims, privateKey, { algorithm: alg, header: header })

Request Header

Notes:

The Method for the endpoint should be POST.

Example Request Header:

Content-Type: x-www-form-urlencoded
Accept: application/json

Request Body

Notes:

grant_type & client_assertion_type are both static values.
client_id is set in the credentials form.
client_assertion is created using the previously explained JWT.

Example Request Body

{
"grant_type": "client_credentials",
"client_assertion_type": "urn:ietf:params:oauth:client-assertion-type:jwt-bearer",
"client_assertion": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJ...",
"client_id": "4157-db19-7d1e22be0b25"
}

Response Body

Notes:

access_token is the token used for autorization.

Example Response Body

{
    "access_token": "eyJraWQiOiJjLjY5NDgwODhfU0IxLjIwMjQtMDQtMDNfMD...",
}

FAQ

How can I remove the Client ID from the request body?

If you’re using the Client Assertion (JWT bearer), you can remove the Client ID by saving the App Store field with a space (empty character).