Home > Developer Documentation Center > Authentication and User Management > Using OAuth2
Authentication and User Management

Using OAuth2

Updated: October 16, 2020

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

Nuxeo tries to stay very close to the OAuth2 RFC memorandum to ease client integration. Before going any further, because OAuth2 makes a lot of exchanges with clients using query parameters, you must ensure to have configured a TLS.

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.

Client Registration

Nuxeo allows you to register client, to specify an arbitrary name, a clientId and a clientSecret. To register your own, go to the Admin tab, OAuth and Consumers tab.

Authorization Endpoint

Requesting an Authorization Code

GET https://NUXEO_SERVER/oauth2/authorization

Query parameters:

NameTypeDescription
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/oauth2/token Query parameters:
NameTypeDescription
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/oauth2/token

Query parameters:

NameTypeDescription
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" http://NUXEO_SERVER/nuxeo/nxdoc/default/d3db3184-c444-40a4-b838-dfde41ba06a4/view_documents
Related Documentation