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