-
Notifications
You must be signed in to change notification settings - Fork 2
User Management API
Soumya Brahma edited this page Feb 6, 2016
·
4 revisions
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.
- 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.
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
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.
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.
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.
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" } }
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" } }
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?
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].
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" } }
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" }
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" }
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"] }
Allowed for: admins.
C: DELETE /accesstokens/7f76c223-2819-4646-919d-41386190453a C: Host: example.com C: Authorization: Bearer h480djs93hd8 S: HTTP/1.1 204 No Content
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" }
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" }
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" }
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
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.