OpenID Connect SSO

This guide outlines how to set up OpenID Connect SSO with First Dollar. This implementation can enable SSO into First Dollar's Health Wallet application for end members and our Health Wallet Manager application for benefit administrators.

Use the 'Destination Application' parameter under Required Configuration Details to designate the target application during the SSO handshake.

Supported OIDC SSO Flows

First Dollar currently supports authenticating by leveraging the access or identity tokens from the OAuth2 "Authorization Code" grant flow.

SSO Via OIDC/OAuth2 Authorization Code Grant Flow

Below is an overview of the OIDC SSO handshake between the OIDC Provider, User, Partner Website, and First Dollar:

Required Configuration Details

Name	Description	Notes
Client ID	The ID of the OIDC OAuth2 client that First Dollar will be using to access the partner’s OIDC server.
Client Secret	The secret associated with the OAuth2 client.
Authorization Endpoint URL	This is the url of the authorization endpoint on the partner’s OIDC server where the OAuth2 Authorization Code Grant Flow is initiated from.
Token Endpoint URL	This is the url of the authorization endpoint on the partner’s OIDC server where the Authorization Code is exchanged for a token.
Issuer URL	This is the url of the token issuer. This must match the iss claim in tokens generated by the partner’s OIDC server.	Required only if Verification Entity Type is ACCESS_TOKEN or ID_TOKEN
User Identifier Claim Path	This is the name of the claim or path to the claim where the First Dollar UID will be located in the token issued by the partner’s OIDC server.	See additional details below in the User Identifier Claim section.
Verification Entity Type	This is where the user identifier claim can be found. Possible options are: ACCESS_TOKEN, ID_TOKEN, INTROSPECTION_ENDPOINT. If INTROSPECTION_ENDPOINT is specified, an Introspection Endpoint URL is required.
Introspection Endpoint	An introspection endpoint where a request with an access token in the Authorization header will return a json object containing the user identifier at the specified User Identifier Claim Path.	Required only if Verification Entity Type is INTROSPECTION_ENDPOINT
Destination Application	This is the name of the First Dollar application that the user will be sent to after sign on is complete. This may be one of the following: manager, consumer, widget	A separate configuration is required for each destination application. Note that manager refers to the Health Wallet Manager web application and consumer refers to the Health Wallet web application

User Identifier Claim

In order to match the user identified by an access or identity token provided by the partner to a user in the First Dollar system, it is required that the First Dollar’s UID for the user is included as a claim in the token or in the json response from the introspection endpoint. This UID will be returned to the partner at the time that a user is created in the First Dollar system.

Since this claim may be named differently by different partners, First Dollar requires the path of this claim in the token or JSON response from the introspection endpoint. If the user identifier is in a top-level claim then this should be the name of that claim. If the user identifier is in a nested claim this would be the full path of claim names. See examples below:

Top-Level Claim

{
  "topLevelClaim": "<user_identifier_value>"
}

In the above example the claim path would be merely topLevelClaim

Nested Claim

{
  "nested": {
    "claim": {
      "path": "<user_identifier_value>"
    }
  }
}

In the above example the claim path would be nested.claim.path

User Verification Entity Types

In order to access the User Identifier Claim outlined in the above section, First Dollar’s OIDC SSO system can be configured to look in the Access Token, Identity Token or by calling an Introspection Endpoint with the Access Token.

Access and Identity Tokens

When using access or identity tokens as the User Verification Entity, the First Dollar system will decode and verify the token. As such the issuer (iss claim) in the token must match the Issuer URL configuration parameter, otherwise token signature verification will fail. It is expected that whichever token is used as the User Verification Entity will contain the user identifier at the path specified via the User Identifier Claim Path described above.

Introspection Endpoint

When using an introspection endpoint as the User Verification Entity, the First Dollar system will make a call to the introspection endpoint with the access token in the Authorization header in the format defined in the OAuth2 specification (Bearer <access_token>). It is expected that a json response will be returned that contains the user identifier at the path specified via the User Identifier Claim Path described above.

Details to be provided to the Partner by First Dollar

SSO ID

This is the ID used to identify the SSO integration in the First Dollar system. It will be provided to the partner by First Dollar. It is used in both the SSO Initiation Endpoint and the OIDC Redirect Endpoint described below. Note that a separate SSO ID will be provided for each First Dollar Destination Application that SSO access is requested to as the SSO ID is bound to the Destination Application.

SSO Initiation Endpoint

This is the url that the partner will send users to in order to initiate SSO to First Dollar. It will be of the format:

https://api.firstdollar.com/v0/auth/oidc/init/:ssoId

ssoId is the SSO ID described in the section above. It is a unique identifier representing a partner's SSO integration.

OIDC Redirect Endpoint

This is the url that the partner will set as the redirect_uri for the OIDC OAuth2 client that will be used by First Dollar. The parameters are the same as that of the SSO Initiation Endpoint. It will be of the format:

https://api.firstdollar.com/v0/auth/oidc/redirect/:ssoId

ssoId is the SSO ID described in the section above. It is a unique identifier representing a partner's SSO integration.