Home > Developer Documentation Center > Nuxeo Server > Authentication and User Management > OAuth 2
Nuxeo Server

OAuth 2

Updated: March 18, 2024

OAuth 2 is a protocol that allows an application to obtain access to the Nuxeo Platform on behalf of a user.

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.

The 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 code for a reusable access token

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 other filters run by the authentication chain.

Client Registration

Nuxeo allows you to register an OAuth 2 client by specifying an arbitrary name, a client ID, possibly a client secret and a list of redirect URIs. There are two ways of registering a client.

Using the REST API

Use the directory REST API endpoint to create a new entry in the oauth2Clients directory, for instance with curl:

curl -u Administrator:Administrator \
  -H 'Content-Type: application/json' \
  -X POST http://NUXEO_SERVER/nuxeo/api/v1/directory/oauth2Clients \
  -d @- << EOF
  {
    "entity-type": "directoryEntry",
    "directoryName": "oauth2Clients",
    "properties": {
      "name": "My App",
      "clientId": "myApp",
      "clientSecret": "secret",
      "redirectURIs": "https://myapp.mydomain.com/nuxeo-auth-done",
      "autoGrant": "true",
      "enabled": "true"
    }
  }
EOF

Through the Admin Center

This requires to have the JSF UI addon installed on your server.

  1. Go to the Nuxeo Platform web interface, then browse to the Admin Center > Cloud Services > Consumers tab.
  2. Provide a name, a client ID, possibly a client secret, at least one redirect URI and save.

The Auto-grant parameter, if checked, allows the OAuth 2 client to bypass the authorization phase, skipping the web page asking the user to allow the application to access the Nuxeo Platform assets. This is the case for the Mobile application.

The OAuth 2 endpoints are now ready to be used.

OAuth 2 Flow

Here is how Nuxeo handles the OAuth 2 flow to authorize your application to access a protected Nuxeo resource on behalf of a user.

Authorization Endpoint

GET https://NUXEO_SERVER/nuxeo/oauth2/authorize?response_type=code&client_id=myApp

Query parameters:

Name Type Required Description
response_type string Yes The value must be code for requesting an authorization code.
client_id string Yes An enabled client identification
redirect_uri string No The absolute URI to return the user to after authorization is complete
state string No An opaque value used by the client to maintain a state between the request and the redirect callback.
scope string No Ignored in our implementation
code_challenge string No A challenge derived from the code verifier, to be verified against later.
code_challenge_method string No The code verifier transformation method: "S256" or "plain".

If Auto-grant is not checked for the OAuth 2 client registered on the server, the user authorization is handled by accessing https://NUXEO_SERVER/nuxeo/oauth2Grant.jsp. That lets you customize the way you want your users to let your application get authorized.

The code_challenge and code_challenge_method parameters must be used with a public client, according to the "Proof Key for Code Exchange by OAuth Public Clients " RFC. For the code_challenge_method, if the client is capable of using "S256", it must use "S256", as "S256" is implemented on the server.

Token Endpoint

Requesting an Access Token

POST https://NUXEO_SERVER/nuxeo/oauth2/token?grant_type=authorization_code&client_id=myApp&code=authorizationCode

Query parameters:

Name Type Required Description
grant_type string Yes The value must be authorization_code for requesting an access token.
client_id string Yes Must be the same as previously sent to the Authorization endpoint.
client_secret string No The client's secret
code string Yes The authorization code received from the Authorization endpoint
redirect_uri string No, only if sent to the Authorization endpoint. Must be the same as previously sent to the Authorization endpoint.
code_verifier string No, only if code_challenge and code_challenge_method were sent to the Authorization endpoint. A high-entropy cryptographic random string using the unreserved characters [A-Z] / [a-z] / [0-9] / "-" / "." / "_" / "~" from Section 2.3 of RFC3986, with a minimum length of 43 characters and a maximum length of 128 characters.

Response:

HTTP/1.1 200 OK
Cache-Control: no-cache
Content-Length: 176
Content-Type: application/json;charset=ISO-8859-1

{
    "access_token": "A4zNYD1F7cp9l2UTL14pMT65qsyilgjZ",
    "expires_in": 3599.0,
    "refresh_token": "uFfVCD82NRlzeACoK6Fw09fvkYp6GmkuLs2UigconizFufNxIQZLd7btXLxzUzlB",
    "token_type": "bearer"
}

Refreshing an Access Token

POST https://NUXEO_SERVER/nuxeo/oauth2/token?grant_type=refresh_token&client_id=myApp&refresh_token=refreshToken

Query parameters:

Name Type Required Description
grant_type string Yes The value must be refresh_token for refreshing an access token.
client_id string Yes Must be the same as previously sent to the Authorization endpoint.
client_secret string No The client's secret
refresh_token string Yes A refresh token bound to the same client

Response:

HTTP/1.1 200 OK
Cache-Control: no-cache
Content-Length: 176
Content-Type: application/json;charset=ISO-8859-1

{
    "access_token": "jkCQ5cgDavJdXlIqWIWwivuhUA2heqBa",
    "expires_in": 3599.0,
    "refresh_token": "R9KzeZSnyo6ErTvYbPifehgsyIhDtdIhBp3XgJQKWcDo2ikZ8Vl2NlMV87d0KEIB",
    "token_type": "bearer"
}

Authenticating Using an Access Token

Once you obtain an access token it can be used to access the protected Nuxeo resources with a request header or a query parameter. Like below using curl:

curl -H "Authorization: Bearer ACCESS_TOKEN" https://NUXEO_SERVER/nuxeo/api/v1/path/default-domain

curl https://NUXEO_SERVER/nuxeo/api/v1/path/default-domain?access_token=ACCESS_TOKEN
Related Documentation