All Collections
Clinical Site
Quick Links
Single Sign-On Setup
Single Sign-On Setup

An overview covering how SSO works in Clinician Nexus and how to set it up

Peter J Anderson avatar
Written by Peter J Anderson
Updated over a week ago

After reading this article you will be able to...

  • Configure SSO

  • Troubleshoot SSO

  • Understand SAML Workflow

  • FAQs

Configure SSO

If your organization is using an IDP that supports SAML2, like Active Directory and many others:

  • Use the form on the organization security settings in the SSO section. This is only available if your organization has the SSO feature enabled in your subscription:

  • The IDP needs to be configured to send first name, last name, and email

  • Tip: Once this is configured, you can try logging in from a different browser (or have somebody else try to log in who’s already been invited as staff at the organization). The Clinician Nexus login page will ask them for their email and then determine their organization is configured for SSO and send them to their organization’s IDP.

Troubleshooting SSO

  • If there is an error about AssertionConsumerServiceURL not being on the list of accepted URLs. This means that the organization needs to add its "https://app.cliniciannexus.com/saml2/<provider>/Acs" URL to its list of accepted URLs.

    • To decode a SAMLRequest query string:

    • Visit to Clinician Nexus’ login page

    • Enter an email with the organization’s email domain

    • Click next

    • Copy the SAMLRequest query string value (not including the RelayState querystring value)

    • Use a tool to uri decode, utf8 decode, and inflate the value to see the XML (like this SAML decoder tool).

    • Then confirm the value for the AssertionConsumerServiceURL is the ACS URL that is in the error message

  • The solution is similar for ADFS as it is with Azure Active Directory. AAD configures it in their "Authentication" section for the service provider. ADFS configures it as SAML Assertion Consumer Endpoint in ADFS.

  • If the organization receives a 400 error when the user returns to the app:

    • The organization may need to map email to "NameID", so the SAMLResponse has the email in the "<Subject>" node. (see https://stackoverflow.com/questions/30487171/adfs-does-not-pass-nameid/30491426)

    • There might be an error with the claims mapping. Clinician Nexus requires a claim for email, first, and last name

    • If you’re sure the claims mappings is correct, you can send ClinicianNexus customer success team an example SAMLResponse (in the POST that the IDP sends to our /Acs endpoint)

  • If the user receives an error about permissions.

    • Check to ensure the user is added to the correct group in Azure.

SAML Workflow

There are 5 requests that happen during a successful SAML workflow (these requests can be inspected via the devtools network tab if necessary):

  • <clinciannexus>/api/account/externallogin?provider=<provider>

    • Sets a cookie named SAML., configured like: path=/; secure; samesite=none; httponly

  • <idp>?SAMLRequest=...&RelayState=...

    • IDP UI is shown, so the user can log in if necessary...

  • <idp>/signin

    • Includes _authnRequest value in the request body

  • <clinciannexus>.../Acs

    • Sets a cookie named Identity.External, configured like

    • Unsets the SAML. cookie - includes SAMLResponse from IDP in request body

  • <clinciannexus>/account/externallogin

    • Sets authentication cookie and unsets the Identity.External cookie

SSO Configuration Directions

FAQs

How does SSO work for our end users?

Once configured, end users will be able to log in to Clinician Nexus using the same login credentials required by their organization. The end user would navigate to the Clinician Nexus login page, enter their email address then be directed to a login page hosted by the organization. The user can then enter the organization’s login credentials to be logged into Clinician Nexus.

Do users have to be added to Clinician Nexus first before they can log in via SSO?

Yes, users must be added to Clinician Nexus before the user can log in via SSO.

How are permissions within Clinician Nexus managed?

User permissions and roles are managed exclusively in the Clinician Nexus application. To make a permission change administrators can do that by logging into Clinician Nexus and updating the staff roles or permissions.

If a user forgets their password, how can they recover it?

If a user forgets their password the password will need to be recovered or reset using the organization’s login page. Clinician Nexus cannot help recover passwords for users who log in via SSO.

What if an email or name changes?

Three fields are used for SSO: first name, last name, and email address. If an email address changes for a user then the email needs to be manually updated in Clinician Nexus. If an email address changes for a user then there might be multiple accounts created for that user which the customer support team can resolve.

Have more questions? Please reach out by clicking the chat icon in the bottom right corner of your screen from 8am-6pm CT, Mon-Fri.


​

Did this answer your question?