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.

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"}

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

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":"OurGroup"}

Get the users in the system

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

Note: This provides the

h3. Remove a user from the group

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

h3. Get all the users in a group

/users

h3. 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.

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

h3. Remove all access to a resource from a group

/resources/

h3. Find out the access types a group has for a resource

/