Healthx SAML Single Sign-On (Inbound)

Healthx supports the SAML standard for inbound SSOs. SAML is one of the most common standards for identity management at the web level. This document will not describe the SAML standard in depth. For that, we recommend you review some of the excellent documentation provided at or wikipedia.

OK, How does the Healthx SAML Implementation Work?

Security Assertion Markup Language (SAML) allows secure web domains to exchange identity information with one another. This means users can log in and authenticate at one website, and that website can vouch for that user to another website.

With SAML, your web application will act as the identity provider for a user. You'll authenticate that user, then pass an encoded SAML response identifying a user to Healthx, the service provider.

Three Phases to SAML Authentication with Healthx

  1. First, your application authenticates a user.
  2. Second, your application creates a SAML2.0 assertion and posts this assertion to a supplied Healthx URL.
  3. Finally, Healthx receives this assertion, validates it, and automatically logs the user in to the Healthx application.


Healthx works with highly sensitive health care data. For this reason, Healthx requires that all SAML-based HTML requests take place over secure HTTP (HTTPS).  The Healthx SAML implementation uses X.509 certificates to certify and sign requests. Healthx supports two signing modes. You can either sign the entire XML string or just the SAML Assertion portion of the XML. Once signed, post it to the supplied Healthx SSO URL in a field called "SAMLResponse." Healthx will verify that the SAML response came from you by validating against the public key you've previously supplied. 

An example of of such a post in a simple HTML form is below.

Sample HTTP Post

<body onload="javascript:document.forms[0].submit()">
<p><strong>Note:</strong> Since your browser does not support JavaScript, you must press the Resume button once to proceed.</p>
<form method="post" action="">
<input type="hidden" name="SAMLResponse" value="PFJlc3BvbnL1N1cHBvcnRnNlPg%3d%3d"/>
<noscript><input type="submit" value="Resume"/></noscript>

Sample Pre-signed XML

Below is some sample XML that would be signed and posted to Healthx in the SamlResponse field above.

<Response xmlns="urn:oasis:names:tc:SAML:2.0:protocol" Consent="urn:oasis:names:tc:SAML:2.0:consent:unspecified" Destination="" ID="R7ee2a902-ca91-40fc-a2c4-6e2fbf7f7ea4" IssueInstant="2013-06-24T15:58:59.944Z" Version="2.0">
  <Signature xmlns="">
      <CanonicalizationMethod Algorithm="" />
      <SignatureMethod Algorithm="" />
      <Reference URI="#R7ee2a902-ca91-40fc-a2c4-6e2fbf7f7ea4">
          <Transform Algorithm="" />
          <Transform Algorithm="" />
        <DigestMethod Algorithm="" />
          <X509IssuerName>CN=Healthx Test Certificate</X509IssuerName>
  <Assertion ID="_beab7252-16f2-42a7-9a6a-a89d0c996fe2" IssueInstant="2013-06-24T15:58:59.944Z" Version="2.0" xmlns="urn:oasis:names:tc:SAML:2.0:assertion">
      <NameID Format="urn:oasis:names:tc:SAML:2.0:nameid-format:persistent">7be3e9cf-6367-45cd-b9a3-d56752591694</NameID>
      <SubjectConfirmation Method="urn:oasis:names:tc:SAML:2.0:cm:bearer">
        <SubjectConfirmationData NotOnOrAfter="2013-06-24T16:03:59.944Z" Recipient="" />
    <Conditions NotBefore="2013-06-24T15:58:59.944Z" NotOnOrAfter="2013-06-24T16:03:59.944Z">
    <AuthnStatement AuthnInstant="2013-06-24T15:58:59.944Z">
      <Attribute Name="Version" NameFormat="urn:oasis:names:tc:SAML:2.0:attrname-format:basic" FriendlyName="Version">
      <Attribute Name="UserId" NameFormat="urn:oasis:names:tc:SAML:2.0:attrname-format:basic" FriendlyName="UserId">
      <Attribute Name="RelationshipCode" NameFormat="urn:oasis:names:tc:SAML:2.0:attrname-format:basic" FriendlyName="RelationshipCode">
      <Attribute Name="MemberLastName" NameFormat="urn:oasis:names:tc:SAML:2.0:attrname-format:basic" FriendlyName="MemberLastName">
      <Attribute Name="MemberFirstName" NameFormat="urn:oasis:names:tc:SAML:2.0:attrname-format:basic" FriendlyName="MemberFirstName">

You will sign the XML with your private key, then base64 and URL encode the XML string. You can see the signing process described in the markup in the Reference URI element:

  <Signature xmlns="">
      <CanonicalizationMethod Algorithm="" />
      <SignatureMethod Algorithm="" />
      <Reference URI="#R85423341-38ac-48e3-8b52-85dbfc1cb383">

This URI matches the Response ID:

<Response xmlns="urn:oasis:names:tc:SAML:2.0:protocol" Consent="urn:oasis:names:tc:SAML:2.0:consent:unspecified" Destination="" ID="R85423341-38ac-48e3-8b52-85dbfc1cb383" IssueInstant="2008-12-18T13:32:14.155Z" Version="2.0">

You can find the Signature specification defined at The SAML assertion follows this specification and represents the most critical portion of the SSO.

First, notice that the Assertion ID in our example begins with an underscore.

<Assertion ID="_3c81362e-6ce3-42ce-bf6a-873d58240845"

