Skip to main content

SAML Health Wallet Manager SSO

Overview​

This section outlines the authentication flow for partners that wish to implement SSO authentication into First Dollar's benefits administration portal, Health Wallet Manager.

This allows you to use your existing identity provider (IdP) to authenticate users in Health Wallet Manager. The IdP can be any SAML 2.0 compliant provider, such as Okta, Google Workspace, or Azure AD.

Azure AD SSO

As illustrated in the above diagram, this can be achieved by leveraging Azure Active Directory to generate a SAML Response after Azure Active Directory receives an AuthnRequest from a partner's own administrative portal. This AuthnRequest should match the configured values for the First Dollar SSO application in Azure AD as follows:

  • Identifier (Entity ID) should match the Issuer value
  • Reply URL should match the AssertionConsumerServiceURL value

Below is a sample AuthnRequest based off of the Azure AD documentation:

<samlp:AuthnRequest
    xmlns="urn:oasis:names:tc:SAML:2.0:metadata"
    ID="id6c1c178c166d486687be4aaf5e482730"
    Version="2.0" IssueInstant="2023-07-14T03:28:54.1839884Z"
    xmlns:samlp="urn:oasis:names:tc:SAML:2.0:protocol"
    AssertionConsumerServiceURL="https://api.firstdollar.com/v0/auth/saml" >
    <Issuer xmlns="urn:oasis:names:tc:SAML:2.0:assertion">https://api.firstdollar.com/v0/auth/saml</Issuer>
</samlp:AuthnRequest>

The attributes in the request that should be changed in the AuthnRequest on a per request basis are as follows:

ID - A unique identifier. Note that it cannot start with a number. Common practice is to use a uuid with id or _ prepended

IssueInstant - current UTC time in format YYYY-MM-DDThh:mm:ss.sssssssZ

Additional Azure AD Configuration Required​

First Dollar requires that the SAML response must be signed. This can be configured in your Azure AD settings for First Dollar SSO. We support SHA 256 as the signature algorithm, and Exclusive XML Canonicalization as the canonicalization algorithm.

Please export the public certificate and send it to developer-support@firstdollar.com as part of implementation. This allows us to use it to validate the signed SAML XML requests you send to us. This file is not private so it's okay to send as a plain attachment via email.

For additional documentation on configuring SAML based SSO with Azure Active Directory, please see Microsoft's published Azure Active Directory Overview.