| Section | ||||||||||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
|
...
API for Authentication
Create User
| Code Block |
|---|
POST https://auth-staging.sagebase.org/auth/v1/user
{"email":"demouser@sagebase.org", "firstName":"demo", "lastName":"user", "displayName":"Demo User"}
|
Successful Response:
| Code Block |
|---|
HTTP/1.1 201 Created
|
Missing password or user ID already exists:
| Code Block |
|---|
HTTP/1.1 400 Bad Request
|
Note: As a side effect this will send an email to the given address, prompting the user to set their password.
...
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.
| Code Block |
|---|
GET https://auth-staging.sagebase.org/auth/v1/user
|
| Code Block |
|---|
HTTP/1.1 200 OK
Content-Type: application/json
{
"displayName": "Demo User",
"email": "demouser@sagebase.org",
"firstName": "demo",
"lastName": "user",
"password": null
}
|
Update User
| Code Block |
|---|
PUT https://auth-staging.sagebase.org/auth/v1/user
sessionToken:<sessionToken>
{"firstName":"demo", "lastName":"user", "displayName":"Demo User"}
|
...
Successful Response:
| Code Block |
|---|
HTTP/1.1 204 No Content
|
Error Response, if the session token is missing or does not match userId:
| Code Block |
|---|
HTTP/1.1 400 Bad Request
Content-Type: application/json
{"reason":"Not authorized."}
|
Send Change-Password Email
| Code Block |
|---|
POST https://auth-staging.sagebase.org/auth/v1/userPasswordEmail
{"email":"demouser@sagebase.org"}
|
Successful Response:
| Code Block |
|---|
HTTP/1.1 204 No Content
|
If the email address is not in the user database:
| Code Block |
|---|
HTTP/1.1 400 Bad Request
|
Note: The email template is in the auth-util package, in the file resetpasswordEmail.txt. The reset link, along with the smtp parameters, is in the file authutil.properties.
Send Set-API-Password Email
| Code Block |
|---|
POST https://auth-staging.sagebase.org/auth/v1/apiPasswordEmail
{"email":"demouser@sagebase.org"}
|
Successful Response:
| Code Block |
|---|
HTTP/1.1 204 No Content
|
If the email address is not in the user database:
| Code Block |
|---|
HTTP/1.1 400 Bad Request
|
Note: The email template is in the auth-util package, in the file setAPIpasswordEmail.txt. The reset link, along with the smtp parameters, is in the file authutil.properties.
Set Password
| Code Block |
|---|
POST https://auth-staging.sagebase.org/auth/v1/userPassword
{"email":"demouser@sagebase.org", "password":"foobar"}
|
Successful Response:
| Code Block |
|---|
HTTP/1.1 204 No Content
|
Note: Session token is required in request header.
Get Secret Key for HMAC Authentication
| Code Block |
|---|
GET https://auth-staging.sagebase.org/auth/v1/secretKey
|
Successful Response:
| Code Block |
|---|
HTTP/1.1 200 {"secretKey":"0Ocy/cW/3WIdZg3Up9dguO4Kh5smBKpN7iWXAvVQqekGD3gT4nc7PWwlfOhcL+KW6W4PjXtgPQNhiP7yrwjfwQ=="}
|
...
Invalidate Secret Key
| Code Block |
|---|
DELETE https://auth-staging.sagebase.org/auth/v1/secretKey
|
Successful Response:
| Code Block |
|---|
HTTP/1.1 204 No Content
|
Note: Session token is required in request header. The key which is invalidated is that of the user authenticated by the session token.
Initiate Session (Login)
Request:
| Code Block |
|---|
POST https://auth-staging.sagebase.org/auth/v1/session
{"email":"demouser@sagebase.org", "password":"demouser-pw"}
|
Successful Response:
| Code Block |
|---|
HTTP/1.1 201 Created
Content-Type: application/json
{"displayName":"Demo User","sessionToken":"AYcOhWIm9NdOC6BdzzzisQ00"}
|
Error Response, if the user authentication details are incorrect:
| Code Block |
|---|
HTTP/1.1 400 Bad Request
AuthenticationURL: https://auth-staging.sagebase.org/auth/v1/session
Content-Type: application/json
{"reason":"Unable to authenticate."}
|
...
Refresh Token (reset timer)
Request:
| Code Block |
|---|
PUT https://auth-staging.sagebase.org/auth/v1/session
{"sessionToken":"AYcOhWIm9NdOC6BdzzzisQ00"}
|
Successful Response:
| Code Block |
|---|
HTTP/1.1 204 No Content
|
Error Response, if the session token is invalid:
| Code Block |
|---|
HTTP/1.1 404 Not Found
{"reason":"Unable to validate session."}
|
...
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:
| Code Block |
|---|
DELETE https://auth-staging.sagebase.org/auth/v1/session
{"sessionToken":"AYcOhWIm9NdOC6BdzzzisQ00"}
|
Response:
| Code Block |
|---|
HTTP/1.1 204 NO CONTENT
|
Sample commands, issued from cURL:
...
Access repository services with session token (obtained by logging in):
curl -H Accept:application/json -H sessionToken:AprxPRzpmaPm7FXzV1ik0w00 https://repo-staging.sagebase.org/repo/v1/dataset/test
Access repository services with HMAC-SHA1 signed request:
curl -i -H "Content-Type:application/json" -H "Accept:application/json" -H signatureTimestamp:2011-09-27T21:59:22.371-07:00 -H signature:yhMgokIH9ErQklj8oUuhHR5o5QM= -H userId:demouser@sagebase.org -X GET "http://localhost:8080/services-repository-0.7-SNAPSHOT/repo/v1/dataset?sort=name&limit=3"
...
Request shall include the following headers:
| Code Block |
|---|
userId: demouser@sagebase.org
signatureTimestamp: 2011-07-16T19:20:30.45+01:00 (i.e. in ISO8601 format including time zone)
signature: <signature>
|
...
then the URI is:
/repo/v1/dataset
Authentication Failure
For requests that fail to be authenticated the response will include the headers:
...
Get the users who can be added to a resource's ACL
| Code Block |
|---|
GET https://repo-staging.sagebase.org/repo/v1/user
|
| Code Block |
|---|
[
{"name":"anonymous@sagebase.org","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
| Code Block |
|---|
GET https://repo-staging.sagebase.org/repo/v1/userGroup
|
| Code Block |
|---|
[
{"name":"AUTHENTICATED_USERS","id":"1","creationDate":1307141423000,"uri":null,"etag":null,"individual":false},
{"name":"PUBLIC","id":"2","creationDate":1307141423000,"uri":null,"etag":null,"individual":false},
{"name":"Federation Group","id":"3","creationDate":1307141423000,"uri":null,"etag":null,"individual":false}
]
|
...
Returns the ACL for the node responsible for the given node's permissions. Note: In the following example, 'id' is the id of the node to which permissions are attached; there is one 'resourceAccess' entry per UserGroup (aka 'principal') having access to the resource; 'groupName' is the name of the UserGroup object; 'accessType' is the list of types of access the given UserGroup has to the given resource.
| Code Block |
|---|
GET https://repo-staging.sagebase.org/repo/v1/{resource_type}/{rid}/acl
|
| Code Block |
|---|
{"id":"1",
"creationDate":1307141851484,
"uri":null,
"etag":"0",
"createdBy":"admin",
"resourceAccess":[
{"id":"1",
"groupName":"PUBLIC",
"accessType":["READ","CHANGE_PERMISSIONS","DELETE","UPDATE","CREATE"]
}
],
"modifiedBy":"admin",
"modifiedOn":1307141851483
}
|
...
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.
| Code Block |
|---|
POST https://repo-staging.sagebase.org/repo/v1/{resource_type}/{rid}/acl
{"id":"{rid}",
"resourceAccess":[
{"groupName":"PUBLIC",
"accessType":["READ","CHANGE_PERMISSIONS","DELETE","UPDATE","CREATE"]
}
]
}
|
...
Note: This is only used when a "resourceId" already specifies its access control list (does not inherit from an ancestor).
| Code Block |
|---|
PUT https://repo-staging.sagebase.org/repo/v1/{resource_type}/{rid}/acl
{"id":"1",
"etag":"0",
"resourceAccess":[
{"id":"1",
"groupName":"PUBLIC",
"accessType":["READ","CHANGE_PERMISSIONS","DELETE","UPDATE","CREATE"]
}
],
}
|
...
This deletes the given object's ACL, restoring its dependence on its owner's permissions.
| Code Block |
|---|
DELETE https://repo-staging.sagebase.org/repo/v1/{resource_type}/{rid}/acl
|
...
Note: The query is asked for the user who is implied by the session token, or 'anonymous' if there is no token.
| Code Block |
|---|
GET https://repo-staging.sagebase.org/repo/v1/{resource_type}/{rid}/access?accessType={accessType}
|
| Code Block |
|---|
{"result":true}
|
More Examples
Add a particular user with full access and identified individuals with read-only access to a project.
Get Request:
| Code Block |
|---|
curl -H sessionToken:XXXXXXXXXXXXXXXXXX -H Content-Type:application/json -k https://repo-staging.sagebase.org/repo/v1/project/498/acl
|
Get Response:
| Code Block |
|---|
{
"id":"3",
"creationDate":1308274656084,
"etag":"0",
"createdBy":"nicole.deflaux@sagebase.org",
"resourceAccess":[
{
"id":"4",
"groupName":"AUTHENTICATED_USERS",
"accessType":[
"DELETE",
"CHANGE_PERMISSIONS",
"UPDATE",
"READ",
"CREATE"
]
}
],
"modifiedBy":"nicole.deflaux@sagebase.org",
"modifiedOn":1308274656084,
"uri":"/repo/v1/project/498/acl"
} |
Update Request:
| Code Block |
|---|
curl -H sessionToken:XXXXXXXXX -H Content-Type:application/json -X PUT -d '{
"id":"3",
"creationDate":1308274656084,
"etag":"0",
"createdBy":"nicole.deflaux@sagebase.org",
"resourceAccess":[
{
"groupName":"AUTHENTICATED_USERS",
"accessType":[
"READ"
]
},
{
"groupName":"nicole.deflaux@sagebase.org",
"accessType":[
"DELETE",
"CHANGE_PERMISSIONS",
"UPDATE",
"READ",
"CREATE"
]
},
{
"groupName":"someuser@sagebase.org",
"accessType":[
"DELETE",
"CHANGE_PERMISSIONS",
"UPDATE",
"READ",
"CREATE"
]
}
],
"modifiedBy":"nicole.deflaux@sagebase.org",
"modifiedOn":1308274656084,
"uri":"/repo/v1/project/498/acl"
}' https://repo-staging.sagebase.org/repo/v1/project/498/acl
|
Update Response:
| Code Block |
|---|
{
"id":"3",
"creationDate":1308274656084,
"etag":"0",
"createdBy":"nicole.deflaux@sagebase.org",
"resourceAccess":[
{
"id":null,
"groupName":"someuser@sagebase.org",
"accessType":[
"DELETE",
"UPDATE",
"CHANGE_PERMISSIONS",
"READ",
"CREATE"
]
},
{
"id":null,
"groupName":"nicole.deflaux@sagebase.org",
"accessType":[
"DELETE",
"UPDATE",
"CHANGE_PERMISSIONS",
"READ",
"CREATE"
]
},
{
"id":null,
"groupName":"AUTHENTICATED_USERS",
"accessType":[
"READ"
]
}
],
"modifiedBy":"nicole.deflaux@sagebase.org",
"modifiedOn":1308274656084,
"uri":"/repo/v1/project/498/acl"
} |
API For Resource Access
The Synapse Authorization Services include support for creating abstract 'resources' and allowing users access. The defined requests are shown below. Note: All requests must be authenticated, as described earlier in this document.
Authorize a User for a Resource