JSON Web Tokens (JWT)

How it Works

First, a user will be prompted to sign in to your external site. Once authenticated, your application will construct a JWT and redirect the user back to Synap using the token as a query string parameter. Synap then deconstructs the JWT and will either find the user and sign them in, or if they are a new user, it will create an account and then sign them in.

Authentication Endpoint

The Synap JWT authentication endpoint is shown below. Please replace YOUR_JWT_TOKEN with a constructed JWT following the format specified later in this document.

You can also provide return_to and/or error_url parameters, as detailed in the table below, if desired.

https://api.synap.ac/external-auth/jwt/authenticate/?jwt=YOUR_JWT_TOKEN

Key	Value	Designation
jwt	An encoded JSON Web Token	REQUIRED
return_to	A URL-encoded URL string that the user should be redirected to after successful authentication. If not specified, the user will be redirected to their default home page on Synap	OPTIONAL
error_url	A URL-encoded URL string that the user should be redirected to if authentication fails. The URL will be appended with an sso_error query param containing a human-readable error message. If not specified, the user will be redirected to the Synap /login page	OPTIONAL

Constructing a JWT

In order to construct a JWT, you will need a Secret Key - in the future, this will be available on your Admin Settings page, but for now please contact your Synap Account Manager to obtain this key.

Once you have obtained your Secret Key you must store it securely. Do not expose it in your client-side code, and we would strongly advise against checking it into your source control.

Please use the following data to construct your header. This specifies the HS256 algorithm.

{
  "alg": "HS256", 
  "typ": "JWT" 
}

Your JWT payload should look like this (replace all values, or remove optional fields as appropriate). Please find detailed descriptions of the fields in the table below

{
  "eaid": YOUR_PORTAL_EAID, // ask your Synap account manager for this
  "exp": 1691610066066, // optional
  "email": "[e-mail]", 
  "name": "John Doe",
  "subPortal": "abc123" // optional
}

Key	Value	Designation
eaid	This is an internal ID used by Synap to identify your SSO integration. It will be the same for every JWT you construct - please ask your account manager for a copy of it	REQUIRED
exp	A unix timestamp indicating the token's expiry date. This is recommended, but not required. We would advise setting an expiry date of ~14 days but you may wish to set a shorter or longer time depending on your internal security and data protection policies	RECOMMENDED
email	The email address of the user to log in	REQUIRED
name	The full name (e.g. Firstname Lastname) of the user being logged in.	REQUIRED
subPortal	If you make use of Synap Subportals, this field can be used to specify the ID of a subportal to log that user into. If you are not using Subportals then please omit this field entirely	OPTIONAL

Finally, your Verification Signature should be constructed as follows:

HMACSHA256(
  base64UrlEncode(header) + "." +
  base64UrlEncode(payload),
  YOUR_SECRET_KEY
)

Replace YOUR_SECRET_KEY with the Secret Key provided by your account manager.

Do NOT base64 encode your secret key when constructing the verification signature

Testing & Debugging

There is a great website for constructing and testing JWTs available at https://jwt.io/ - it can be helpful for quick testing and debugging.

Developing & Helpful Libraries

You may be interested in the following libraries to assist with constructing JWTs:

• Auth0 - An 'Authentication as a Service' platform that you can use to set up and manage your authentication process. It provides JWT as a login option, as well as native Auth0 login and SAML.

• This page - Has an extensive list of JWT signing and verification libraries in a range of popular programming languages and platforms.