# Single Sign-On Guide

Every tenant in Rhythm has an associated Auth0 tenant for member login. These Auth0 tenants have a unique domain,
usually in the format `tenant id`.us.auth0.com, which is subsequently referred to in this document as `auth0 domain`.

This guide assumes that you are conducting the Single Sign-On in a regular, server-side web app where you can securely
store a **client secret**, and will therefore use the Authorization Code Flow.

For more info on other flows see [authentication](/tutorials/authentication).

## Universal Login

Auth0 maintains the authentication state directly with the member’s browser. Once a user has authenticated, they can be redirected to the Rhythm Portal,
or any other site that uses the same Auth0 tenant, without being prompted for credentials.

SSO
The Rhythm Portal will always start by redirecting users to Auth0. Since
the user has already authenticated with Auth0, they are immediately redirected back to the Rhythm Portal.

## Setup

To prevent unauthorized authentication attempts, Auth0 will only work with pre-authorized URLs.

You will need to provide one or more of each of these URLs to Rhythm:

* URL where you want to receive the access token after a successful login (`redirect uri`)
* URL where you want users to be redirected after logout (`logout uri`)


Once this is done, Rhythm will supply you with the `auth0 domain`, `client id`, and `client secret` which is used in your
SSO redirects as defined below.

## Auth0 SDK

Auth0 publishes SDKs for several popular frameworks which you can use instead of manually executing the Authorization Code
flow. For a full list, see [https://auth0.com/docs/libraries](https://auth0.com/docs/libraries)

## Authentication

Start the Authorization Code flow by redirecting users to:

> https:// `auth0 domain`/authorize?response_type=code&client_id=`client id`&redirect_uri=`redirect uri`&scope=openid%20profile%20email&state=`state value you define`


Once a user is authenticated, they will be redirected back to the `redirect uri` with an `access code` in the query string.
This URL will look something like:

> `redirect uri`?code=`access code`&state=`state value you defined in the redirect`


At this point, you can verify the state value is valid for this authentication request. For more about using state values
to prevent CSRF attacks, see: [https://auth0.com/docs/protocols/oauth2/oauth-state](https://auth0.com/docs/protocols/oauth2/oauth-state)

## Getting an Access Token

You can now exchange the `access code` for an ID and Access token by executing a server-side **x-www-form-urlencoded** `POST`
of the `access code` to the endpoint at:

> https:// `auth0 domain`/oauth/token


as documented at [https://auth0.com/docs/api/authentication?http#authenticate-user](https://auth0.com/docs/api/authentication?http#authenticate-user)

You must supply the following parameters in the body of the POST:


```
grant_type=“authorization_code”
&client_id=[your client id]
&client_secret=[your client secret]
&code=[your access code]
&redirect_uri=[your redirect uri]
```

As a response, you will receive a JSON object including an `access_token` attribute.
To use the Rhythm API, this value can be sent in the `Authorization` HTTP header with a value in the format:

> "Authorization": "Bearer `access_token`"


This access token should never be used for more than one user and will automatically expire.

## Accessing the Contact ID

If you have not yet read about the differences between Users and Contacts, check out this section from the Quick Start first:
[Users vs. Contacts](/tutorials/concepts)

Since an **access token** is a Base64 encoded JSON Web Token (JWT), you can decode it to access information about the user.

Decoding a JWT
Most frameworks have a library to verify and decode a JWT such as:

* JavaScript: [https://www.npmjs.com/package/jsonwebtoken](https://www.npmjs.com/package/jsonwebtoken)
* .NET: [https://docs.microsoft.com/en-us/dotnet/api/system.identitymodel.tokens.jwt.jwtsecuritytokenhandler.readjwttoken?view=azure-dotnet](https://docs.microsoft.com/en-us/dotnet/api/system.identitymodel.tokens.jwt.jwtsecuritytokenhandler.readjwttoken?view=azure-dotnet)


Once decoded, the information in the JWT will include a number of fields (claims) including:


```json
{
 "http://rhythmsoftware.com/customer_id": "faa.org",
 "http://rhythmsoftware.com/tenant_id": "faa.org",
 "http://rhythmsoftware.com/contact_id": "HFIPWJ8y2s"
}
```

If the current user has never logged in to the Rhythm Portal, they will not yet have been linked to a Contact record and
the `http://rhythmsoftware.com/contact_id` claim will not be returned. In this case, the user should first be redirected to
the Rhythm Portal to complete the linking process.

## Logout

To log a user out, you can redirect them to:

> https:// `auth0 domain`/v2/logout?client_id=`client id`&returnTo=`logout uri`


Logging a user out will log them out for both your app and the Rhythm Portal then return the user to the pre-authorized
`logout url` you specified.