Page Comparison

Wiki Markup
h1. API for Authentication and Authorization

...

Table of Contents

API for Authentication

Create User

Code Block


{toc}


h2. API for Authentication


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


Successful Response:

...


{code

}
HTTP/1.1 201 Created

Missing password or user ID already exists:

Code Block
{code} Missing password or user ID already exists: {code} HTTP/1.1 400 Bad Request

Update User

Code Block

{code}


h3. Update User

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

...

{code}

&nbsp;where <sessionToken> is that returned by "Initiate Session", below.

...



Successful Response:

...


{code

}
HTTP/1.1 200 OK
{code}

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

...


{code

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

...

{code}

h3. Send Change-Password Email

...


{code

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

...

{code}


Successful Response:

...


{code

}
HTTP/1.1 204 NO CONTENT

...


{code}

h3. Initiate Session (Login)

...



Request:

...



{code

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


Successful Response:

...


{code

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

Error Response, if the user authentication details are incorrect:

...


{code

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

Code Block

{code}




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



h3. Refresh Token (reset timer)

Request:

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

...

{code}


Successful Response:

...


{code

}
HTTP/1.1 200 OK
{code}

Error Response, if the session token is invalid:

...


{code

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

...

{code}

h3. Terminate Session (Logout)

...





Request:

...



{code

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


Response:

...



{code

}
HTTP/1.1 204 NO CONTENT

...


{code}



h2. 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:

...

]













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

Code Block

]\\




h3. Authentication of Requests to Platform

Requests shall include a header named "sessionToken"&nbsp;whose value is that&nbsp;returned by the Initiate Session request, above.&nbsp; (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:&nbsp; "The token provided was invalid or expired."

h2. API for Authorization

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

h3. Create Group
{code}
POST http://repositoryservice.sagebase.org/repo/v1/usergroup
{"name":"MyGroup"}
{code}


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

...

Retrieve Groups

Code Block
h3. Retrieve Groups {code} GET http://repositoryservice.sagebase.org/repo/v1/usergroup

Retrieve Group

Code Block
{code} h3. Retrieve Group {code} GET http://repositoryservice.sagebase.org/repo/v1/usergroup/{id}

Delete Group

Code Block
{code} h3. Delete Group {code} DELETE http://repositoryservice.sagebase.org/repo/v1/usergroup/{id}

Update Group

{code}

h3. Update Group

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

...


{code

}
PUT http://repositoryservice.sagebase.org/repo/v1/usergroup/{id}
{"name":"OurGroup"}
{code}

h3. Get the users in the system
{code}
GET http://repositoryservice.sagebase.org/repo/v1/user
{code}

Add a user to the group

Code Block
Note: This provides the {uid} values for the following requests. h3. Add a user to the group {code} PUT http://repositoryservice.sagebase.org/repo/v1/usergroup/{gid}/users/{uid}

Remove a user from the group

Code Block
{code} h3. Remove a user from the group {code} DELETE http://repositoryservice.sagebase.org/repo/v1/usergroup/{gid}/users/{uid}

Get all the users in a group

Code Block
{code} h3. Get all the users in a group {code} GET http://repositoryservice.sagebase.org/repo/v1/usergroup/{gid}/users

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

...

{code}

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.&nbsp; Allowable types are returned by the DAOs in the 'models' package, e.g. org.sagebionetworks.repo.model.DatasetDAO.getType() returns the type for Datasets.

...



{code

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

Remove all access to a resource from a group

Code Block
{code} h3. Remove all access to a resource from a group {code} DELETE http://repositoryservice.sagebase.org/repo/v1/usergroup/{gid}/resources/{rtype}/{rid}

Find out the access types a group has for a resource

Code Block
{code} h3. Find out the access types a group has for a resource {code} GET http://repositoryservice.sagebase.org/repo/v1/usergroup/{gid}/resources/{rtype}/{rid} {code}

Versions Compared

Old Version 38

New Version 39

Key

API for Authentication

Create User

Update User

Refresh Token (reset timer)

Authentication of Requests to Platform

API for Authorization

Create Group

Retrieve Groups

Retrieve Group

Delete Group

Update Group

Add a user to the group

Remove a user from the group

Get all the users in a group

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

Remove all access to a resource from a group

Find out the access types a group has for a resource