OAuth2 Resource Endpoint

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.