Home > Developer Documentation Center > Nuxeo Server > Authentication and User Management > OAuth2
Nuxeo Server

OAuth2

Updated: March 18, 2024

OAuth2 is a protocol that allows application request authorization to the Nuxeo Platform without getting user's password.

Nuxeo tries to stay very close to the "OAuth 2.0 Authorization Framework" RFC to ease client integration and be secure. Before going any further, because OAuth 2 has to make a lot of secure exchanges with clients using query parameters, you must ensure to have configured Nuxeo in HTTPS.

RFC describes two endpoints:

  • An Authorization endpoint used by the client to obtain authorization from the resource owner via user-agent redirection,
  • A Token endpoint used by the client to exchange an authorization grant for an access token, typically with client authentication.

Installation

OAuth 2 is natively supported by the Nuxeo Platform, which means there is no bundle to install and no XML extensions required to enable it. An HTTP filter handles authentication in priority compared to the filter that handles the contributed authentication chain illustrated at the beginning of this section.

Client Registration

Nuxeo allows you to register client, to specify an arbitrary name, a clientId and a clientSecret. To register your own:

  1. Go to the Nuxeo Platform web application, then browse Admin Center > Cloud Services > Consumers tab.
  2. Provide a name, a ClientId, and a ClientSecret and save. OAuth endpoints are ready to be used.

Authorization Endpoint

GET https://NUXEO_SERVER/nuxeo/oauth2/authorization

Query parameters:

Name Type Description
response_type string REQUIRED. The value must be code for requesting an authorization code.
state string An opaque value used by the client to maintain state between the request and callback.
scope Ignored in our implementation.
redirect_uri string REQUIRED. An absolute URI where the redirection is done after completing the interaction.
client_id string REQUIRED. An enabled client identification.

User authentication is handled by accessing to https://NUXEO_SERVER/nuxeo/oauth2Grant.jsp which is behind the default NuxeoAuthenticationFilter. That lets you customize the way you want your users to identify themselves.

Token Endpoint

Requesting an Access Token

GET https://NUXEO_SERVER/nuxeo/oauth2/token

Query parameters:

Name Type Description
grant_type string REQUIRED. The value must be authorization_code for requesting an access token.
code string REQUIRED. The authorization code received from the Authorization endpoint.
redirect_uri string REQUIRED. Must be the same as previously sent to the Authorization endpoint.
client_id string REQUIRED. Must be the same as previously sent to the Authorization endpoint.
client_secret string REQUIRED. Client's secret.

Response:

HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
Cache-Control: no-store
Pragma: no-cache
{
  "access_token":"H8dXDdEW9U2jJnFDh6lJJ74AHRzCyG4D",
  "token_type":"bearer",
  "expires_in":3600,
  "refresh_token":"Amz8JlyglhGWDmYHMYS5EnTTFUFAwZLiHG4aqQDfkwUNunSMpTTSFUmvprX3WdSF",
}

Refreshing an Access Token

 GET https://NUXEO_SERVER/nuxeo/oauth2/token

Query parameters:

Name Type Description
grant_type string REQUIRED. The value must be refresh_token for requesting an access token.
refresh_token string REQUIRED. A Refresh Token bound to the same Client.
client_id string REQUIRED. Must be the same as previously sent to the Authorization endpoint.
client_secret string REQUIRED. Client's secret.

Response:

HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
Cache-Control: no-store
Pragma: no-cache
{
  "access_token":"H8dXDdEW9U2jJnFDh6lJJ74AHRzCyG4D",
  "token_type":"bearer",
  "expires_in":3600,
  "refresh_token":"Amz8JlyglhGWDmYHMYS5EnTTFUFAwZLiHG4aqQDfkwUNunSMpTTSFUmvprX3WdSF",
}

Authentication Using an Access Token

Once you have a valid access token, you have to pass it in each requests as an Authorization header. Like below using curl:

curl -H "Authorization: Bearer gsQwO6X4zdOOegaR1EZEpRNJ2LK6J8d6" https://NUXEO_SERVER/nuxeo/api/v1/path/default-domain/workspaces
Related Documentation