API for Authentication and Authorization

API for Authentication

Create User

POST http://auth-sagebase-org.elasticbeanstalk.com/auth/v1/user
{"userId":"demouser", "email":"demouser@sagebase.org", "firstName":"demo", "lastName":"user", "displayName":"Demo User"}

Successful Response:

HTTP/1.1 201 Created

Missing password or user ID already exists:

HTTP/1.1 400 Bad Request

Update User

PUT http://auth-sagebase-org.elasticbeanstalk.com/auth/v1/user
sessionToken:<sessionToken>
{"userId":"demouser", "email":"demouser@sagebase.org", "firstName":"demo", "lastName":"user", "displayName":"Demo User"}

 where <sessionToken> is that returned by "Initiate Session", below.  Note the authentication service manage the properties shown (principally the userId and password) while the repository services (below) manage other related user attributes.

Successful Response:

HTTP/1.1 200 OK

Error Response, if the session token is missing or does not match userId:

HTTP/1.1 400 Bad Request
Content-Type: application/json
{"reason":"Not authorized."}

Send Change-Password Email

POST http://auth-sagebase-org.elasticbeanstalk.com/auth/v1/userPasswordEmail
{"userId":"demouser"}

Successful Response:

HTTP/1.1 204 NO CONTENT

Initiate Session (Login)

Request:

POST http://auth-sagebase-org.elasticbeanstalk.com/auth/v1/session
{"userId":"demouser", "password":"demouser-pw"}

Successful Response:

HTTP/1.1 201 Created
Content-Type: application/json
{"displayName":"Demo User","sessionToken":"AYcOhWIm9NdOC6BdzzzisQ00"}

Error Response, if the user authentication details are incorrect:

HTTP/1.1 400 Bad Request
AuthenticationURL: http://auth-sagebase-org.elasticbeanstalk.com/auth/v1/session
Content-Type: application/json
{"reason":"Unable to authenticate."}

Session token is valid for a period of time, currently set to 24 hours.

Refresh Token (reset timer)

Request:

PUT http://auth-sagebase-org.elasticbeanstalk.com/auth/v1/session
{"sessionToken":"AYcOhWIm9NdOC6BdzzzisQ00"}

Successful Response:

HTTP/1.1 200 OK

Error Response, if the session token is invalid:

HTTP/1.1 404 Not Found
{"reason":"Unable to validate session."}

Terminate Session (Logout)

Request:

DELETE http://auth-sagebase-org.elasticbeanstalk.com/auth/v1/session
{"sessionToken":"AYcOhWIm9NdOC6BdzzzisQ00"}

Response:

HTTP/1.1 204 NO CONTENT

Sample commands, issued from cURL:

Create User:
curl -k -H "Content-Type:application/json" -H "Accept:application/json" -d "{\"userId\":\"NEWuser\", \"email\":\"demouser@sagebase.org\", \"firstName\":\"demo\", \"lastName\":\"user\", \"displayName\":\"Demo User\"}" -X POST http://auth-sagebase-org.elasticbeanstalk.com/auth/v1/user

Update User:
curl -k -H "Content-Type:application/json" -H "Accept:application/json" -d "{\"userId\":\"NEWuser\", \"email\":\"demouser@sagebase.org\", \"firstName\":\"NEWdemo\", \"lastName\":\"NEWuser\", \"displayName\":\"NEWDemo User\"}" -X PUT http://auth-sagebase-org.elasticbeanstalk.com/auth/v1/user

Send Change Password Email:
curl -k -H "Content-Type:application/json" -H "Accept:application/json" -d "{\"userId\":\"demouser\"}" -X POST http://auth-sagebase-org.elasticbeanstalk.com/auth/v1/userPasswordEmail

Login:
curl -k -H "Content-Type:application/json" -H "Accept:application/json" -d "{\"userId\":\"demouser\", \"password\":\"demouser-pw\"}" -X POST http://auth-sagebase-org.elasticbeanstalk.com/auth/v1/session

