Skip to main content

Health Wallet SSO

To allow for a seamless integration between your UI and First Dollar’s UI, there needs to be an authentication integration between the two platforms. The end result of this integration is that a user, logged into your portal, can be redirected to their associated First Dollar dashboard without needing to log in again.

Terms​

SAML - XML-based authentication passing technique

Overview​

Enabling SSO requires the following steps:

  • From within your web application, your user requests a redirect to First Dollar's web application. The user must already be authenticated on your web application.
  • Your server generates and signs SAML XML.
  • The user is sent to https://api.firstdollar.com/v0/auth/saml with a form post containing the signed SAML XML in the post body.
  • First Dollar validates SAML signature (with a public key), and validates the userId from your system
  • User is logged in with a userId property from First Dollar, and is redirected to First Dollar's web application

This SSO integration also depends on a mapping from a globally unique user ID property to an associated First Dollar user ID.

For API based partners, you can store the id field that is returned from the createIndividual API endpoint to serve as this shared user ID property.

For file based partners, a mapping of a unique user ID in your system can be made to a First Dollar unique user ID as a part of the ingestion of your enrollment file.

Details​

Generate SAML Signing Key​

On a linux machine, run the following command:

openssl req -x509 -nodes -sha256 -days 3650 -newkey rsa:2048 -keyout
fd_saml_private_signing.key -out fd_saml_signing_certificate.crt

Move fd_saml_private_signing.key to a secure location.

Please attach fd_saml_signing_certificate.crt in an email and send it to developer-support@firstdollar.com. This allows us 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.

Generating the SAML XML​

As the Identity Provider, you must generate and sign a SAML Response XML. This unsigned XML should look like the following template:

<?xml version="1.0" encoding="UTF-8" standalone="no"?>
<saml2p:Response xmlns:saml2p="urn:oasis:names:tc:SAML:2.0:protocol"
   ID="{samlResponseId}" IssueInstant="{samlIssueInstant}"
   Version="2.0">
   <saml2:Issuer xmlns:saml2="urn:oasis:names:tc:SAML:2.0:assertion">
      {samlIssuerId}
   </saml2:Issuer>
   <saml2p:Status>
      <saml2p:StatusCode
         Value="urn:oasis:names:tc:SAML:2.0:status:Success"/>
   </saml2p:Status>
   <saml2:Assertion
      xmlns:saml2="urn:oasis:names:tc:SAML:2.0:assertion"
      ID="{samlAssertionId}" IssueInstant="{samlIssueInstant}"
      Version="2.0">
      <saml2:Issuer>{samlIssuerId}</saml2:Issuer>
      <saml2:Subject>
         <saml2:NameID>{samlUserId}</saml2:NameID>
         <saml2:SubjectConfirmation
            Method="urn:oasis:names:tc:SAML:2.0:cm:bearer">
            <saml2:SubjectConfirmationData
               NotOnOrAfter="{samlExpirationTimestamp}"/>
         </saml2:SubjectConfirmation>
      </saml2:Subject>
      <saml2:Conditions NotBefore="{samlBeginTimestamp}"
         NotOnOrAfter="{samlExpirationTimestamp}"/>
      <saml2:AuthnStatement AuthnInstant="{samlIssueInstant}">
         <saml2:AuthnContext>
            <saml2:AuthnContextClassRef>
               urn:oasis:names:tc:SAML:2.0:ac:classes:PreviousSession
            </saml2:AuthnContextClassRef>
         </saml2:AuthnContext>
      </saml2:AuthnStatement>
   </saml2:Assertion>
</saml2p:Response>

This template should be filled in with the following template variables, all properly XML escaped. Below are the variable names and an example value:

 // A unique uuid
 samlResponseId: '7a40ec03-5c75-45fe-9db7-9ef74f928e48'

 // A unique uuid
 samlAssertionId: 'c3f5bbbe-6fc3-47a5-aad5-e57160dee5bd'

 // The timestamp when this SAML XML was generated
 samlIssueInstant: '2022-01-27T15:04:42+0000'

 // URL of the service that issued this SAML XML
 samlIssuerId: 'https://participant.your-url.com/generateSaml'

 // The userId from your system of the user that we’d like to authenticate.
 samlUserId: ‘1234’

 // When this SAML token expires, we recommend {samlIssueInstant} + 5min
 samlExpirationTimestamp: '2022-01-27T15:09:42+0000'

 // When this SAML token starts being valid, we recommend {samlIssueInstant} - 10s
 samlBeginTimestamp: '2022-01-27T15:04:32+000'

Signing the SAML XML​

Once the SAML XML has been generated, it must be signed before sending it to First Dollar. Specifically, the <saml2:Assertion> block is signed.

We support http://www.w3.org/2001/04/xmldsig-more#rsa-sha256 as the signature algorithm, and http://www.w3.org/2001/10/xml-exc-c14n as the canonicalization algorithm. This will generate the following XML, which should be added as a child of the <saml:Response> entry.

<ds:SignedInfo>
   <ds:CanonicalizationMethod Algorithm="http://www.w3.org/2001/10/xml-exc-c14n#"/>
   <ds:SignatureMethod Algorithm="http://www.w3.org/2000/09/xmldsig#rsa-sha1"/>
   <ds:Reference URI=<!-- should reference the saml2:Assertion block –>>
   <ds:Transforms>
      <ds:Transform Algorithm="  http://www.w3.org/2000/09/xmldsig#enveloped-signature"/  >
      <ds:Transform Algorithm="  http://www.w3.org/2001/10/xml-exc-c14n#" />
   </ds:Transforms>
   <ds:DigestMethod Algorithm="  http://www.w3.org/2000/09/xmldsig#sha1" />
   <ds:DigestValue>
      <!-- generated by signing the saml:Assertion block -->
   </ds:DigestValue>
   </ds:Reference>
</ds:SignedInfo>
<ds:SignatureValue>
   <!-- generated by signing the saml:Assertion block -->
</ds:SignatureValue>
<ds:KeyInfo>
   <ds:X509Data>
      <ds:Signature xmlns:ds="http://www.w3.org/2000/09/xmldsig#">
         <ds:X509Certificate>
            <!-- contents of `fd_saml_signing_certificate.crt` generated above -->
         </ds:X509Certificate>
   </ds:X509Data>
</ds:KeyInfo>
</ds:Signature>

Note that most languages have libraries which handle XML signing / SAML out of the box.

Send the user to First Dollar​

After generating the signed SAML XML, send the user to https://api.firstdollar.com/v0/auth/saml with a form post containing the signed SAML XML in the post body.

First Dollar's server will take the SAML XML provided and verify it. It will run the following steps and return an error if any failures occur:

  • Validate the signature on the SAML XML
  • Validate the provided userId from your system maps to a valid First Dollar userId

Upon successful verification, First Dollar will redirect the user to our UI.

Once FD has verified that the SAML XML was signed appropriately and that First Dollar has a valid User for the given userId from your system, FD will generate a JWT token and redirect the user to a page which takes the newly generated JWT token. First Dollar also sets the appropriate cookies so that the User can access their First Dollar dashboard.