Single Sign-On (SSO) for the Wallet

Suggest Edits

Overview

Single Sign-On (SSO) allows users to access multiple related software applications with one set of login credentials. This document provides an overview of the SSO integration with the Axuall Wallet and the requirements for setting it up.

The SSO offering is designed as a way to allow clinicians to access their Wallet through another software. The second software will need to build a link that, when clicked, will send a SAML call and pass the following information and will open the Axuall workflow in a new tab in the browser.

  • First Name
  • Last Name
  • NPI (if no NPI, then NCSBN)
  • Provider Type
  • Email Address

Workflow

SSO is enabled through a SAML call. There are three workflows that a provider could experience through SSO. They include the following below:

User Communication

SSO may require some communication with users of your applications to understand what is going on. The following should be known:

  • No emails will be sent to the users that enter the platform via SSO; no invite emails or reminder emails will go out.
  • If a user fails validation of their account when entering last name, date of birth, and last four digits of their social security number, an error page will appear that prompts the user to reach out to Axuall’s support team to help resolve the issue.

Technical Details

SAML Setup

Clients will need to supply Axuall with the following information in the environments where they wish to use SSO:

  • SAMLP login URL
  • Sign-in certificate
  • X509 signing certificate in PEM format
  • Domain(s) of the web application that will initiate the SSO request
    • Axuall will use these to whitelist the domain(s).

Axuall will supply clients with the following information in the environments where they wish to use SSO:

  • Login URL
  • API client secret and key (For clients already using the Axuall API, you will use the same API credentials).

IdP Initiated Flow

For SSO into the clinician wallet, Axuall supports an IdP Initiated Flow. For each SSO attempt an unique URL must be generated by calling the SSO Initiation endpoint. This endpoint will provide an unique URL and set a cookie in order to mitigate CSRF attacks.

Our recommendation is to open the provided URL in a new tab as the Axuall website does not allow for use within an iFrame.

Data Requirements

Provider type values need to be in the following values:

  • NP
  • CRNA
  • MD
  • DO
  • PA
  • RN

First name, last name, NPI (if no NPI, NCSBN), and email address in addition to provider type, will need to be sent with every SAML call.

For new clinicians, the Initial Recipe for the provider type will be applied. To assign another recipe, such as a re-appointment recipe, the Assign Workflow endpoint should be used. Note: that for already engaged clinicians that have a recipe assigned when SSO is being set up for the organization, the recipe that is already assigned to them will remain assigned to them.

Sample SAML Response

In order to be able to map clinician users in the Axuall system, the SAML IdP will need to send the following identity claims as part of the SAML response:

Below is an example SAML response: 