This is because the ID must be unique, but it must take the attributes of xml type NCName, which requires that the value begin with an underscore character. It is likely that w3c will publish an updated specification for an ID attribute at some point in the future, in which case the SAML specification will update in kind. See section 1.3.4 of the SAML 2.0 Specifications for more information about this ID type. [PDF]


The vendor may ask for our metadata. This can be downloaded from the Autologin service and is slightly different depending on the mode of the SSO (members, providers, or admins).


Healthx supports only SAML attribute encryption. We do not support assertion encryption. If you wish to use attribute encryption, you should encrypt with our public certificate, which is attached to this page.

Entity ID

The vendor may ask for our entity ID, if they didn't get it from our metadata. Our entity ID is:

Accepted Attributes

The series of attributes within the attribute element are the specific claims that you will use to identify the user to Healthx. Healthx currently accepts the following attributes:

Attributes for Member

    • Version (required) (must be "1")
    • RelationshipCode (required)
    • UserId (required) (this value must match the MemberID, SSN, or AltMemberID sent to Healthx in the eligibility file)
    • MemberGroupNumber
    • MemberLastName
    • MemberFirstName
    • MemberDateOfBirth (yyyymmdd)
    • UserEmailAddress
    • UserPhoneNumber
If the RelationshipCode is anything other than 18 (self), the following attributes are required:
    • UserLastName
    • UserFirstName
    • UserDateOfBirth (yyyymmdd)

Attributes for Non-member users (e.g. admins)

    • RemoteUser (required) (a persistent, unique ID for the user in any format you like)
    • Fingerprint
If Fingerprint is absent, or present but changed, the following attributes are looked at:
    • UserFirstName (required)
    • UserLastName (required)
    • UserEmailAddress
    • UserPhoneNumber
    • UserAddress1
    • UserAddress2
    • UserAddress3
    • UserAddressCity
    • UserAddressState
    • UserAddressZipCode
    • UserDateOfBirth (yyyymmdd)
    • UserGroupNumber
    • UserGender
    • AliasFirstName
    • AliasLastName

Attributes for Providers

    • remoteUser (required) (note the lower case 'r'. A persistent, unique ID for the user in any format you like)
    • Fingerprint
If Fingerprint is absent, or present but changed, the following attributes are looked at:
    • FirstName (required)
    • LastName (required)
    • Email
    • TIN (required)
    • OrgProviderID (optional, supports single value or multiple comma-separated values)
    • ProviderPhoneNumber
    • ProviderAddress1
    • ProviderAddress2
    • ProviderAddress3
    • ProviderAddressCity
    • ProviderAddressState
    • ProviderAddressZipCode

TIN Format for Providers

The TIN attribute should contain XML in the format shown in the following example. It should be wrapped in a CDATA tag so that the XML-specific characters do not need to be encoded. Any number of TINs and NPIs can be submitted in this way, and they will be stored as part of the user account. The values should be sent with every SSO request.

        <TIN ID="0123456789">
        <TIN ID="1234567890">

If you do not have any TIN or NPI values to send for a user, you may send an empty set with the following XML:


Optional attributes for any login type

    • ImitateUserId
      • If you choose to allow it, user imitation can be performed. This means that an admin user can log in using the credentials of another user and see the portal as the other user would see it. The value of this attribute should be the Healthx UserId of the admin user who will be logged as initiating the imitation session.
    • SignupKeycode
      • This optional attribute grants the user access to programs and services. The SSO configuration allows a default SignupKeycode to be specified, so that this attribute only needs to be used if some users will have different access requirements.
    • RedirectInfo
      • This parameter is used to send the user to any page other than the portal home page after they are logged in. An example of the format is shown below. The serviceid indicates the service that the user should be sent to. Any number of parameters may be specified and they will be sent along on the URL to the service.
      • See below, or the attached SAMLTemplate.xml file for proper formatting:
<saml:Attribute Name="RedirectInfo" NameFormat="urn:oasis:names:tc:SAML:2.0:attrname-format:basic" FriendlyName="RedirectInfo">
        <ServiceId xmlns="">REDIRECT SERVICEID GOES HERE</ServiceId>
        <SupportParams Name="PARAM1">PARAM1VALUE</SupportParams>
        <SupportParams Name="PARAM2">PARAM2VALUE</SupportParams>
    • DeepLinkInfo
      • This parameter is used to send the user to any page other than the portal home page after they are logged in. It is an alternate to RedirectInfo for those that can't use XML in SAML attributes. An example of the format is shown below. The serviceid indicates the service that the user should be sent to. Any number of parameters may be specified and they will be sent along on the URL to the service. You may also specify what hash will be used at the end of the URL.
<Attribute Name="DeepLinkInfo" NameFormat="urn:oasis:names:tc:SAML:2.0:attrname-format:basic" FriendlyName="DeepLinkInfo">

If no parameters will be sent, the value must still include ;params: at the end. But the has section can be omitted:

<Attribute Name="DeepLinkInfo" NameFormat="urn:oasis:names:tc:SAML:2.0:attrname-format:basic" FriendlyName="DeepLinkInfo">
    <AttributeValue>serviceid:REDIRECT SERVICEID GOES HERE;params:</AttributeValue>

Ready to begin? E-mail to get started on your SSO into Healthx.

Joel Klee,
Aug 16, 2016, 10:25 AM
Mike Rowe,
Mar 31, 2011, 10:22 AM
Jay German,
Sep 24, 2009, 8:26 AM
Alex Toumey,
May 15, 2018, 7:02 AM