Skip to content

User Management API

Jump to bottom Edit New page
Soumya Brahma edited this page Feb 6, 2016 · 4 revisions

Table of Contents

API function overview

The user model in Wf4Ever should be as minimal as possible, so that it serves its basic purposes, can easily be mapped or reused in other contexts, and can be extended if necessary. The only absolute, project-wide requirement is that the users are identified by URIs. Whether the URIs can be dereferenced and what is returned when dereferenced depends on each application.

For user management in RODL, the following additional assumptions are made:

  • User URIs are opaque, using UUIDs as user identifiers.
  • RODL stores minimal information about users: their URI, a human friendly name (optional) and alternative URIs (optional). Alternative URIs may help in reusing user services in other systems (i.e. myExperiment) and may prevent users from creating duplicate accounts (i.e. two accounts with the same OpenID URI).
  • There is no constraint about the user authentication method. It can be an OpenID, username/password or another mechanism. In particular, it may be possible to use more than one mechanism for one user account.
Access control policy model is out of scope of this document. However, for purpose of the REST API, three levels of permissions are defined:
  • Admins. These operations can be performed by RODL admins, or clients closely coupled with RODL.
  • Authenticated users. These operations can be performed by RODL users, authorized using OAuth.
  • Public: No authorization is necessary to perform these operations.

Conformance with external APIs

For managing user identification, the Simple Cloud Identity Management API [1] [2] is used.

The SCIM Protocol is an application-level, REST protocol for provisioning and managing identity data on the web. The protocol supports creation, modification, retrieval, and discovery of core identity Resources; i.e., Users and Groups, as well as custom Resource extensions.
The SCIM API is used as a base and not all required resources may initially be implemented, i.e. Groups.

The following design rules are taken from SCIM:

  • The Users/ resource API
  • The use of JSON for resource representation
  • The use of OAuth 2.0 Bearer schema for request authorization
Following the SCIM recommendation and previous experiences, RODL uses OAuth 2.0 API [3].
The OAuth 2.0 authorization framework enables a third-party application to obtain limited access to an HTTP service, either on behalf of a resource owner by orchestrating an approval interaction between the resource owner and the HTTP service, or by allowing the third-party application to obtain access on its own behalf.

RODL implements the authorization code grant with support for native applications. It uses the Bearer authorization schema.

API usage

Identity management (based on SCIM)

The operations below are taken from the SCIM API [1]. The set of operations is minimal in order to allow user registration, update, delete and retrieval. It does not include getting/filtering/sorting all existing users, nor any operations on user groups.

⚠️ Authentication
SCIM API and Core Schema read that the password may be stored for each user and must not ever be returned in response. They don't specify any particular mechanism for authentication, i.e. password verification. Such operation will have to be added in here.
⚠️ User URI vs. id
This API uses user URIs. The clients may identify their users using their usernames. To create the access token, user ID is used. This needs to be simplified.

Create a user.

Allowed for: admins. 

C: POST /Users HTTP/1.1
C: Host: service.example.org
C: Accept: application/json
C: Authorization: Bearer h480djs93hd8
C: Content-Length: ...
C:
C: {
     "schemas":["urn:scim:schemas:core:1.0"],
     "userName":"bjensen",
     "password":"cleartext",
     "myExperimentId":"http://www.myexperiment.org/users/1",
     "openId":"bjensen.myopenid.com",
     "name":{
       "formatted":"Ms. Barbara J Jensen III"
     }
   }

S: HTTP/1.1 201 Created
S: Content-Type: application/json
S: Location: https://sandbox/rodl/Users/2819c223-7f76-453a-919d-413861904646
S:
S: {
     "schemas":["urn:scim:schemas:core:1.0"],
     "userName":"bjensen",
     "myExperimentId":"http://www.myexperiment.org/users/1",
     "openId":"bjensen.myopenid.com",
     "name":{
       "formatted":"Ms. Barbara J Jensen III"
     }
   }
❗ Comments to the user schema
  • userName, password: should only be used when the user authenticates in RODL. Password must be sent in clear text and must never be sent back, as defined in SCIM.
  • myExperimentId: not defined in SCIM.
  • openId: not defined in SCIM.

Get a user.

Allowed for: public. 

C: GET /Users/2819c223-7f76-453a-919d-413861904646
C: Host: example.com
C: Accept: application/json
C: Authorization: Bearer h480djs93hd8

S: HTTP/1.1 200 OK
S: Content-Type: application/json
S:
S: {
     "schemas":["urn:scim:schemas:core:1.0"],
     "userName":"bjensen",
     "myExperimentId":"http://www.myexperiment.org/users/1",
     "openId":"bjensen.myopenid.com",
     "name":{
       "formatted":"Ms. Barbara J Jensen III"
     }
   }

Modify a user.

Allowed for: admins. 

C: PUT /Users/2819c223-7f76-453a-919d-413861904646 HTTP/1.1
C: Host: service.example.org
C: Accept: application/json
C: Authorization: Bearer h480djs93hd8
C: Content-Length: ...
C:
C: {
     "schemas":["urn:scim:schemas:core:1.0"],
     "userName":"bjensen",
     "password":"cleartext",
     "myExperimentId":"http://www.myexperiment.org/users/1",
     "openId":"bjensen.myopenid.com",
     "name":{
       "formatted":"Ms. Barbara J Jensen III"
     }
   }

S: HTTP/1.1 200 OK
S: Content-Type: application/json
S: Location: https://sandbox/rodl/Users/2819c223-7f76-453a-919d-413861904646
S:
S: {
     "schemas":["urn:scim:schemas:core:1.0"],
     "userName":"bjensen",
     "myExperimentId":"http://www.myexperiment.org/users/1",
     "openId":"bjensen.myopenid.com",
     "name":{
       "formatted":"Ms. Barbara J Jensen III"
     }
   }

