How to use OAuth2 Tokens in Platform?

EN | ES

Onesait Platform is ready to work with OAuth2 authentication. The Oauth2 token management flow is explained below.

1. OAuth2 Realm configuration parameters

When creating or Updating a Realm, there are two parameters to be configured associated to the OAuth Tokens:

• KEY (Clave) (Secret): key that will be used for clients's authentication..
• TOKEN VALIDITY TIME (S) (Tiempo de validez de token (s)): configurable timespan (in seconds) in which the generated token will be valid.

They are optional attributes. If not informed, they will take default values ​​defined in the platform deployment (onesaitplatform and 43200 (12 hours)).

2. Token Generation

There is an endpoint that allows OAuth2 token generation. The URL is like this: https://lab.onesaitplatform.com/oauth-server/oauth/token

It's a POST request, and it must include:

• Headers:
  • Authorization: (client:secret b64)
  • Content-Type: application/x-www-form-urlencoded
• Body:
  • grant_type: password (User/Password request)
  • username: user's Id
  • password: user's password
  • clientId: id of the client requesting the token
  • scope: Token scope 

Using Postman to send this request, will be something like this:

The response will have this format:

Highlights:

• access_token: Access token.
• refresh_token: Refresh Token (single use).
• expires_in: Remaining validity time (seconds).
• authorities: Realms' roles asigned to the user.
  

3. Check Token

Service that verifies the validity of a token. The endpoint will be like this: https://lab.onesaitplatform.com/oauth-server/openplatform-oauth/check_token

The POST request must include:

• Headers:
  • Authorization: (client:secret b64)
• Parameter:
  • token: token to validate

Using Postman:

If the token is valid, a response will be obtained in the form:

Highlights:

• principal/name: user for which the token was generated.
• exp: Expiration date.
• client_id: Client for which the token was generated.
• authorities: Realm's Roles to which the token's user belongs.

4. Refresh Token

Service that regenerates the token to obtain another one. The endpoint is like this: https://lab.onesaitplatform.com/oauth-server/oauth/token

(the same as for getting a new token, changes the grant-type attribute).

The POST request must include:

• Headers:
  • Authorization: (client:secret b64)
  • Content-Type: application/x-www-form-urlencoded
• Body:
  • grant_type: refresh_token (for token refresh)
  • refresh_token: refresh token obtained when the access token was generated.

Using Postman:

The result will have the same structure as when a token generation request is made.

The refresh token is one-use only. After using it, a new one will be provided along with the new access token.

5. Revoke Token

As an additional service, a token revocation service is included. Allows you to disable (revoke) an access token associated with a given user.

The endpoint is like this: https://lab.onesaitplatform.com/oauth-server/openplatform-oauth/revoke_token

The POST request must include:

Headers:

• Authorization: (cliente:secret en b64)
• Content-Type: application/x-www-form-urlencoded

Query Param:

• token: (token to revoke)

In Postman:

The result will indicate that the token is not longer valid:

6. User info endpoints

An endpoint to retrieve user claims. The url is like this: https://lab.onesaitplatform.com/oauth-server/user

The POST request must include:

Headers:

• Authorization: Bearer {jwt}

In Postman: