Page Comparison

...

Missing password or user ID already exists:

HTTP/1.1 400401 Bad RequestUnauthorized

Note:  As a side effect this will send an email to the given address, prompting the user to set their password.

...

POST https://auth-staging.sagebase.org/auth/v1/user/password/userPasswordEmailemail
{"email":"demouser@sagebase.org"}

...

If the email address is not in the user database:

HTTP/1.1 400404 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.

...

Not Found

Set Password

POST https://auth-staging.sagebase.org/auth/v1/user/apiPasswordEmailpassword
{"emailsessionToken":"demouser@sagebase.org"}abcdefgh-0123-4567-ijkl-mnopqrstuvwx", "password":"foobar"}

Successful Response:

HTTP/1.1 204 No Content

...

Get Secret Key for HMAC Authentication

GET https://auth-staging.sagebase.org/auth/v1/secretKey

Successful Response:

HTTP/1.1 400 Bad Request200 {"secretKey":"0Ocy/cW/3WIdZg3Up9dguO4Kh5smBKpN7iWXAvVQqekGD3gT4nc7PWwlfOhcL+KW6W4PjXtgPQNhiP7yrwjfwQ=="}

Note: The email template Session token 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

...

required in request header.  The returned key is that of the authenticated user.

Invalidate Secret Key

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

Successful Response:

HTTP/1.1 204  No Content

Note: Session token token or HMAC signature is required in request header.

...

  The key which is invalidated is that of the authenticated user.

Initiate Session (Login)

Request:

GETPOST https://auth-staging.sagebase.org/auth/v1/secretKey
session
{"email":"demouser@sagebase.org", "password":"demouser-pw"}

Successful Response:

HTTP/1.1 200 201 Created
Content-Type: application/json
{"secretKeysessionToken":"0Ocy/cW/3WIdZg3Up9dguO4Kh5smBKpN7iWXAvVQqekGD3gT4nc7PWwlfOhcL+KW6W4PjXtgPQNhiP7yrwjfwQ=="}

Note: Session token is required in request header.  The returned key is that of the user authenticated by the session token.

Invalidate Secret Key

DELETEAYcOhWIm9NdOC6BdzzzisQ00", "acceptsTermsOfUse":"true"}

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:

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

Successful Response:

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)

RequestError Response, if the session token is invalid:

POST https://auth-staging.sagebase.org/auth/v1/sessionHTTP/1.1 401 Unauthorized
{"emailreason":"demouser@sagebase.org", "password":"demouser-pwSession token is not valid"}

orError Response, if the user has not signed the terms of use yet:

POST https://auth-staging.sagebase.org/auth/v1/sessionHTTP/1.1 403 Forbidden
{"emailreason":"demouser@sagebase.org", "password":"demouser-pw", "acceptsTermsOfUse":"true"}

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: 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:

DELETE https://auth-staging.sagebase.org/auth/v1/session
Content-Type: application/json
{"reason":"Unable to authenticate."}

...

Note: Session token is required in request header.

Response:

HTTP/1.1 403204 ForbiddenNo 
<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:

PUT https://auth-staging.sagebase.org/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://auth-staging.sagebase.org/auth/v1/session

Note: Session token is required in request header.

Response:

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:

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.

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:

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:

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:

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:

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:

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

...

Content

Accept the Synapse Terms of Use

Request:

POST https://auth-staging.sagebase.org/auth/v1/termsOfUse
{"sessionToken":"AYcOhWIm9NdOC6BdzzzisQ00", "acceptsTermsOfUse":"true"}

Response:

HTTP/1.1 204 No Content

Note: The ToU are available at this URL:

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/password/userPasswordEmailemail

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

...

For requests that fail to be authenticated the response will include the headers:

WWW-Authenticate: authenticate Crowd"Digest" your email

and a plain text body:  "The token provided was invalid or expired."

...