Nuxeo Server

OAuth 2 Resource Endpoint

Updated: March 18, 2024

The OAuth 2 endpoint allows REST clients to retrieve information about OAuth 2 providers and tokens. It is available since 8.10.

Several resources are exposed by this endpoint, which allows to:

  • Create, read, update and delete OAuth 2 providers
  • Get a valid access token for a given provider for the current user
  • Read, update and delete OAuth 2 tokens

CRUD on OAuth 2 Providers

OAuth 2 service providers can be created, read, updated and deleted using the following resources:

Path Description
GET /api/v1/oauth2/provider Gets the list of registered OAuth 2 service providers.
POST /api/v1/oauth2/provider Creates a new OAuth 2 service provider. Only available to Administrators.
GET /api/v1/oauth2/provider/{providerName} Gets the details for a given provider.
PUT /api/v1/oauth2/provider/{providerName} Updates an OAuth 2 service provider. Only available to Administrators.
DELETE /api/v1/oauth2/provider/{providerName} Deletes an OAuth 2 service provider. Only available to Administrators.

OAuth 2 providers exchanged via REST API are represented by the following properties:

Property Description
entity-type The entity-type of this object, in this case nuxeoOAuth2ServiceProvider.
serviceName The provider ID
description The description of the provider.
clientId The OAuth 2 client ID.
clientSecret The OAuth 2 client secret.
authorizationServerURL The URL of the authorization server.
tokenServerURL The URL of the token server.
scopes The list of user account scopes to which access will be requested.
isEnabled true if provider is enabled; false otherwise. Will be set to false automatically if clientId and clientSecret are undefined.
isAvailable true if provider is enabled and both clientId and clientSecret are defined; false otherwise.
authorizationURL The URL used to display the consent screen.
isAuthorized true if server has access token stored for current user; false otherwise.
userId The user ID.

Example

Request

GET https://NUXEO_SERVER/nuxeo/api/v1/oauth2/provider/googledrive

Response

{
  "entity-type": "nuxeoOAuth2ServiceProvider",
  "serviceName": "googledrive",
  "description": "Google Drive",
  "clientId": "123-....apps.googleusercontent.com",
  "clientSecret": "...",
  "authorizationServerURL": "https://accounts.google.com/o/oauth2/auth?access_type=offline&approval_prompt=force",
  "tokenServerURL": "https://accounts.google.com/o/oauth2/token",
  "userAuthorizationURL": null,
  "scopes": [
    "https://www.googleapis.com/auth/drive",
    "https://www.googleapis.com/auth/drive.apps.readonly",
    "email"
  ],
  "isEnabled": true,
  "isAvailable": true,
  "authorizationURL": "https://accounts.google.com/o/oauth2/auth?client_id=...",
  "isAuthorized": false,
  "userId": null
}

Getting an Access Token

A valid access token for the current user can be retrieved via /nuxeo/api/v1/oauth2/provider/{providerId}/token. If the token currently stored by the Nuxeo server is already expired, a new one will be requested from the service provider.

Example

Request

GET https://NUXEO_SERVER/nuxeo/api/v1/oauth2/provider/googledrive/token

Response

{
  "token": "abc57.Gsda..."
}

Reading, Updating and Deleting OAuth 2 Tokens

The following resources are available for managing tokens:

Path Description
GET /api/v1/oauth2/token Retrieves a list of all stored tokens for all users. Only available to Administrators.
GET /api/v1/oauth2/token/{providerName}/{nxLogin} Retrieves a stored token for a given service provider and user. Only available to Administrators.
PUT /api/v1/oauth2/token/{providerName}/{nxLogin} Updates a stored token for a given service provider and user. Only available to Administrators.
DELETE /api/v1/oauth2/token/{providerName}/{nxLogin} Deletes a stored token for a given service provider and user. Only available to Administrators.

OAuth 2 tokens are represented by the following properties:

Property Description
entity-type The entity-type of this object, in this case nuxeoOAuth2Token.
clientId The OAuth 2 client ID.
serviceName The provider ID.
creationDate The creation date of the token.
nuxeoLogin The Nuxeo user id to whom the token corresponds to.
serviceLogin The id used by the service to identify the user.
isShared true if the token is shared with other users; false otherwise.
sharedWith A list of users and groups the token has been shared with.

Related Documentation