Single Sign On

CirrusMD has various integration points depending on customer needs. We strive to ensure that our customers have all of the information and support they need for integrating with CirrusMD to meet the needs of each program.

Patient / Member Authentication

We currently support 2 authentication models each with options as it relates to member validation and eligibility.

SAML 2.0
JWT (requires use of CirrusMD mobile SDKs)
Oauth2.0 / OpenID

SAML 2.0

SAML 2.0 is our recommended approach to member authentication as it creates a seamless experience for the member as well as allowing our customers to manage access themselves without a lot of data integration work.

We currently support:

IdP initiated SSO – CirrusMD As Service Provider (SP) and Customer As Identity Provider (IdP)

Key URLs:

name	Method	URL	Parameters
Consumption URL	POST	`will be shared prior to testing`	SAMLResponse¹, RelayState²
Metadata URL	GET	`will be shared prior to testing`	None

¹ SAMLResponse (required) - is the base64 encoding of a <samlp:Response> element

² RelayState (optional) is often used to redirect users to a SP protected resource. in IdP initiated scenarios, fully qualified URLs are not exposed, so providing a care-channel identifier as the RelayState value will allow users to be redirected to the appropriate care channel after a successful SSO request.

Required Configuration Parameters: (IdP to provide these to CirrusMD)

name	type	provided by	value or [description]
SP EntityId	String	SP	CirrusMD
IdP Entity Id	String	IdP	[Idp Entity Id]
Sign In URL	String	IdP	[Redirect Location if user visits SP is not logged in]
Sign Out URL	String	IdP	[Redirect Location when user logs out of SP]
Certificate	String	IdP	[X.509 Public Certificate]

Supported Response Types

SAML Response with Signed Message

Required Attributes

name	type	description [format or validation]
dateOfBirth	ISO8601	Patient Date of Birth [‘YYYY-MM-DD’]
emailAddress	String	Patient Email (must ALSO be globally unique)
externalUserId	String	Globally unique Identifier
firstName	String	Patient First Name
lastName	String	Patient Last Name
memberId	String	Program Member Identifier
sex	String	Patient sex [‘m’, ‘f’]

Example Attribute Statement for Required Attributes

<saml:AttributeStatement xmlns:xs='http://www.w3.org/2001/XMLSchema'>
  <saml:Attribute Name='dateOfBirth' NameFormat='urn:oasis:names:tc:SAML:2.0:attrname-format:basic'>
    <saml:AttributeValue xsi:type='xs:string' xmlns:xsi='http://www.w3.org/2001/XMLSchema-instance'>1976-01-12</saml:AttributeValue>
  </saml:Attribute>
  <saml:Attribute Name='externalUserId' NameFormat='urn:oasis:names:tc:SAML:2.0:attrname-format:basic'>
    <saml:AttributeValue xsi:type='xs:string' xmlns:xsi='http://www.w3.org/2001/XMLSchema-instance'>GLOBALUNIQUEID</saml:AttributeValue>
  </saml:Attribute>
  <saml:Attribute Name='emailAddress' NameFormat='urn:oasis:names:tc:SAML:2.0:attrname-format:basic'>
    <saml:AttributeValue xsi:type='xs:string' xmlns:xsi='http://www.w3.org/2001/XMLSchema-instance'>email@domain.dom</saml:AttributeValue>
  </saml:Attribute>
  <saml:Attribute Name='firstName' NameFormat='urn:oasis:names:tc:SAML:2.0:attrname-format:basic'>
    <saml:AttributeValue xsi:type='xs:string' xmlns:xsi='http://www.w3.org/2001/XMLSchema-instance'>James</saml:AttributeValue>
  </saml:Attribute>
  <saml:Attribute Name='lastName' NameFormat='urn:oasis:names:tc:SAML:2.0:attrname-format:basic'>
    <saml:AttributeValue xsi:type='xs:string' xmlns:xsi='http://www.w3.org/2001/XMLSchema-instance'>Smythe</saml:AttributeValue>
  </saml:Attribute>
  <saml:Attribute Name='memberId' NameFormat='urn:oasis:names:tc:SAML:2.0:attrname-format:basic'>
    <saml:AttributeValue xsi:type='xs:string' xmlns:xsi='http://www.w3.org/2001/XMLSchema-instance'>1234567</saml:AttributeValue>
  </saml:Attribute>
  <saml:Attribute Name='sex' NameFormat='urn:oasis:names:tc:SAML:2.0:attrname-format:basic'>
    <saml:AttributeValue xsi:type='xs:string' xmlns:xsi='http://www.w3.org/2001/XMLSchema-instance'>m</saml:AttributeValue>
	</saml:Attribute>
</saml:AttributeStatement>

Optional Attributes

name	type	description [format or validation]
allergies	String	Patient Allergies
history	String	Patient Medical History
medications	String	Patient Medications
phoneNumber	String	Patient Phone [NANP 10 digit]
zipCode	String	Patient ZIP code
welcomeMessage	String	See SSO Patient Origin Intro section
regionKeys	[String]	An array of strings to grant access to plans

