Nuxeo Server

OAuth2 Resource Endpoint

Updated: November 13, 2017 Page Information Edit on GitHub

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.

Related Documentation
5 days ago manonlumeau Added content-review-lts2017 label
a month ago manonlumeau NXDOC-1346-FT review screenshot
History: Created by manonlumeau