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

{% code overflow="wrap" %}

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

{% endcode %}

```
US Infrastructure: 
https://use1.prod.api.synap.ac/external-auth/jwt/authenticate
```

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

{% hint style="info" %}
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. 
{% endhint %}

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

<pre><code>{
  "eaid": YOUR_PORTAL_EAID, // ask your Synap account manager for this
  "exp": 1691610066066, // optional
  "email": "john.doe@synap.ac", 
  "name": "John Doe",
  "subPortal": "abc123" // optional
<strong>}
</strong></code></pre>

| 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.&#x20;

{% hint style="info" %}
Do NOT base64 encode your secret key when constructing the verification signature
{% endhint %}

## 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.&#x20;

## Developing & Helpful Libraries

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

* [Auth0](https://auth0.com/) - 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](https://jwt.io/libraries) - Has an extensive list of JWT signing and verification libraries in a range of popular programming languages and platforms.