You are viewing an old version of this page. View the current version.

Compare with Current View Page History

« Previous Version 2 Next »

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:

  1. /var/simplesamlphp/config/config.php
  2. /var/simplesamlphp/metadata/saml20-idp-remote.php
  3. /var/simplesamlphp/config/authsources.php
  4. /var/simplesamlphp/metadata/dc-idp-mapping.php


Changes to /var/simplesamlphp/config.php - only required once per V1 server


The following changes (with reference to this URL are required as baseline setup of simpleSAMLphp these changes are only required once.

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 

Additional change required in config.php specific to Dr. Cloud

The phpsession cookiename needs to be changed from SimpleSAML to DrCloud

    'session.phpsession.cookiename' => 'DrCloud',

 Changes to /var/simplesamlphp/metadata/saml20-idp-remote.php

Metadata for each Identity Provider needs to be added to the saml20-idp-remote.php file

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


 Changes to /var/simplesamlphp/config/authsources.php

The entries added in the previous step need to be enabled as authentication sources

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',
],
'sp2' => [
    'saml:SP',
  'entityID' => 'https://okta.com/',
],

 Changes to /var/simplesamlphp/metadata/dc-idp-mapping.php


The authentication sources defined in the previous step are mapped to V1 site_id/database configurations

/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'],     //--example
      'second'     =>['dc_site_id' => 'qa'          , 'idp_entity' => 'sp2'],     //–example

];

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, 


  • No labels