Example Attribute Statement inclusive of optional Attributes

<saml:AttributeStatement xmlns:xs='http://www.w3.org/2001/XMLSchema'>
  <saml:Attribute Name='allergies' NameFormat='urn:oasis:names:tc:SAML:2.0:attrname-format:basic'>
    <saml:AttributeValue xsi:type='xs:string' xmlns:xsi='http://www.w3.org/2001/XMLSchema-instance'>Latex, Bees</saml:AttributeValue>
  </saml:Attribute>
  <saml:Attribute Name='dateOfBirth' NameFormat='urn:oasis:names:tc:SAML:2.0:attrname-format:basic'>
    <saml:AttributeValue xsi:type='xs:string' xmlns:xsi='http://www.w3.org/2001/XMLSchema-instance'>1976-01-12</saml:AttributeValue>
  </saml:Attribute>
  <saml:Attribute Name='externalUserId' NameFormat='urn:oasis:names:tc:SAML:2.0:attrname-format:basic'>
    <saml:AttributeValue xsi:type='xs:string' xmlns:xsi='http://www.w3.org/2001/XMLSchema-instance'>GLOBALUNIQUEID</saml:AttributeValue>
  </saml:Attribute>
  <saml:Attribute Name='emailAddress' NameFormat='urn:oasis:names:tc:SAML:2.0:attrname-format:basic'>
    <saml:AttributeValue xsi:type='xs:string' xmlns:xsi='http://www.w3.org/2001/XMLSchema-instance'>email@domain.dom</saml:AttributeValue>
  </saml:Attribute>
  <saml:Attribute Name='history' NameFormat='urn:oasis:names:tc:SAML:2.0:attrname-format:basic'>
    <saml:AttributeValue xsi:type='xs:string' xmlns:xsi='http://www.w3.org/2001/XMLSchema-instance'>High Blood Pressure, chronic fatigue</saml:AttributeValue>
  </saml:Attribute>
  <saml:Attribute Name='firstName' NameFormat='urn:oasis:names:tc:SAML:2.0:attrname-format:basic'>
    <saml:AttributeValue xsi:type='xs:string' xmlns:xsi='http://www.w3.org/2001/XMLSchema-instance'>James</saml:AttributeValue>
  </saml:Attribute>
  <saml:Attribute Name='lastName' NameFormat='urn:oasis:names:tc:SAML:2.0:attrname-format:basic'>
    <saml:AttributeValue xsi:type='xs:string' xmlns:xsi='http://www.w3.org/2001/XMLSchema-instance'>Smythe</saml:AttributeValue>
  </saml:Attribute>
  <saml:Attribute Name='medications' NameFormat='urn:oasis:names:tc:SAML:2.0:attrname-format:basic'>
    <saml:AttributeValue xsi:type='xs:string' xmlns:xsi='http://www.w3.org/2001/XMLSchema-instance'>daily ibuprofen</saml:AttributeValue>
  </saml:Attribute>
  <saml:Attribute Name='memberId' NameFormat='urn:oasis:names:tc:SAML:2.0:attrname-format:basic'>
    <saml:AttributeValue xsi:type='xs:string' xmlns:xsi='http://www.w3.org/2001/XMLSchema-instance'>1234567</saml:AttributeValue>
  </saml:Attribute>
  <saml:Attribute Name='sex' NameFormat='urn:oasis:names:tc:SAML:2.0:attrname-format:basic'>
    <saml:AttributeValue xsi:type='xs:string' xmlns:xsi='http://www.w3.org/2001/XMLSchema-instance'>m</saml:AttributeValue>
	</saml:Attribute>
  <saml:Attribute Name='zipCode' NameFormat='urn:oasis:names:tc:SAML:2.0:attrname-format:basic'>
    <saml:AttributeValue xsi:type='xs:string' xmlns:xsi='http://www.w3.org/2001/XMLSchema-instance'>802103456</saml:AttributeValue>
  </saml:Attribute>
  <saml:Attribute Name='welcomeMessage' NameFormat='urn:oasis:names:tc:SAML:2.0:attrname-format:uri' FriendlyName='welcomeMessage'>
    <saml:AttributeValue><![CDATA[Welcome]]></saml:AttributeValue>
  </saml:Attribute>
  <saml:Attribute Name='regionKeys' NameFormat='urn:oasis:names:tc:SAML:2.0:attrname-format:uri' FriendlyName='regionKeys'>
    <saml:AttributeValue>CO</saml:AttributeValue>
    <saml:AttributeValue>NY</saml:AttributeValue>
  </saml:Attribute>
</saml:AttributeStatement>

SAML 2.0 Metadata Encryption and Signing (optional)

In addition to the standard SAML 2.0 integration, We offer an enhanced security feature that allows the encryption of the SAML payload. This feature must be configured by an account manager before use. When configured, the metadata endpoint response will include a certificate to use for encrypting the SAML payload.

Example Metadata Encryption Response

<EncryptionMetadata xmlns='urn:oasis:names:tc:SAML:2.0:metadata'>
  <KeyInfo>
    <X509Data>
      <X509Certificate>
        <!-- X.509 Certificate for Encryption -->
      </X509Certificate>
    </X509Data>
  </KeyInfo>
</EncryptionMetadata>

Encrypted SAML Payload Example

Once you have obtained the encryption certificate, you can use it to encrypt the SAML payload. A request should be made to fetch a new certificate before each SSO attempt. Below is an example of an encrypted SAML assertion:

<EncryptedAssertion xmlns='urn:oasis:names:tc:SAML:2.0:assertion'>
  <EncryptedData xmlns='http://www.w3.org/2001/04/xmlenc#' Id='ED' Type='http://www.w3.org/2001/04/xmlenc#Element'>
    <EncryptionMethod Algorithm='http://www.w3.org/2001/04/xmlenc#aes256-cbc'/>
    <ds:KeyInfo xmlns:ds='http://www.w3.org/2000/09/xmldsig#'>
      <EncryptedKey xmlns='http://www.w3.org/2001/04/xmlenc#' Id='EK'>
        <EncryptionMethod Algorithm='http://www.w3.org/2001/04/xmlenc#rsa-oaep-mgf1p'/>
        <ds:KeyInfo xmlns:ds='http://www.w3.org/2000/09/xmldsig#'>
          <ds:X509Data>
            <ds:X509Certificate>
              <!-- X.509 Certificate for Encryption -->
            </ds:X509Certificate>
          </ds:X509Data>
        </ds:KeyInfo>
        <CipherData>
          <CipherValue>
            <!-- Encrypted Key Cipher Value -->
          </CipherValue>
        </CipherData>
        <ReferenceList>
          <DataReference URI='#ED'/>
        </ReferenceList>
      </EncryptedKey>
    </ds:KeyInfo>
    <CipherData>
      <CipherValue>
        <!-- Encrypted SAML Payload Cipher Value -->
      </CipherValue>
    </CipherData>
  </EncryptedData>
</EncryptedAssertion>

OAuth 2.0 / OpenID

OAuth 2.0 can be supported if required. However, we recommend SAML 2.0 as this standard is becoming more and more common in the enterprise healthcare space. If you would like to implement OAuth 2.0 or OpenID a requirements session discussing grant types and meta-data specifications will be necessary.

OAuth 2.0 / OpenID

SSO Patient Origin Intro

This feature allows customers to add a message to the start of a patient’s chat. To use this feature you will need to talk with the product team to configure an encounter_origin for you. encounter_origins have 3 fields a title, body, and label that are predefined when created.

Note on encounter_origins:

body maximum length is 200 characters
title maximum length is 30 characters
label maximum length is 30 characters

This works exactly like our SSO implementation but will be enabled by adding a few extra parameters.

Extra Parameters for SSO Patient Origin Intro

name	type	description [format or validation]	Required
RelayState	String	Points to a plan and encounter_origin	true

The RelayState is a URL-encoded parameter formatted according to the following scheme:

(URL-decoded) "<external_plan_id>?origin=<encounter_origin_label>"

Adding the RelayState parameter will result with the following card in plans chat

A welcomeMessage attribute can be added to the SAML payload and if it is present it will replace the predefined body text of the encounter_origins configuration.

  <Attribute Name='welcomeMessage' NameFormat='urn:oasis:names:tc:SAML:2.0:attrname-format:uri' FriendlyName='welcomeMessage'>
      <AttributeValue><![CDATA[My custom message]]></AttributeValue>
    </Attribute>
  </AttributeStatement>

Note on welcomeMessage attribute:

We currently do not offer any formatting or styling options.
The maximum length is 200 characters if you go over this limit we will truncate any characters past 200.

Region Keys

The regionKeys attribute is an array of strings that corresponds to a customer’s SSO configuration region_map. This attribute is used to automatically enroll patients into all plans that match the keys in the array.

The regionKeys attribute can be defined using the following XML code:

<saml:Attribute Name='regionKeys' NameFormat='urn:oasis:names:tc:SAML:2.0:attrname-format:uri' FriendlyName='regionKeys'>
  <saml:AttributeValue>CO</saml:AttributeValue>
  <saml:AttributeValue>NY</saml:AttributeValue>
</saml:Attribute>

Note on regionKeys attribute:

Access to plans that the patient has previously had access to does not expire.

CirrusMD API Documentation

Repository for GiHub Pages hosted Developer Documentation

Single Sign On

Patient / Member Authentication

SAML 2.0

SAML 2.0 Metadata Encryption and Signing (optional)

Example Metadata Encryption Response

Encrypted SAML Payload Example

OAuth 2.0 / OpenID

OAuth 2.0 / OpenID

SSO Patient Origin Intro

Region Keys