| Wiki Markup | ||||||||||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
| Section | ||||||||||||||||||||||
|
API for Authentication and Authorization
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"}
{code}
Successful |
Successful Response:
...
| Code Block |
|---|
HTTP/1.1 201 Created
{code}
Missing password or user ID already exists:
{code} |
Missing password or user ID already exists:
| Code Block |
|---|
HTTP/1.1 400 Bad Request
{code}
Note: As a side effect this will send an email to the given address, prompting the user to set their password.
h3. 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.
{code} |
Note: As a side effect this will send an email to the given address, prompting the user to set their password.
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.
| Code Block |
|---|
GET https://auth-staging.sagebase.org/auth/v1/user
{ |
| Code Block |
|---|
{code} HTTP/1.1 200 OK Content-Type: application/json { "displayName": "Demo User", "email": "demouser@sagebase.org", "firstName": "demo", "lastName": "user", "password": null } {code} h3. Update User {code} |
Update User
| Code Block |
|---|
PUT https://auth-staging.sagebase.org/auth/v1/user
sessionToken:<sessionToken>
{"firstName":"demo", "lastName":"user", "displayName":"Demo User"}
{code}
where <sessionToken> is that returned by "Initiate |
where <sessionToken> is that returned by "Initiate Session",
...
below.
...
This
...
service
...
updates
...
the
...
user
...
who is authenticated by the session token.
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:
| Code Block |
|---|
HTTP/1.1 204 No Content
{code}
|
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."}
{code}
h3. Send |
Send Change-Password
...
...
| Code Block |
|---|
POST https://auth-staging.sagebase.org/auth/v1/userPasswordEmail
{"email":"demouser@sagebase.org"}
{code}
Successful |
Successful Response:
...
| Code Block |
|---|
HTTP/1.1 204 No Content
{code}
|
If
...
the
...
...
address
...
is
...
not
...
in
...
the
...
user
...
database:
...
| Code Block |
|---|
HTTP/1.1 400 Bad Request
{code}
|
Note:
...
The
...
...
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
...
...
| Code Block |
|---|
POST https://auth-staging.sagebase.org/auth/v1/apiPasswordEmail
{"email":"demouser@sagebase.org"}
{code}
Successful |
Successful Response:
...
| Code Block |
|---|
HTTP/1.1 204 No Content
{code}
|
If
...
the
...
...
address
...
is
...
not
...
in
...
the
...
user
...
database:
...
| Code Block |
|---|
HTTP/1.1 400 Bad Request
{code}
|
Note:
...
The
...
...
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"}
{code}
Successful |
Successful Response:
...
| Code Block |
|---|
HTTP/1.1 204 No Content
{code}
|
Note:
...
Session
...
token
...
is
...
required
...
in
...
request
...
header.
...
Create
...
Secret
...
Key
...
for
...
HMAC Authentication
| Code Block |
|---|
AuthenticationPOSTPOST https://auth-staging.sagebase.org/auth/v1/secretKey {"email":"demouser@sagebase.org"} |
Successful
...
Response:
| Code Block |
|---|
HTTP/1.1 201 {"secretKey":"0Ocy/cW/3WIdZg3Up9dguO4Kh5smBKpN7iWXAvVQqekGD3gT4nc7PWwlfOhcL+KW6W4PjXtgPQNhiP7yrwjfwQ=="} Note: Session token is required in request header. h3. Initiate Session (Login) Request: {code} |
Note: Session token is required in request header.
Initiate Session (Login)
Request:
| Code Block |
|---|
POST https://auth-staging.sagebase.org/auth/v1/session
{"email":"demouser@sagebase.org", "password":"demouser-pw"}
{code}
Successful |
Successful Response:
...
| Code Block |
|---|
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 Block |
|---|
HTTP/1.1 400 Bad Request
AuthenticationURL: https://auth-staging.sagebase.org/auth/v1/session
Content-Type: application/json
{"reason":"Unable to authenticate."}
{code}
Session token is valid for a period of time, currently set to 24 hours.
h3. Refresh Token (reset timer)
Request:
{code} |
Session token is valid for a period of time, currently set to 24 hours.
Refresh Token (reset timer)
Request:
| Code Block |
|---|
PUT https://auth-staging.sagebase.org/auth/v1/session
{"sessionToken":"AYcOhWIm9NdOC6BdzzzisQ00"}
{code}
Successful |
Successful Response:
...
| Code Block |
|---|
HTTP/1.1 204 No Content
{code}
|
Error
...
Response,
...
if
...
the
...
session
...
token
...
is
...
invalid:
...
| Code Block |
|---|
HTTP/1.1 404 Not Found
{"reason":"Unable to validate session."}
{code}
h3. Terminate 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:
| Code Block |
|---|
DELETE https://auth-staging.sagebase.org/auth/v1/session
{"sessionToken":"AYcOhWIm9NdOC6BdzzzisQ00"}
{code}
|
Response:
...
| Code Block |
|---|
HTTP/1.1 204 NO CONTENT
{code}
h2. Sample |
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://auth-staging.sagebase.org/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://auth-staging.sagebase.org/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://auth-staging.sagebase.org/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://auth-staging.sagebase.org/auth/v1/session
...
Refresh session token:
curl -k -H "Content-Type:application/json"
...
-H
...
"Accept:application/json"
...
-d
...
"
...
{\"sessionToken\":\"QYNoamrOKK0dBhjZOFfbAg00\"
...
}"
...
-X
...
PUT
...
https://auth-staging.sagebase.org/auth/v1/session
...
Logout:
curl -k -H "Content-Type:application/json"
...
-H
...
"Accept:application/json"
...
-d
...
"
...
{\"sessionToken\":\"QYNoamrOKK0dBhjZOFfbAg00\"}"
...
-X
...
DELETE
...
https://auth-staging.sagebase.org/auth/v1/session
...
Access repository services anonymously:
curl -H Accept:application/json
...
https://repo-staging.sagebase.org/repo/v1/dataset/test
...
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
...
Authentication of Requests to Platform
Authentication via Session Token
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.)
Authentication via Secret Key
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>
|
where <signature> is the HMAC-SHA1 hash created using the shared secret key generated above, and the hashed data is the concatenation:
userId + url + signatureTimestamp
Authentication Failure
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
Default groups
Currently, there are two default groups that can be used to set permissions:
Group Name | Description |
|---|---|
PUBLIC | All users belong to this group. This is the only group that the anonymous@sagebase.org user belongs to. The anonymous user is used for anyone that has not logged in to Synapse. Therefore, granting permission to PUBLIC will grant that permission to everyone including users that have not logged in. |
AUTHENTICATED_USERS | All users that have logged in will automatically belong to this group. Therefore, granting permissions to AUTHENTICATED_USERS will grant that permission to any user that has logged in to Synapse. |
Get the users who can be added to a resource's ACL
| Code Block |
|---|
GET https://repo-staging.sagebase.org/repo/v1/user
{code}
{code} |
| 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}
]
{codetrue}
]
h3. |
Get
...
the
...
groups
...
who
...
can
...
be
...
added
...
to
...
a
...
resource's
...
ACL
...
| Code Block |
|---|
GET https://repo-staging.sagebase.org/repo/v1/userGroup
{code}
{code} |
| 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}
]
{code}
|
Note:
...
The
...
"name"
...
fields
...
returned
...
from
...
/user
...
and
...
/userGroup
...
are
...
used
...
in
...
the
...
"groupName"
...
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,
...
'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}
{code}}/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
}
{code}
h3. 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.
{code} |
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.
| 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"]
}
]
}
{code
}
]
}
h3. |
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).
...
| 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"]
}
],
}
{code}
h3. Delete Access Control List for a Resource
This deletes the given object's ACL, restoring its dependence on its owner's permissions.
{code} |
Delete Access Control List for a Resource
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
{code}
h3. 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.
{code} |
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.
| Code Block |
|---|
GET https://repo-staging.sagebase.org/repo/v1/{resource_type}/{rid}/access?accessType={accessType}
{ |
| Code Block |
|---|
{code} {"result":true} {code} h1. More Examples h2. Add a particular user with full access and identified individuals with read-only access to a project. *Get Request:*{code} |
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
{code}
*Get |
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"
}{code}
*Update Request*:{code} |
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
{code}
*Update Response*:{code} |
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"
}{code} |