OpenID Connect

Overview

OpenID Connect is an authentication flow built on top of the OAuth 2.0 protocol. It enables your application to verify the identity and obtain basic profile information about JazzHR users.

Discovery Metadata

The Discovery metadata for JazzHR's OpenID Connect implementation can be found at the Discovery endpoint.

Authorization Code Flow

Currently, JazzHR only supports the OpenID Connect Authorization Code flow.

Obtain an Authorization Code

Direct the user to https://api.jazz.co/oauth/authorize with the following URL encoded query string parameters:

• response_type=code- Enables the Authorization Code flow

• redirect_uri - Must be a redirect URI supplied to JazzHR during initial configuration

• client_id - An OAuth client ID provided by JazzHR during initial configuration

• scopes - A space-delimited set of scopes which determine the set of claims present in the OpenID Connect ID token

  • Currently supported OpenID Connect standard scopes: openid, profile, and email
  • Currently supported custom scopes: https://www.jazzhr.com/company (includes company_id, company_name, and company_rcid claims), https://www.jazzhr.com/partner (includes partner_owner_rcid claims), and https://www.jazzhr.com/user (includes user_account_id)

• state - An optional parameter useful for preventing CSRF attacks (see here for more information)

Example Authorization Request

https://api.jazz.co/oauth/authorize?response_type=code&scope=openid%20profile%20email&client_id=<your-client-id>&state=<some-unique-string>&redirect_uri=<your-redirect-uri>

If they are not already authenticated, the user is prompted to sign in to JazzHR. Upon being successfully authenticated, the user is redirected to your application’s redirect URI with the query parameters code and state appended. An example redirect would be https://<your-redirect-uri>?code=<authorization-code>&state=<some-unique-string>.

Your application should then lift the value of the code query parameter from the redirect URI to use in the next step of the process. This authorization code is a one-time use token that has a lifetime of 5 minutes. If the authorization code is not used to obtain an access token within 5 minutes, you must start the process over.

Obtain an ID Token

Now that your application has an authorization code, it can be exchanged for an OpenID Connect ID token. In order to authenticate to the token endpoint, you must use HTTP Basic authentication, where the user name is your OAuth client ID and the password is your OAuth client secret.

The request body of the token request should contain the following form-encoded parameters:

• grant_type=authorization_code- Enables the Authorization Code flow

• code - The authorization code returned from the authorization endpoint

• redirect_uri - Must be the same redirect URI included in the authorization request

Example Token Request

curl -X POST \
  https://<your-client-id>:<your-client-secret>@api.jazz.co/openId/accessToken \
  -H 'Content-Type: application/x-www-form-urlencoded' \
  -d 'grant_type=authorization_code&code=<authorization-code>&redirect_uri=<your-redirect-uri>'

If the request was made successfully, the response to the token request will include an OpenID Connect ID token that must be validated (see here for more information) before being used to authenticate the user with your application.

Note: an OAuth access token and refresh token will also be included in the token response; these can be safely ignored for the SSO use case

Example Token Response

{
    "token_type": "Bearer",
    "expires_in": 3600,
    "id_token": "<the OpenID Connect ID token>"
}