...
| Code Block |
|---|
POST https://auth-staging.sagebase.org/auth/v1/userPasswordEmailuser/password/email {"email":"demouser@sagebase.org"} |
...
| Code Block |
|---|
HTTP/1.1 404 Not Found
|
...
...
Set
...
Password
...
| Code Block |
|---|
POST https://auth-staging.sagebase.org/auth/v1/apiPasswordEmailuser/password {"email"sessionToken":"abcdefgh-0123-4567-ijkl-mnopqrstuvwx", "password":"demouser@sagebase.orgfoobar"} |
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 404 Not Found
|
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 |
Get Secret Key for HMAC Authentication
| Code Block |
|---|
GET https://auth-staging.sagebase.org/auth/v1/userPassword {"email":"demouser@sagebase.org", "password":"foobar"} |
...
secretKey
|
Successful Response:
| Code Block |
|---|
HTTP/1.1 204 No Content 200 {"secretKey":"0Ocy/cW/3WIdZg3Up9dguO4Kh5smBKpN7iWXAvVQqekGD3gT4nc7PWwlfOhcL+KW6W4PjXtgPQNhiP7yrwjfwQ=="} |
Note: Session token or HMAC signature is required in request header. The returned key is that of the authenticated user.
...
Invalidate Secret Key
...
| Code Block |
|---|
GETDELETE https://auth-staging.sagebase.org/auth/v1/secretKey |
Successful Response:
| Code Block |
|---|
HTTP/1.1 204 No 200 {"secretKey":"0Ocy/cW/3WIdZg3Up9dguO4Kh5smBKpN7iWXAvVQqekGD3gT4nc7PWwlfOhcL+KW6W4PjXtgPQNhiP7yrwjfwQ=="} |
...
Content
|
Note: Session token or HMAC signature is required in request header. The returned key which is invalidated is that of the authenticated user.
...
Initiate Session (Login)
Request:
| Code Block |
|---|
DELETEPOST https://auth-staging.sagebase.org/auth/v1/secretKey session {"email":"demouser@sagebase.org", "password":"demouser-pw"} |
Successful Response:
| Code Block |
|---|
HTTP/1.1 204201 Created No Content |
Note: Session token or HMAC signature is required in request header. The key which is invalidated is that of the authenticated user.
Initiate Session (Login)
Request:
| Code Block |
|---|
POST https://auth-staging.sagebase.org/auth/v1/session {"email":"demouser@sagebase.orgContent-Type: application/json {"sessionToken":"AYcOhWIm9NdOC6BdzzzisQ00", "passwordacceptsTermsOfUse":"demouser-pwtrue"} |
or
...
Note: If the "acceptsTermsOfUse" field is "false", then an additional call to accept the Synapse terms of use is required before the session token can be used for authenticated requests
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 {"emailsessionToken":"demouser@sagebase.orgAYcOhWIm9NdOC6BdzzzisQ00", "password":"demouser-pw", "acceptsTermsOfUse":"true"} |
...
}
|
Successful Response:
| Code Block |
|---|
HTTP/1.1 201204 CreatedNo Content-Type: application/json {"displayName":"Demo User","sessionToken":"AYcOhWIm9NdOC6BdzzzisQ00"} |
Error Response, if the user authentication details are incorrectsession token is invalid:
| Code Block |
|---|
HTTP/1.1 401 Unauthorized
AuthenticationURL: https://auth-staging.sagebase.org/auth/v1/session
Content-Type: application/json
{"reason":"Invalid username or password"}
|
...
{"reason":"Session token is not valid"}
|
Error Response, if the Terms of Use are not either accepted explicitly in the request or accepted by the user previouslyuser has not signed the terms of use yet:
| Code Block |
|---|
HTTP/1.1 403 Forbidden
<html xmlns:v="urn:schemas-microsoft-com:vml"
xmlns:o="urn:schemas-microsoft-com:office:office"
xmlns:w="urn:schemas-microsoft-com:office:word"
xmlns:m="http://schemas.microsoft.com/office/2004/12/omml"
xmlns:mv="http://macVmlSchemaUri" xmlns="http://www.w3.org/TR/REC-html40">
<head>
<meta name=Title content="Synapse Terms and Conditions of Use">
<meta name=Keywords content="">
...
</html>
|
ie. the text of the terms of use is included in the response.
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"}
|
Successful Response:
| Code Block |
|---|
HTTP/1.1 204 No Content
|
Error Response, if the session token is invalid:
| Code Block |
|---|
HTTP/1.1 401 Unauthorized
{"reason":"Session token is not valid"}
|
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
|
Note: Session token is required in request header.
Response:
| Code Block |
|---|
HTTP/1.1 204 NO CONTENT
|
Authentication via OpenID
Synapse supports authentication via OpenID. Specifically there is a service which performs the OpenID handshake and, upon success, logs the user into Synapse and returns a Synapse session token. If it is the first time that the user has logged in to Synapse, then after successful OpenID authentication a new user account is created, a session is created and the session token is returned. The basic request is:
| Code Block |
|---|
POST https://www.synapse.org/Portal/openid?OPEN_ID_PROVIDER=<ProviderName>&RETURN_TO_URL=<RedirectURL>
|
<ProviderName> is the name of a supported OpenID provider. At this time the only allowed value is GOOGLE and this value will be used in the remaining examples.
Synapse supports the GET method, as required by applications which redirect requests to this service.
| Code Block |
|---|
GET https://www.synapse.org/Portal/openid?OPEN_ID_PROVIDER=GOOGLE&RETURN_TO_URL=<RedirectURL>
|
The successful response is a redirect to <RedirectURL> with extra request parameters to hold (1) an authentication status indicator (OK) and (2) the session token:
| Code Block |
|---|
HTTP/1.1 302 Moved Temporarily
...
Location: <RedirectURL>?status=OK&sessionToken=<sessionToken>
...
|
If successful, but if the user has not yet accepted the Synapse Terms of Use (ToU), then the result is:
| Code Block |
|---|
HTTP/1.1 302 Moved Temporarily
...
Location: <RedirectURL>?status=TermsOfUseAcceptanceRequired
...
|
In this case, authentication must be repeated with explict ToU acceptance. The client should display the ToU and request the user's acceptance. The ToU are available at this URL:
| Code Block |
|---|
https://auth-prod.sagebase.org/auth/v1/termsOfUse.html
|
Once the user has accepted the ToU, the authentication request may repeated, including a new request parameter acceptsTermsOfUse=true:
| Code Block |
|---|
POST https://www.sagebase.org/Portal/openid?OPEN_ID_PROVIDER=GOOGLE&acceptsTermsOfUse=true&RETURN_TO_URL=<RedirectURL>
|
If authentication is unsuccessful for a reason other than a missing terms of use agreement then the result is:
| Code Block |
|---|
HTTP/1.1 302 Moved Temporarily
...
Location: <RedirectURL>?status=OpenIDError
...
|
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
...
{"reason":"Terms of use must be signed"} |
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
|
Note: Session token is required in request header.
Response:
| Code Block |
|---|
HTTP/1.1 204 No Content
|
Accept the Synapse Terms of Use
Request:
| Code Block |
|---|
POST https://auth-staging.sagebase.org/auth/v1/termsOfUse
{"sessionToken":"AYcOhWIm9NdOC6BdzzzisQ00", "acceptsTermsOfUse":"true"} |
Response:
| Code Block |
|---|
HTTP/1.1 204 No Content |
Note: The ToU are available at this URL:
| Code Block |
|---|
https://auth-prod.sagebase.org/auth/v1/termsOfUse.html
|
Authentication via OpenID
Synapse supports authentication via OpenID with Google as the identity provider. You as a client initiate the users identity verification with Google, and pass through the URL parameters to our REST api which will unpack the openID parameters, and verify the account. If login is successful a Session object will be returned. See the Synapse Authentication REST API documentation for details.
Sample commands, issued from cURL:
Create User:
curl -k -H "Content-Type:application/json" -H "Accept:application/json" -d "{\"email\":\"demouser@sagebase.org\", \"firstName\":\"NEWdemodemo\", \"lastName\":\"NEWuseruser\", \"displayName\":\"NEWDemo Demo User\"}" -X PUT POST 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/user/userPasswordEmailpassword/email
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
...