How to use OAuth2 Tokens in Platform?

Owned by DevPortal Editor (Unlicensed)
Last updated: 12/09/22 by Onesait 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: