Healthx supports the SAML2 standard for inbound SSOs. SAML2 is one of the most common standards for identity management at the web level. This document will not describe the SAML2 standard in depth. For that, we recommend you review some of the excellent documentation provided at http://saml.xml.org/saml-specifications 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 SAML2 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 SAML2 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 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="http://www.healthx.com/endpoint-url" ID="R7ee2a902-ca91-40fc-a2c4-6e2fbf7f7ea4" IssueInstant="2013-06-24T15:58:59.944Z" Version="2.0">

  <Signature xmlns="http://www.w3.org/2000/09/xmldsig#">

    <SignedInfo>

      <CanonicalizationMethod Algorithm="http://www.w3.org/2001/10/xml-exc-c14n#" />

      <SignatureMethod Algorithm="http://www.w3.org/2000/09/xmldsig#rsa-sha1" />

      <Reference URI="#R7ee2a902-ca91-40fc-a2c4-6e2fbf7f7ea4">

        <Transforms>

          <Transform Algorithm="http://www.w3.org/2000/09/xmldsig#enveloped-signature" />

          <Transform Algorithm="http://www.w3.org/2001/10/xml-exc-c14n#" />

        </Transforms>

        <DigestMethod Algorithm="http://www.w3.org/2000/09/xmldsig#sha1" />

        <DigestValue>PwtybRpvQ9YVa+v0OdE9BIpElDs=</DigestValue>

      </Reference>

    </SignedInfo>

    <SignatureValue>CysphYlBiRUxAq0JgxaTXLqleDfgctZTfqLHpg1x1fR9fhbGeYaLII+aYL16UxGhxHV+o1sg2J00SpGKHJMCm9mAY+FPrVZDhkgagP+Mzdxjm1MoIH5FzyK/JhWJRKJHBQbRUz/QaObAHBaBTTuRme3XN4zxJlwh4t3SSL1krRM=</SignatureValue>

    <KeyInfo>

      <X509Data>

        <X509IssuerSerial>

          <X509IssuerName>CN=Healthx Test Certificate</X509IssuerName>

          <X509SerialNumber>5999782545553227370133761051242316812</X509SerialNumber>

        </X509IssuerSerial>

          <X509Certificate>MIICIzCCAYygAwIBAgIQBIOEHj1/rqpDRSz0L3zEDDANBgkqhkiG9w0BAQQFADAjMSEwHwYDVQQDExhIZWFsdGh4IFRlc3QgQ2VydGlmaWNhdGUwHhcNMDgxMDMxMTQ0MTIzWhcNMzkxMjMxMjM1OTU5WjAjMSEwHwYDVQQDExhIZWFsdGh4IFRlc3QgQ2VydGlmaWNhdGUwgZ8wDQYJKoZIhvcNAQEBBQADgY0AMIGJAoGBAKY6KxFC7auRwFb2IvX1B4YsUkbYpDuhy2RspV6v4YJfAXXmTC/522OLKJVp6mHrPRjmM6OKN3E0W2byNlGTcYX82HHfbX7XIVyjtD2wptIYKu8YOE0NLY3CTrOLDxKyfCSKYLT1Gyw1Vp6k66RcBQJm2t0mWA8AysuRnSwKkOzRAgMBAAGjWDBWMFQGA1UdAQRNMEuAEGa3Qv4isCfWXIckonY7bUyhJTAjMSEwHwYDVQQDExhIZWFsdGh4IFRlc3QgQ2VydGlmaWNhdGWCEASDhB49f66qQ0Us9C98xAwwDQYJKoZIhvcNAQEEBQADgYEARiaBwwyZaSN3AY6foY2klLSQQazDEm3+hh3h09O+VGm2TBoh+LQahRyLtiNhWJBvTHJzH+Gd0TCQyQfvB7TM2xZaLLCINgOCcQCBAO8cbNitFzBI8csamaZ6SSys1pAipGNuDh8+ZIObvPohNEkpg2MRxq9E1bgZkKmcEwkKJ0w=</X509Certificate>

      </X509Data>

    </KeyInfo>

  </Signature>

  <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">

    <Issuer>https://dev.healthx.com/idp</Issuer>

    <Subject>

      <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="http://www.healthx.com/" />

      </SubjectConfirmation>

    </Subject>

    <Conditions NotBefore="2013-06-24T15:58:59.944Z" NotOnOrAfter="2013-06-24T16:03:59.944Z">

      <AudienceRestriction>

        <Audience>https://secure.healthx.com/PublicService/SSO/AutoLogin.aspx</Audience>

      </AudienceRestriction>

    </Conditions>

    <AuthnStatement AuthnInstant="2013-06-24T15:58:59.944Z">

      <AuthnContext>

        <AuthnContextClassRef>urn:oasis:names:tc:SAML:2.0:ac:classes:Password</AuthnContextClassRef>

      </AuthnContext>

    </AuthnStatement>

    <AttributeStatement>

      <Attribute Name="Version" NameFormat="urn:oasis:names:tc:SAML:2.0:attrname-format:basic" FriendlyName="Version">

        <AttributeValue>1</AttributeValue>

      </Attribute>

      <Attribute Name="UserId" NameFormat="urn:oasis:names:tc:SAML:2.0:attrname-format:basic" FriendlyName="UserId">

        <AttributeValue>12345</AttributeValue>

      </Attribute>

      <Attribute Name="RelationshipCode" NameFormat="urn:oasis:names:tc:SAML:2.0:attrname-format:basic" FriendlyName="RelationshipCode">

        <AttributeValue>18</AttributeValue>

      </Attribute>

      <Attribute Name="MemberLastName" NameFormat="urn:oasis:names:tc:SAML:2.0:attrname-format:basic" FriendlyName="MemberLastName">

        <AttributeValue>Smith</AttributeValue>

      </Attribute>

      <Attribute Name="MemberFirstName" NameFormat="urn:oasis:names:tc:SAML:2.0:attrname-format:basic" FriendlyName="MemberFirstName">

        <AttributeValue>John</AttributeValue>

      </Attribute>

    </AttributeStatement>

  </Assertion>

