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
Get a valid access token for a given provider 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..."
}

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/{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.

OAuth2 tokens are represented by the following properties:

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