Enabling SAML for PHP based DrCloud sites requires installation of SimpleSAMLphp version 1.19.9
This older release is required for compatibility with current PHP version 7.4 in use for DrCloud
https://github.com/simplesamlphp/simplesamlphp/releases/tag/v1.19.9
The default folder to extract the required files is /var/simplesamlphp
After extraction, a symbolic link is needed in the webserver root directory (/data1/wwwroot/html) to /var/simplesamlphp/www named simplesaml
Access to SAML related configuration and test tools are available at:
https://<v1-server>/simplesaml
Login via SAML is accomplished at this URL:
https://<v1-server>/<ehrFiles>/interface/login/saml.php?idp=<IdentityProviderTag>
(example: https://dceast.drcloudemr.com/ehr/interface/login/saml.php?idp=whlc) <NOT yet configured>
Additional changes are required in four files:
https://simplesamlphp.org/docs/1.19/simplesamlphp-install.html#simplesamlphp-configuration-configphp
Set the baseurlpath
configuration option. Make it point to the canonical URL of your deployment, where SimpleSAMLphp can be reached:
'baseurlpath' => 'https://your.canonical.host.name/simplesaml/',
Please note that your canonical URL should always use HTTPS in order to protect your users. Additionally, if you are running behind a reverse proxy and you are offloading TLS to it, the proper way to tell SimpleSAMLphp that its base URL should use HTTPS is to set the baseurlpath
configuration option properly. SimpleSAMLphp deliberately ignores the X-Forwarded-*
set of headers that your proxy might be setting, so do not rely on those .
Set an administrator password. This is needed to access some of the pages in your SimpleSAMLphp installation web interface.
Hashed passwords can also be used here. See the authcrypt
documentation for more information.
'auth.adminpassword' => 'setnewpasswordhere',
Set a secret salt. This should be a random string. Some parts of the SimpleSAMLphp needs this salt to generate cryptographically secure hashes. SimpleSAMLphp will give an error if the salt is not changed from the default value. The command below can help you to generated a random string on (some) unix systems:
tr -c -d '0123456789abcdefghijklmnopqrstuvwxyz' </dev/urandom | dd bs=32 count=1 2>/dev/null;echo
Here is an example of the configuration option:
'secretsalt' => 'randombytesinsertedhere',
Please note that changing the secret salt may break access to services for your users
The phpsession cookiename needs to be changed from SimpleSAML to DrCloud
'session.phpsession.cookiename' => 'DrCloud',
The XML from the IdP needs to be converted into PHP format and appended to the above file using the metarefresh tool:
(Detailed documentation in the following link):
https://simplesamlphp.org/docs/contrib_modules/metarefresh/simplesamlphp-automated_metadata.html
Command used as follows.
/var/simplesamlphp/modules/metarefresh/bin/metarefresh.php -s https://<idp-server>/<location>.xml > <IdPFileName>.php
Example:
/var/simplesamlphp/modules/metarefresh/bin/metarefresh.php -s https://drcloudehr-idd-qa-dev-ed.develop.my.salesforce.com/.well-known/samlidp.xml > SF-SSO.php
For each IdPs/sites to be enabled, the above command needs to be run with different <idp-server> and/or <location> to generate distinct files.
Each of the generated files needs to be combined into the /var/simplesamlphp/metadata/saml20-idp-remote.php
Example:
cat SF-SSO.php SF-SSO-2.php SF-SSO-3.php > /var/simplesamlphp/metadata/saml20-idp-remote.php
This creates entries in the metadata array for each IdP. The keys in this array are used in the next step
$metadata['https://drcloudehr-idd-qa-dev-ed.develop.my.salesforce.com'] = array (
'entityid' => 'https://drcloudehr-idd-qa-dev-ed.develop.my.salesforce.com',
'entityDescriptor' => 'PG1kOkVu....
https://simplesamlphp.org/docs/1.19/simplesamlphp-sp.html#configuring-the-sp
Entries need to be added to the authsources.php file in the config array as follows:
'sp1' => [
'saml:SP',
'entityID' => 'https://drcloudehr-idd-qa-dev-ed.develop.my.salesforce.com',
'idp' => 'https://drcloudehr-idd-qa-dev-ed.develop.my.salesforce.com',
],
'sp2' => [
'saml:SP',
'entityID' => 'https://okta.com/',
'idp' => 'https://okta.com/',
],
The entityID and idp are keys to the metadata array defined in saml20-idp-remote.php file that was updated in the previous step.
The entityId and the idp entries are set to the same value to eliminate the step of choosing an IdP when logging in.
/var/simplesamlphp/metadata/dc-idp-mapping.php stores an associative array of authentication source to V1 site_id tags. It specifies which database should be used to compare the SAML user with the V1 user. (referenced through the email address column in the users table)
$DC_IDP_MAPPINGS = [
// idp-tag DrCloud SiteID idp-entity-id
'qa' =>['dc_site_id' => 'qa' , 'idp_entity' => 'sp1'], // (Connects to qa site using "Salesforce IdP"
'qa-okta' =>['dc_site_id' => 'qa' , 'idp_entity' => 'sp2'], // (Connects to qa site using "Okta IdP"
];
These mapping consist of an idp-tag that associates a SiteID(dc_site_id) with one of the sources(idp_entity) defined in authsources.php
The idp-tag is specified when accessing the SSO URL described earlier
https://<v1-server>/<ehrFiles>/interface/login/saml.php?idp=<IdentityProviderTag>
The idp-tag does not need to match the V1 site id. However, when possible, it is encouraged to do so. If multiple IdP need to connect to the same V1 site, then only one of the idp-tags can match the V1 site id