</Response>


Attributes corresponding to user details will be updated on each autologin, except where fingerprint is in play.  If fingerprint is used, a non-matching fingerprint will cause the autologin service to skip the update of attributes sent.  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

If the RelationshipCode is anything other than 18 (self), the following attributes are required:

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

Fingerprint is an optional value, defined/generated by you, to optionally control whether we process the rest of the values and update the account accordingly. If Fingerprint is absent, or present but changed, the following attributes will be looked at and the account, if it exists already, will be updated with any new values:

• UserFirstName (required)
• UserLastName (required)
• UserEmailAddress
• UserPhoneNumber
• UserAddress1
• UserAddress2
• UserAddress3
• UserAddressCity
• UserAddressState
• UserAddressZipCode
• UserDateOfBirth (yyyymmdd)
• UserGroupNumber
• UserGender
• AliasFirstName
• AliasLastName

Attributes for Providers

Fingerprint is an optional value, defined/generated by you, to optionally control whether we process the rest of the values and update the account accordingly. If Fingerprint is absent, or present but changed, the following attributes will be looked at and the account, if it exists already, will be updated with any new values:

TIN Format for Providers

The TIN attribute should contain XML in one of the formats shown below. It should be wrapped in a CDATA tag if you wish to send the XML unencoded. 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.

<![CDATA[

    <Provider>

        <TIN ID="0123456789">

            <NPI>0123</NPI>

            <NPI>4567</NPI>

        </TIN>

        <TIN ID="1234567890">

            <NPI>1234</NPI>

        </TIN>

    </Provider>

]]>




&lt;Provider&gt;

    &lt;TIN ID="0123456789"&gt;

        &lt;NPI&gt;0123&lt;/NPI&gt;

        &lt;NPI&gt;4567&lt;/NPI&gt;

    &lt;/TIN&gt;

    &lt;TIN ID="1234567890"&gt;

        &lt;NPI&gt;1234&lt;/NPI&gt;

    &lt;/TIN&gt;

&lt;/Provider&gt;

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:

<![CDATA[

    <Provider/>

]]>

Optional attributes for any login type

<saml:Attribute Name="RedirectInfo" NameFormat="urn:oasis:names:tc:SAML:2.0:attrname-format:basic" FriendlyName="RedirectInfo">

    <saml:AttributeValue>

        <ServiceId xmlns="">REDIRECT SERVICEID GOES HERE</ServiceId>

        <SupportParams Name="PARAM1">PARAM1VALUE</SupportParams>

        <SupportParams Name="PARAM2">PARAM2VALUE</SupportParams>

    </saml:AttributeValue>

</saml:Attribute>

• 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">
    <AttributeValue>serviceid:REDIRECT SERVICEID GOES HERE;params:PARAM1=PARAM1VALUE&PARAM2=PARAM2VALUE;HASHPARAM1=HASHVALUE1&HASHPARAM2=HASHVALUE2

</AttributeValue>
</Attribute>




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>
</Attribute>

The IdP Single Sign-On Service builds a SAML assertion representing the user's logon security context. Since a POST binding is going to be used, the assertion is digitally signed and then placed within a SAML message. The message is then placed within an HTML FORM as a hidden form control named SAMLResponse. If the IdP received a RelayState value from the SP, it must return it unmodified to the SP in a hidden form control named RelayState. The Single Sign-On Service sends the HTML form back to the browser in the HTTP response. For ease of use purposes, the HTML FORM typically will be accompanied by script code that will automatically post the form to the destination site.




<form method="post" action="https://sp.example.com/SAML2/SSO/POST" ...>  

<input type="hidden" name="SAMLResponse" value="response" />  

<input type="hidden" name="RelayState" value="token" />  ...  

<input type="submit" value="Submit" />

</form>

Colon (:) GUID Semi-colon (;) Colon (:)

:4968A0EC-1CDD-4AEF-971C-F2CA98366080;:

The default audience value for Healthx is https://secure.healthx.com/PublicService/SSO/AutoLogin.aspx. For instances where the customer is setting up multiple inbound SSOs and requires an alternative to the default audience value, one of the following values may also be used:

• https://secure.healthx.com/provider
• https://secure.healthx.com/admin
• https://secure.healthx.com/employer
• https://secure.healthx.com/member
• https://secure.healthx.com