Refresh session token:

curl -k -H "Content-Type:application/json" -H "Accept:application/json" -d "{\"sessionToken\":\"QYNoamrOKK0dBhjZOFfbAg00\"}" -X PUT http://auth-sagebase-org.elasticbeanstalk.com/auth/v1/session

Logout:
curl -k -H "Content-Type:application/json" -H "Accept:application/json" -d "{\"sessionToken\":\"QYNoamrOKK0dBhjZOFfbAg00\"}" -X DELETE http://auth-sagebase-org.elasticbeanstalk.com/auth/v1/session

Access repository services anonymously:
curl -H Accept:application/json http://localhost:8080/repo/v1/dataset/test

Access repository services with session token (obtained by logging in):
curl -H Accept:application/json -H sessionToken:AprxPRzpmaPm7FXzV1ik0w00 http://localhost:8080/repo/v1/dataset/test

Authentication of Requests to Platform

Requests shall include a header named "sessionToken" whose value is that returned by the Initiate Session request, above.  (The session will timeout eventually, with a nominal duration of 24 hours.)

For requests that fail to be authenticated the response will include the headers:

WWW-Authenticate: authenticate Crowd

and a plain text body:  "The token provided was invalid or expired."

API for Authorization

(Note, the URL may migrate from that of the repository services to a separate location.)

Create Group

POST http://repositoryservice.sagebase.org/repo/v1/usergroup
{"name":"MyGroup", "creatableTypes":["type1","type2","type3"]}

Note: The group's name must be unique in the system.

Note: Only an administrator may specify the "creatableTypes" argument.  Other users must omit this field, or get an UnauthorizedException.

Retrieve Groups

GET http://repositoryservice.sagebase.org/repo/v1/usergroup

Retrieve Group

GET http://repositoryservice.sagebase.org/repo/v1/usergroup/{id}

Delete Group

DELETE http://repositoryservice.sagebase.org/repo/v1/usergroup/{id}

Update Group

(shallow properties, i.e. the group's name)

PUT http://repositoryservice.sagebase.org/repo/v1/usergroup/{id}
{"name":"MyGroup", "creatableTypes":["type1","type2","type3"]}

Note: The group's name must be unique in the system.

Note: Only an administrator may specify the "creatableTypes" argument.  Other users must omit this field, or get an UnauthorizedException.

Get the users in the system

GET http://repositoryservice.sagebase.org/repo/v1/user

Note: This provides the {uid} values for the following requests.

Update a user's shallow properties

PUT http://repositoryservice.sagebase.org/repo/v1/user/{uid}
{"userId":"mkellen", "iamAccessId":"asdfasfsf", "iamSecretKey":"asfsafsf"}

Note: It is not permissible to change the user's userId.

Add a user to the group

POST http://repositoryservice.sagebase.org/repo/v1/usergroup/{gid}/users/{uid}

Remove a user from the group

DELETE http://repositoryservice.sagebase.org/repo/v1/usergroup/{gid}/users/{uid}

Get all the users in a group

GET http://repositoryservice.sagebase.org/repo/v1/usergroup/{gid}/users

Give a group access to a resource, specifying the allowable access types

Note: A resource is specified by its type and an identifier, unique within a type.  Allowable types are returned by the DAOs in the 'models' package, e.g. org.sagebionetworks.repo.model.DatasetDAO.getType() returns the type for Datasets.

POST http://repositoryservice.sagebase.org/repo/v1/usergroup/{gid}/resources/{rtype}/{rid}
{"accessType":["READ","CHANGE","SHARE"]}

Remove all access to a resource from a group

DELETE http://repositoryservice.sagebase.org/repo/v1/usergroup/{gid}/resources/{rtype}/{rid}

Find out the access types a group has for a resource

GET http://repositoryservice.sagebase.org/repo/v1/usergroup/{gid}/resources/{rtype}/{rid}