<samlp:Response xmlns:samlp="urn:oasis:names:tc:SAML:2.0:protocol" ID="_220f84f56eed63077e47"  Version="2.0" IssueInstant="2023-02-23T20:30:23.108Z"  Destination="<https://manage.auth0.com/tester/samlp>">
  <saml:Issuer xmlns:saml="urn:oasis:names:tc:SAML:2.0:assertion">{{Issuer}}</saml:Issuer>
  <samlp:Status>
    <samlp:StatusCode Value="urn:oasis:names:tc:SAML:2.0:status:Success"/>
  </samlp:Status>
  <saml:Assertion xmlns:saml="urn:oasis:names:tc:SAML:2.0:assertion" Version="2.0" ID="_ltPgRJVMk6TXpzPv9FLlOGZdK6MWjMxv" IssueInstant="2023-02-23T20:30:23.051Z">
    <saml:Issuer>{{Issuer}}/saml:Issuer>
    <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/2001/04/xmldsig-more#rsa-sha256>"/>
        <Reference URI="#_ltPgRJVMk6TXpzPv9FLlOGZdK6MWjMxv">
          <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/2001/04/xmlenc#sha256>"/>
          <DigestValue>{{DigestValue}}</DigestValue>
        </Reference>
      </SignedInfo>
      <SignatureValue>{{SignatureValue}}</SignatureValue>
      <KeyInfo>
        <X509Data>
          <X509Certificate>{{X509Certificate}}</X509Certificate>
        </X509Data>
      </KeyInfo>
    </Signature>
    <saml:Subject>
      <saml:NameID Format="urn:oasis:names:tc:SAML:1.1:nameid-format:unspecified">{{User ID}}</saml:NameID>
      <saml:SubjectConfirmation Method="urn:oasis:names:tc:SAML:2.0:cm:bearer">
        <saml:SubjectConfirmationData NotOnOrAfter="2023-02-23T21:30:23.051Z" Recipient="<https://manage.auth0.com/tester/samlp>"/>
      </saml:SubjectConfirmation>
    </saml:Subject>
    <saml:Conditions NotBefore="2023-02-23T20:30:23.051Z" NotOnOrAfter="2023-02-23T21:30:23.051Z">
      <saml:AudienceRestriction>
        <saml:Audience>{{Audience}}</saml:Audience>
      </saml:AudienceRestriction>
    </saml:Conditions>
    <saml:AuthnStatement AuthnInstant="2023-02-23T20:30:23.051Z" SessionIndex="_POlMBSBHU8UOE9jmfAo_XfBgXRk3rkEN">
      <saml:AuthnContext>
        <saml:AuthnContextClassRef>urn:oasis:names:tc:SAML:2.0:ac:classes:unspecified</saml:AuthnContextClassRef>
      </saml:AuthnContext>
    </saml:AuthnStatement>
    <saml:AttributeStatement xmlns:xs="<http://www.w3.org/2001/XMLSchema>" xmlns:xsi="<http://www.w3.org/2001/XMLSchema-instance>">
      <saml:Attribute Name="<http://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddress>" NameFormat="urn:oasis:names:tc:SAML:2.0:attrname-format:uri">
        <saml:AttributeValue xsi:type="xs:string">{{Email}}</saml:AttributeValue>
      </saml:Attribute>
      <saml:Attribute Name="<http://schemas.xmlsoap.org/ws/2005/05/identity/claims/givenname>" NameFormat="urn:oasis:names:tc:SAML:2.0:attrname-format:uri">
        <saml:AttributeValue xsi:type="xs:string">{{First Name}}</saml:AttributeValue>
      </saml:Attribute>
      <saml:Attribute Name="<http://schemas.xmlsoap.org/ws/2005/05/identity/claims/surname>" NameFormat="urn:oasis:names:tc:SAML:2.0:attrname-format:uri">
        <saml:AttributeValue xsi:type="xs:string">{{Last Name}}</saml:AttributeValue>
      </saml:Attribute>
      <saml:Attribute Name="<http://schemas.xmlsoap.org/ws/2005/05/identity/claims/nscbn>" NameFormat="urn:oasis:names:tc:SAML:2.0:attrname-format:uri">
        <saml:AttributeValue xsi:type="xs:string">{{NSCBN}}</saml:AttributeValue>
      </saml:Attribute>
      <saml:Attribute Name="<http://schemas.xmlsoap.org/ws/2005/05/identity/claims/degree>" NameFormat="urn:oasis:names:tc:SAML:2.0:attrname-format:uri">
        <saml:AttributeValue xsi:type="xs:string">{{Degree}}</saml:AttributeValue>
      </saml:Attribute>
      <saml:Attribute Name="<http://schemas.xmlsoap.org/ws/2005/05/identity/claims/upn>" NameFormat="urn:oasis:names:tc:SAML:2.0:attrname-format:uri">
        <saml:AttributeValue xsi:type="xs:string">{{User ID}}</saml:AttributeValue>
      </saml:Attribute>
      </saml:Attribute>
    </saml:AttributeStatement>
  </saml:Assertion>
</samlp:Response>

Updated 3 months ago