API for Authentication and Authorization
API for Authentication
Create User
POST https://staging-auth.elasticbeanstalk.com/auth/v1/user
{"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
Get User
Retrieves the user based on the session token header, which is required. Note: the "password" field will be null, since retrieving a user's password is not permitted.
GET https://staging-auth.elasticbeanstalk.com/auth/v1/user
HTTP/1.1 200 OK
Content-Type: application/json
{
"displayName": "Demo User",
"email": "demouser@sagebase.org",
"firstName": "demo",
"lastName": "user",
"password": null
}
Update User
PUT https://staging-auth.elasticbeanstalk.com/auth/v1/user
sessionToken:<sessionToken>
{"email":"demouser@sagebase.org", "firstName":"demo", "lastName":"user", "displayName":"Demo User", "password":"foobar"}
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 204 No Content
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 https://staging-auth.elasticbeanstalk.com/auth/v1/userPasswordEmail
{"email":"demouser@sagebase.org"}
Successful Response:
HTTP/1.1 204 NO CONTENT
Initiate Session (Login)
Request:
POST https://staging-auth.elasticbeanstalk.com/auth/v1/session
{"email":"demouser@sagebase.org", "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: https://staging-auth.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 https://staging-auth.elasticbeanstalk.com/auth/v1/session
{"sessionToken":"AYcOhWIm9NdOC6BdzzzisQ00"}
Successful Response:
HTTP/1.1 204 No Content
Error Response, if the session token is invalid:
HTTP/1.1 404 Not Found
{"reason":"Unable to validate session."}
Terminate Session (Logout)
Note: Sessions initiated by multiple clients for the same user around the same time will receive identical "single sign on" tokens. Since session termination is linked to the session token, terminating the session for one client via this command will have the side effect of terminating all sessions. An alternative is for the client simply to delete its own copy of the token.
Request:
DELETE https://staging-auth.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 "{\"email\":\"demouser@sagebase.org\", \"firstName\":\"demo\", \"lastName\":\"user\", \"displayName\":\"Demo User\"}" -X POST https://staging-auth.elasticbeanstalk.com/auth/v1/user
Update User:
curl -k -H "Content-Type:application/json" -H "Accept:application/json" -d "{\"email\":\"demouser@sagebase.org\", \"firstName\":\"NEWdemo\", \"lastName\":\"NEWuser\", \"displayName\":\"NEWDemo User\"}" -X PUT https://staging-auth.elasticbeanstalk.com/auth/v1/user
Send Change Password Email:
curl -k -H "Content-Type:application/json" -H "Accept:application/json" -d "{\"email\":\"demouser@sagebase.org\"}" -X POST https://staging-auth.elasticbeanstalk.com/auth/v1/userPasswordEmail
Login:
curl -k -H "Content-Type:application/json" -H "Accept:application/json" -d "{\"email\":\"demouser@sagebase.org\", \"password\":\"demouser-pw\"}" -X POST https://staging-auth.elasticbeanstalk.com/auth/v1/session
Refresh session token:
curl -k -H "Content-Type:application/json" -H "Accept:application/json" -d "{\"sessionToken\":\"QYNoamrOKK0dBhjZOFfbAg00\"}" -X PUT https://staging-auth.elasticbeanstalk.com/auth/v1/session
Logout:
curl -k -H "Content-Type:application/json" -H "Accept:application/json" -d "{\"sessionToken\":\"QYNoamrOKK0dBhjZOFfbAg00\"}" -X DELETE https://staging-auth.elasticbeanstalk.com/auth/v1/session
Access repository services anonymously:
curl -H Accept:application/json https://staging-reposervice.elasticbeanstalk.com/repo/v1/dataset/test
Access repository services with session token (obtained by logging in):
curl -H Accept:application/json -H sessionToken:AprxPRzpmaPm7FXzV1ik0w00 https://staging-reposervice.elasticbeanstalk.com/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
Get the users who can be added to a resource's ACL
GET https://staging-reposervice.elasticbeanstalk.com/repo/v1/user
[
{"name":"anonymous","id":"3","creationDate":1307402971000,"uri":null,"etag":null,"individual":true},
{"name":"foo@sagebase.org","id":"4","creationDate":1307403226000,"uri":null,"etag":null,"individual":true}
]
Get the groups who can be added to a resource's ACL
GET https://staging-reposervice.elasticbeanstalk.com/repo/v1/userGroup
[
{"name":"Identified Users","id":"1","creationDate":1307141423000,"uri":null,"etag":null,"individual":false},
{"name":"Federation Group","id":"2","creationDate":1307141423000,"uri":null,"etag":null,"individual":false}
]
Note: The "id" fields returned from /user and /userGroup are used in the "userGroupId" fields in the ACLs shown below.
Get Access Control List for a Resource
Returns the ACL for the node responsible for the given node's permissions. Note: In the following example, 'resourceId' is the id of the node to which permissions are attached, either rid or one of rid's ancestors; 'resource_type' is the type of rid (project, dataset, layer, etc.); there is one 'resourceAccess' entry per UserGroup (aka 'principal') having access to the resource; 'userGroupId' is the id of the UserGroup object; 'accessType' is the list of types of access the given UserGroup has to the given resource.
GET https://staging-reposervice.elasticbeanstalk.com/repo/v1/{resource_type}/{rid}/acl
{"id":"1",
"creationDate":1307141851484,
"uri":null,
"etag":"0",
"createdBy":"admin",
"resourceId":"1",
"resourceAccess":[
{"id":"1",
"userGroupId":"4",
"accessType":["READ","CHANGE_PERMISSIONS","DELETE","UPDATE","CREATE"]
}
],
"modifiedBy":"admin",
"modifiedOn":1307141851483
}
Create Access Control List for a Resource
Note: This is only used when the resource 'rid' currently inherits its access control list from an ancestor. This request causes 'rid' to cease ACL inheritance and instead use the ACL passed in with the request.
POST https://staging-reposervice.elasticbeanstalk.com/repo/v1/{resource_type}/{rid}/acl
{
"resourceId":{rid},
"resourceAccess":[
{"userGroupId":"4",
"accessType":["READ","CHANGE_PERMISSIONS","DELETE","UPDATE","CREATE"]
}
]
}
Update Access Control List for a Resource
Note: This is only used when a "resourceId" already specifies its access control list (does not inherit from an ancestor).
PUT https://staging-reposervice.elasticbeanstalk.com/repo/v1/{resource_type}/{rid}/acl
{"id":"1",
"etag":"0",
"resourceId":{rid},
"resourceAccess":[
{"id":"1",
"userGroupId":"4",
"accessType":["READ","CHANGE_PERMISSIONS","DELETE","UPDATE","CREATE"]
}
],
}
Delete Access Control List for a Resource
This deletes the given object's ACL, restoring its dependence on its owner's permissions.
DELETE https://staging-reposervice.elasticbeanstalk.com/repo/v1/{resource_type}/{rid}/acl
Ask whether there is access to a Resource
Note: The query is asked for the user who is implied by the session token, or 'anonymous' if there is no token.
GET https://staging-reposervice.elasticbeanstalk.com/repo/v1/{resource_type}/{rid}/access?accessType={accessType}
{"result":true}
More Examples
Add a particular user with full access and identified individuals with read-only access to a project.
Get Request:
curl -H sessionToken:XXXXXXXXXXXXXXXXXX -H Content-Type:application/json -k https://reposvc-alpha.sagebase.org/repo/v1/project/498/acl
Get Response:
{
"id":"3",
"creationDate":1308274656084,
"etag":"0",
"createdBy":"nicole.deflaux@sagebase.org",
"resourceId":"498",
"resourceAccess":[
{
"id":"4",
"userGroupId":"7",
"accessType":[
"DELETE",
"CHANGE_PERMISSIONS",
"UPDATE",
"READ",
"CREATE"
]
}
],
"modifiedBy":"nicole.deflaux@sagebase.org",
"modifiedOn":1308274656084,
"uri":"/repo/v1/project/498/acl"
}
Update Request:
curl -H sessionToken:XXXXXXXXX -H Content-Type:application/json -X PUT -d '{
"id":"3",
"creationDate":1308274656084,
"etag":"0",
"createdBy":"nicole.deflaux@sagebase.org",
"resourceId":"498",
"resourceAccess":[
{
"userGroupId":"1",
"accessType":[
"READ"
]
},
{
"userGroupId":"7",
"accessType":[
"DELETE",
"CHANGE_PERMISSIONS",
"UPDATE",
"READ",
"CREATE"
]
},
{
"userGroupId":"18",
"accessType":[
"DELETE",
"CHANGE_PERMISSIONS",
"UPDATE",
"READ",
"CREATE"
]
}
],
"modifiedBy":"nicole.deflaux@sagebase.org",
"modifiedOn":1308274656084,
"uri":"/repo/v1/project/498/acl"
}' https://reposvc-alpha.sagebase.org/repo/v1/project/498/acl
Update Response:
{
"id":"3",
"creationDate":1308274656084,
"etag":"0",
"createdBy":"nicole.deflaux@sagebase.org",
"resourceId":"498",
"resourceAccess":[
{
"id":null,
"userGroupId":"7",
"accessType":[
"DELETE",
"UPDATE",
"CHANGE_PERMISSIONS",
"READ",
"CREATE"
]
},
{
"id":null,
"userGroupId":"18",
"accessType":[
"DELETE",
"UPDATE",
"CHANGE_PERMISSIONS",
"READ",
"CREATE"
]
},
{
"id":null,
"userGroupId":"1",
"accessType":[
"READ"
]
}
],
"modifiedBy":"nicole.deflaux@sagebase.org",
"modifiedOn":1308274656084,
"uri":"/repo/v1/project/498/acl"
}