OAuth2

OAuth2

Introduction

OAuth2 is a standard that allows you to set up a delegation of authorization to grant a third-party application limited access to a resource, with the agreement of the owner of the resource.

The implementation is based on the JAX-RS specification (Jersey), the JWT standard and the open-source Nimbus library.

Limitations

• Only the flow Resource Owner Password Credentials is supported.
  • To obtain a valid token for a user, the third-party application must provide the username and password of said user.
• There is no configuration page in Constellio to manage third-party applications.
  • Temporary web services are offered, for the system administrator only, to create/delete a new third-party application and to revoke a refresh token.
• The generated JWT tokens allow third-party applications to access the REST API v2 only.
  • To use the REST API v2, the JWT token must be provided in the Authorization header with the Bearer prefix.

Configurations

It is important that the configuration "Link of the Constellio server" is correctly filled in and corresponds exactly to the url of the server since it is this value that is used to validate the issuer.  

User Guide

To add a new third-party application:

• POST /oauth/v2/credentials?applicationName=applicationname
  • The applicationName query parameter is required
  • The user must send the Bearer type Authorization header with a legacy token from the administrator (ex: Bearer superToken)
  • A json response is returned with the client id and the secret client.
  • This service will add the third-party application to the list of supported applications. It will generate a client id, a secret client, and a private and public RSA key pair.

To remove a third-party app:

• DELETE /oauth/v2/credentials?applicationName=applicationname
  • The applicationName query parameter is required
  • The user must send the Bearer type Authorization header with a legacy token from the administrator (ex: Bearer superToken)
  • An empty answer is returned.
  • This service will remove the third-party application from the list of supported applications. All associated refresh tokens are also deleted.

To get a JWT token:

• POST /oauth/v2/token
  • The body must be in the format x-www-form-urlencoded and the following variables must be provided: grant_type, client_id, client_secret, username, password
  • The grant_type variable must be set to password
  • A json response is returned with the access token, token type, token expiration, and refresh token
  • Normally, the token has a lifespan of 600 seconds and after this period, one must obtain another one using the refresh token.

To refresh a JWT token:

• POST /oauth/v2/token
  • The body must be in the format x-www-form-urlencoded and the following variables must be provided: grant_type, client_id, client_secret, refresh_token
  • The grant_type variable must be set to refresh_token
  • A json response is returned with the access token, token type, token expiration, and refresh token

To revoke a refresh token:

• POST /oauth/v2/revoke?refreshToken=refreshToken
  • The refreshToken query parameter is required
  • The user must send the Bearer type Authorization header with a legacy token from the administrator (ex: Bearer superToken)
  • An empty answer is returned.
  • This service will remove the refresh token from the server and it will no longer be possible to refresh a token with this refresh token