OAuth 2 Resource Endpoint

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.