Server

OAuth2 Resource Endpoint

Updated: March 18, 2024

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

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

  • Create, read, update and delete OAuth2 providers
  • Read OAuth2 clients
  • Get a valid access token for a given provider or client for the current user
  • Read, update and delete OAuth2 tokens

CRUD on OAuth2 Providers

OAuth2 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 OAuth2 service providers.
POST /api/v1/oauth2/provider Creates a new OAuth2 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 OAuth2 service provider. Only available to Administrators.
DELETE /api/v1/oauth2/provider/{providerName} Deletes an OAuth2 service provider. Only available to Administrators.

OAuth2 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 OAuth2 client ID.
clientSecret The OAuth2 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..."
}

Getting OAuth2 Clients

Information about a particular or all OAuth2 clients can be retrieved through these resources:

Path Description
GET /api/v1/oauth2/client Gets the list of registered OAuth2 clients.
GET /api/v1/oauth2/client/{clientId} Gets the details for a given client.

OAuth2 clients have the following properties:

Property Description
entity-type The entity-type of this object, in this case oauth2Client.
id The client ID.
name The client name.
isEnabled true if client is enabled; false otherwise.

Example

Request

GET https://NUXEO_SERVER/nuxeo/api/v1/oauth2/client/nuxeo-mobile

Response

{
  "entity-type": "oauth2Client",
  "id": "nuxeo-mobile",
  "name": "Nuxeo Mobile",
  "isEnabled": true
}

Reading, Updating and Deleting OAuth2 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/provider Retrieves all stored tokens for a given service provider and for the current user.
GET /api/v1/oauth2/token/{providerName}/{nxLogin}
(deprecated since 10.2; use the endpoint below instead)
Retrieves a stored token for a given service provider and user.
GET /api/v1/oauth2/token/provider/{providerName}/user/{nxLogin} Retrieves a stored token for a given service provider and user.
PUT /api/v1/oauth2/token/{providerName}/{nxLogin}
(deprecated since 10.2; use the endpoint below instead)
Updates a stored token for a given service provider and user.
PUT /api/v1/oauth2/token/provider/{providerName}/user/{nxLogin} Updates a stored token for a given service provider and user.
DELETE /api/v1/oauth2/token/{providerName}/{nxLogin}
(deprecated since 10.2; use the endpoint below instead)
Deletes a stored token for a given service provider and user.
DELETE /api/v1/oauth2/token/provider/{providerName}/user/{nxLogin} Deletes a stored token for a given service provider and user.
GET /api/v1/oauth2/token/client Retrieves all stored tokens for a given client and for the current user.
GET /api/v1/oauth2/token/client/{clientId}/user/{nxLogin} Retrieves a stored token for a given client and user.
PUT /api/v1/oauth2/token/client/{clientId}/user/{nxLogin} Updates a stored token for a given client and user.
DELETE /api/v1/oauth2/token/client/{clientId}/user/{nxLogin} Deletes a stored token for a given client and user.

OAuth2 tokens are represented by the following properties:

Property Description
entity-type The entity-type of this object, in this case nuxeoOAuth2Token.
clientId The 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