...

Column

width	50%

On This page

Table of Contents

...

width	5%

Column

width	45%

On Related Pages

Page Tree

root	PLFM:@parent
startDepth	3

API for Authentication and Authorization

API for Authentication

Create User

Code Block

Wiki Markup

{section}
{column:width=50%}
On This page
{toc}
{column}
{column:width=5%}
{column}
{column:width=45%}
On Related Pages
{pagetree:root=@parent|startDepth=3}
{column}
{section}

h1. API for Authentication and Authorization

h2. API for Authentication


h3. Create User
{code}
POST https://auth-staging.sagebase.org/auth/v1/user
{"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

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

{code}


Note:&nbsp; 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.&nbsp; Note:&nbsp; the "password" field will be null, since retrieving a user's password is not permitted.


{code}
GET https://auth-staging.sagebase.org/auth/v1/user

Code Block

{code}

{code}
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
{code} h3. Update User {code} PUT https://auth-staging.sagebase.org/auth/v1/user sessionToken:<sessionToken> {"firstName":"demo", "lastName":"user", "displayName":"Demo User"}

...


{code}

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

...

&nbsp; This service updates the user

...

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

 who is&nbsp;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}
HTTP/1.1 204 No Content
{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 https://auth-staging.sagebase.org/auth/v1/userPasswordEmail
{"email":"demouser@sagebase.org"}

...

{code}


Successful Response:

...


{code

}
HTTP/1.1 204 No Content
{code}

If the email address is not in the user database:

...


{code

}
HTTP/1.1 400 Bad Request
{code}


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.

...



h3. Send Set-API-Password Email

...


{code

}
POST https://auth-staging.sagebase.org/auth/v1/apiPasswordEmail
{"email":"demouser@sagebase.org"}
{code}


Successful Response:

...


{code

}
HTTP/1.1 204 No Content
{code}

If the email address is not in the user database:

...


{code

}
HTTP/1.1 400 Bad Request

{code}



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.

...



h3. Set

...

Code Block


POST Password
{code}
POST https://auth-staging.sagebase.org/auth/v1/userPassword
{"email":"demouser@sagebase.org", "password":"foobar"}
{code}


Successful Response:
{code}
HTTP/1.1 204 No Content
{code}




Note:&nbsp; Session token is required in request header.

h3. Create Secret Key for HMAC AuthenticationPOST https://auth-staging.sagebase.org/auth/v1/userPasswordsecretKey
{"email":"demouser@sagebase.org", "password":"foobar"}

Successful Response:

Code Block
} Successful Response:HTTP/1.1 201 No Content

Note: Session token is required in request header.

Request:

Code Block

 {"secretKey":"0Ocy/cW/3WIdZg3Up9dguO4Kh5smBKpN7iWXAvVQqekGD3gT4nc7PWwlfOhcL+KW6W4PjXtgPQNhiP7yrwjfwQ=="} 
 
 
 

Note:&nbsp; Session token is required in request header.

h3. Initiate Session (Login)

Request:

{code}
POST https://auth-staging.sagebase.org/auth/v1/session
{"email":"demouser@sagebase.org", "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: 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

}
PUT https://auth-staging.sagebase.org/auth/v1/session
{"sessionToken":"AYcOhWIm9NdOC6BdzzzisQ00"}

...

{code}


Successful Response:

...


{code

}
HTTP/1.1 204 No Content
{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)

...

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



&nbsp;Note: Sessions initiated by multiple clients for the same user around the same time will receive identical "single sign on" tokens.&nbsp; 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.&nbsp; An alternative is for the client simply to delete its own copy of the token.

Request:

{code}
DELETE https://auth-staging.sagebase.org/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 "\{\"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:

...

]













































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

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

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

]\\




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

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

h3. Get the users who can be added to a resource's ACL
{code}
GET https://repo-staging.sagebase.org/repo/v1/user

Code Block

{code}
{code}
[
  {"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":truetrue}
]
{code}
]

h3. Get the groups who can be added to a resource's ACL

...


{code

}
GET https://repo-staging.sagebase.org/repo/v1/userGroup

Code Block

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

...



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

}
GET https://repo-staging.sagebase.org/repo/v1/{resource_type}/{rid}/acl

Code Block

acl
{code}

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

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

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

}
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 https://repo-staging.sagebase.org/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.

Code Block


{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}
GET https://repo-staging.sagebase.org/repo/v1/{resource_type}/{rid}/access?accessType={accessType}

Code Block

{code}

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

}
{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}
curl -H sessionToken:XXXXXXXXXXXXXXXXXX -H Content-Type:application/json -k  https://repo-staging.sagebase.org/repo/v1/project/498/acl

...

{code}

*Get Response:

...

*{code

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

{code}


*Update Request*:{code}
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

{code}

*Update Response*:{code}
{
   "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}

Versions Compared

Old Version 83

New Version 84

Key

API for Authentication and Authorization

API for Authentication

Create User

Get User

Update User

Authentication of Requests to Platform

API for Authorization

Default groups

Get the users who can be added to a resource's ACL

Create Access Control List for a Resource

Ask whether there is access to a Resource

More Examples

Add a particular user with full access and identified individuals with read-only access to a project.

Page Comparison

Versions Compared

Old Version 83

New Version 84

Key

API for Authentication and Authorization

API for Authentication

Create User

Get User

Update User

Initiate Session (Login)

Authentication of Requests to Platform

API for Authorization

Default groups

Get the users who can be added to a resource's ACL

Create Access Control List for a Resource

Ask whether there is access to a Resource

More Examples

Add a particular user with full access and identified individuals with read-only access to a project.