, Provides REST APIs for managing and obtaining the necessary credentials to access Synapse. ,

, ,

, Authentication to Synapse services requires an access token passed in the HTTP Authorization header, as per the ,,HTTP bearer authorization,, standard. The access token incorporates a set of 'scopes' and the documentation for each service requiring authorization lists the scopes which the access token must include in order to use that service. ,

, ,

, Synapse currently supports four modes of obtaining an access token: ,

, ,

, ,
• ,Present username and password,
, ,
• ,Authentication via a whitelisted OAuth 2.0 provider,
, ,
• ,Authentication via a registered OAuth 2.0 client,
, ,
• ,Exchange an access token for Personal Access Token,
, ,

, ,

, The username and password are exchanged for an access token using ,,POST /login2,, service. This method should only be used by Synapse itself. No other application should prompt a user for their user name and password. ,

, ,

, Synapse allows authentication via a white listed OAuth 2.0 provider. Currently only Google is supported. The final step is ,,POST /oauth2/session2,, which returns an access token which is included as a Bearer token in the Authorization header of subsequent requests as described above. Only Synapse itself may use this service, as redirection back from the OAuth2 provider is only allowed to the Synapse web portal. ,

, ,

, A registered OAuth 2.0 client can use the ,,OAuth 2.0 services,, to authenticate, the final step of which is a request to the token endpoint: ,,POST /oauth2/token,, The returned access token is included as a Bearer token in the Authorization header of subsequent requests as described above. ,

, ,

, A user may freely generate up to 100 Personal access tokens (PATs) with scoped access using ,,POST /personalAccessToken,,. Unlike OAuth access tokens, ,

, ,
• ,PATs can be freely generated by a user alone and are not linked to any third party OAuth client and,
, ,
• ,While ATs have a strict 24 hour lifetime, PATs are long lived, and will only expire if unused for 180 consecutive days,
, ,

, For these reasons, it is critical to treat PATs as sensitive credentials, like passwords. If a user creates more than 100 tokens, then the least-recently used token(s) will be deleted until the user has no more than 100 tokens. ,

, ,

, The returned personal access token is included as a Bearer token in the Authorization header of subsequent requests as described above. ,

The OpenID Connect (OIDC) services implement OAuth 2.0 with the OpenID identity extensions.

, APIs to manage two factor authentication (2FA) in Synapse. ,<,/p ,

, Synapse currently supports using authenticator applications that can generate a ,,TOTP,, that is used as a second factor. ,

, ,

, To enable 2FA two requests are involved:

,

, ,
1. ,,POST /2fa/enroll,,: Generates a shared secret that is added to the user authenticator application,
, ,
2. ,,POST /2fa,,: Enables a specific secret generated by 1. to be used as second factor,
, ,

, ,

,

,

, In order to login through 2FA an additional request needs to be performed after the user attempts to authenticate (e.g. through the ,,POST /login2,, API). If the user has 2FA enabled, they will receive a 401 and the body of the response will contain a twoFaToken that can be used in the ,,POST /2fa/token,, API to obtain an access token. ,

,

,

, The user can additionally generate a set of recovery codes using the ,,POST /2fa/recoveryCodes,, API. The codes are one time use and can be used in place of a TOTP code when performing 2FA authentication. The body of the ,,POST /2fa/token,, request should specify as otpType RECOVERY_CODE and the value of the otpCode should match one of the generated codes. ,

, The ,, Data Repository Service,, API provides access to data objects in single, standard way regardless of where they are stored and how they are managed. The data objects for which information can be fetched are ,,FileEntity,, and ,,Dataset,,.The data object that is downloaded is a file. ,

, ,

, The supported end points for DRS are: ,

, ,
• ,, GET /service-info,,
, ,
• ,, GET /objects/{object_id},,
, ,

, ,

, ,

, Use the ,, GET /service-info ,, API to get information about GA4GH-compliant web services, including DRS services, to be aggregated into registries and made available via a standard API. ,

, Use the ,, GET /objects/{object_id} ,, API to get information about individual DRS objects. ,