Delete a user.

Allowed for: admins. 

C: DELETE /Users/2819c223-7f76-453a-919d-413861904646
C: Host: example.com
C: Authorization: Bearer h480djs93hd8

S: HTTP/1.1 204 No Content
⚠️ SCIM defines a 200 OK response but 204 No Content seems more appropriate?

Authorization management (based on OAuth 2.0)

The operations below use resources taken from the OAuth 2.0 specification [3]. In case of identifying the access token owner, the request uses also the SCIM Core Schema [2].

Identify the access token owner

Who-Am-I resource. Allows clients to check which user the access token belongs to.

Allowed for: authenticated. 

C: GET /whoami/
C: Host: example.com
C: Accept: application/json
C: Authorization: Bearer h480djs93hd8

S: HTTP/1.1 200 OK
S: Content-Type: application/json
S: Location: https://sandbox/rodl/Users/2819c223-7f76-453a-919d-413861904646
S:
S: {
     "schemas":["urn:scim:schemas:core:1.0"],
     "userName":"bjensen",
     "myExperimentId":"http://www.myexperiment.org/users/1",
     "openId":"bjensen.myopenid.com",
     "name":{
       "formatted":"Ms. Barbara J Jensen III"
     }
   }

Create an access token.

Allowed for: admins. 

C: POST /accesstokens/
C: Host: example.com
C: Accept: application/json
C: Authorization: Bearer h480djs93hd8
C:
C: {
     "clientId":"61904646-7f76-453a-919d-41382819c223",
     "userId":"2819c223-7f76-453a-919d-413861904646"
   }

S: HTTP/1.1 201 Created
S: Content-Type: application/json
S: Location: https://sandbox/rodl/accesstokens/7f76c223-2819-4646-919d-41386190453a
S:
S: {
     "clientId":"61904646-7f76-453a-919d-41382819c223",
     "userId":"2819c223-7f76-453a-919d-413861904646"
   }

Get access token details.

Allowed for: admins. 

C: GET /accesstokens/7f76c223-2819-4646-919d-41386190453a
C: Host: example.com
C: Accept: application/json
C: Authorization: Bearer h480djs93hd8

S: HTTP/1.1 200 OK
S: Content-Type: application/json
S:
S: {
     "clientId":"61904646-7f76-453a-919d-41382819c223",
     "userId":"2819c223-7f76-453a-919d-413861904646"
   }

Get a list of access tokens.

Query params are optional.

Allowed for: admins. 

C: GET /accesstokens?clientId=61904646-7f76-453a-919d-41382819c223&userId=2819c223-7f76-453a-919d-413861904646
C: Host: example.com
C: Accept: application/json
C: Authorization: Bearer h480djs93hd8

S: HTTP/1.1 200 OK
S: Content-Type: application/json
S:
S: {
     "accessTokens":["7f76c223-2819-4646-919d-41386190453a", "7f76c223-919d-4646-2819-41386190453a"]
   }


<pre>

====Delete an access token.====

Allowed for: admins.
<pre>


C: DELETE /accesstokens/7f76c223-2819-4646-919d-41386190453a
C: Host: example.com
C: Authorization: Bearer h480djs93hd8

S: HTTP/1.1 204 No Content

Register a new client application.

Allowed for: admins. 

C: POST /clients/
C: Host: example.com
C: Accept: application/json
C: Authorization: Bearer h480djs93hd8
C:
C: {
     "name":"A test app",
     "callbackURL":"http://sandbox/testapp/oauth",
     "clientSecret":"2819c223-7f76-453a-919d-413861904646"
   }

S: HTTP/1.1 201 Created
S: Content-Type: application/json
S: Location: https://sandbox/rodl/clients/7f76c223-2819-4646-919d-41386190453a
S:
S: {
     "name":"A test app",
     "callbackURL":"http://sandbox/testapp/oauth"
   }

Get client application details.

Allowed for: admins. 

C: GET /clients/7f76c223-2819-4646-919d-41386190453a
C: Host: example.com
C: Accept: application/json
C: Authorization: Bearer h480djs93hd8

S: HTTP/1.1 200 OK
S: Content-Type: application/json
S:
S: {
     "name":"A test app",
     "callbackURL":"http://sandbox/testapp/oauth"
   }

Modify client application details.

Allowed for: admins. 

C: PUT /clients/7f76c223-2819-4646-919d-41386190453a
C: Host: example.com
C: Accept: application/json
C: Authorization: Bearer h480djs93hd8
C: {
     "name":"Another test app",
     "callbackURL":"http://sandbox/testapp/oauth"
   }

S: HTTP/1.1 200 OK
S: Content-Type: application/json
S:
S: {
     "name":"Another test app",
     "callbackURL":"http://sandbox/testapp/oauth"
   }

Delete a client application.

Allowed for: admins. 

C: DELETE /clients/7f76c223-2819-4646-919d-41386190453a
C: Host: example.com
C: Authorization: Bearer h480djs93hd8

S: HTTP/1.1 204 No Content

Link relations

The API uses SCIM API [1] and Core Schema 1.0 [2], which uses JSON as a common format.

No link relations are used in identity management. Upon creating the user, its URI is returned in the Location HTTP header. Clients will be able to discover the user URI for a given username using query params.

References

  1. http://www.simplecloud.info/specs/draft-scim-api-00.html
  2. http://www.simplecloud.info/specs/draft-scim-core-schema-00.html
  3. http://oauth.net/2/
Add a custom footer

RO Services and APIs

Clone this wiki locally