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.

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.

Setup

In order 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

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

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

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 property. To use the Rhythm API, this value can be sent in the Authorization HTTP header with a value in the format:

Bearer access_token

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

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

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

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

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.