Note
The PainChek App does not support a pop up window for SSO Authentication
At a high level, the following outlines the flow of actions
To avoid PainChek double handling the configuration, it is recommended that the client should create the IdP application on their end first, and provide us with the relevant values.
PainChek SSO does not recognise NameID - many IdPs will have a NameID claim configured by default and unchangeable. Even if it happens to be an email address, the client must still configure an “Email” claim.
Azure Specific note
Azure populates the “Namespace” attribute of the claims. This needs to be removed (leave blank) - otherwise PainChek will not recognise a claim and will return an error message similar to:
Missing ‘XYZ’ Claim from response.
Claims refer to the data sent from the IdP to PainChek. PainChek SSO supports receiving the following data claims:
|
Attribute (Claim ID) |
Description |
Validation |
Mandatory |
|---|---|---|---|
|
|
The email address of the user |
Must be a valid email address |
Yes |
|
FirstName |
The first name of the user |
Must be populated |
Yes |
|
LastName |
The last name of the user |
Must be populated |
Yes |
|
JobTitle |
The job title of the user |
Any string value |
No |
|
IDPGroupIds |
A list of group IDs (i.e. groups that the user is assigned to in the iDP system). Groups can be used to supply role and/or site details to PainChek. |
For PainChek to process an iDP Group record, the group ID must be recorded in PainChek as an alias for either a PainChek site or a PainChek role |
Conditional See the Conditional Role Claims and the Conditional Site Claims sections below for details |
|
RoleName |
This is the role to be assigned to the PainChek user. Our default roles are:
|
Must be a valid role name |
Conditional See the Conditional Role Claims section below for details |
|
SiteExternalIds |
A space-separated list of external IDs associated with sites that the user is being granted access to. |
Any values supplied must be valid site external IDs. An invalid external ID will result in the user not being authenticated. An external ID is a unique identifier for a site defined in a external system (e.g. a Residential Care System (RCS) of the iDP) and recorded in PainChek |
Conditional See the Conditional Site Claims section below for details |
|
SiteName |
A single input text field that relates directly to a site’s name on the license |
It must be an exact case-sensitive match to either:
|
Conditional See the Conditional Site Claims section below for details |
|
FullSiteAccess |
A string-based boolean indicating whether the user shall have access to all sites |
Must be any of the following values (case insensitive):
|
No If not provided or blank, the user will NOT be granted full site access unless they are being provisioned as a role type that has the full site access permission. |
There are two ways to provide user role details:
-
Using iDP Group IDs (via the IDPGroupIds claim); or
-
Using the PainChek role code (via the RoleName claim)
A PainChek user must be assigned a single role, so ensure that if iDP groups IDs are used, a user is not assigned multiple roles (or no roles at all).
Sites (or facilities) are be assigned to users to control the users access to resident records - a user may only access residents admitted to the sites that the user is granted access to.
it is necessary to include the appropriate SAML claims in the SSO payload.
A user can be granted access to sites as follows:
-
By role - a “license_admin” user will always be granted access to all sites
-
By the FullSiteAccess claim - setting this claim to True will grant the user access to all sites
-
By iDP Group IDs, SiteName or SiteExternalIds - a user can be granted access to specific sites using these claims,
There are three ways to provide user site restrictions:
-
Using iDP Group IDs (via the IDPGroupIds claim); or
-
Using an external site ID (via the SiteExternalIds claim). External IDs are site identifiers provided to PainChek via an integration with a Care Management Systems; or
-
Using the PainChek site name or site alias (via the SiteName claim)
These three methods are mutually exclusive. PainChek SSO does not support receiving a combination of conditional site claims.
With this in mind, the following combination of site related claims are allowed:
|
RoleName |
FullSite Access claim |
IDPGroupIds |
Site External Ids |
SiteName |
Access granted |
|---|---|---|---|---|---|
|
license_admin |
Ignored (treated as True) |
Ignored |
Ignored |
Ignored |
All sites |
|
not license_admin |
True |
Ignored |
Ignored |
Ignored |
All sites |
|
not license_admin |
False |
Populated (with Site records) |
Null/ empty |
Null/empty |
One or more sites identified using the iDP group ids (known as SSO aliases in PainChek) |
|
not license_admin |
False |
Null/empty |
Populated |
Null/empty |
One or more sites identified using Care Management System Site IDs |
|
not license_admin |
False |
Null/empty |
Null/ empty |
Populated |
One site identified by site name or site alias |
Each IdP is slightly different so there is no standard configuration. In general, the following terms are used among IdPs. The terminology varies depending on which side of the connection you are referring to:
IdP Side - Terms for Service Provider (SP) Inputs
-
EntityId
-
OneLogin: Audience (EntityId)
-
Azure: Identifier (EntityId)
-
-
Metadata
-
OneLogin:
-
Azure: There is no metadata URL field in Azure - you can only upload an xml file.
-
-
ACS
-
OneLogin: ACS (Consumer URL)
-
Azure: Reply URL (Assertion Consumer Service URL)
-
SP Side - Terms for the IdP Inputs
-
IdP Entity Id
-
OneLogin: Issuer URL
-
Azure: Azure AD Identifier
-
-
Idp Metadata URL
-
OneLogin: Issuer URL
-
Azure: App Federation Metadata Url
-
-
IdP SSO URL
-
OneLogin: SAML 2.0 Endpoint (HTTP)
-
Azure: Login URL
-
-
IdP Certificate
-
OneLogin: X.509 Certificate
-
Azure: Certificate (Raw)
-
Please remove the comments from the certificate and any line breaks.
There is a quirk in the configuration where the certificates generally come with line breaks after so many characters in the certificate. You need to remove those before pasting saving the SSO configuration in PainChek.