Single Sign On Deployment - NCIOCPL/cgov-digital-platform GitHub Wiki

Deploying SAML authentication to a new environment.

At a high-level, the steps are:

  1. Set up the hostname.
  2. Configure HTTPS.
  3. Create SAML configuration files
  4. Deploy the code.
  5. Exchange SAML metadata with the NIH Login team.
  6. Activate SAML authentication.

Set up Hostname

  1. Determine what the new hostname should be (e.g. www-dev-ac)
  2. Login to Acquia dashboard, go to the server's Overview page, and obtain the server's URL (e.g. ncigovcdode61.prod.acquia-sites.com)
  3. Enter a ServiceNow ticket for the CBIIT Hosting team, requesting a new hostname in the cancer.gov domain.
  • Request that the new hostname be set up as a CNAME alias for the server's Acquia URL.

Configuring HTTPS

This is a three step process:

  1. Generate a Certificate Signing Request.
  2. Request an SSL certificate.
  3. Install the certificate.

Generate the Certificate Signing Request

  1. Login to the Acquia dashboard and go to the server's Overview page.
  2. Click the "SSL" link in the left-side navigation.
  3. In the upper right corner of the page, click the "Generate CSR" link.
  4. Fill out the CSR using:
    1. Country: US
    2. State: Maryland
    3. Locality: Rockville
    4. Organization: National Cancer Institute
    5. Department: OCPL
    6. Common name: *.cancer.gov
    7. Subject alternative name: The server's hostname (e.g. www.cancer.gov)
  5. Click the Generate CSR button. The CSR generation process takes several minutes.

Request Certificate creation

After the CSR generation process has completed:

  1. Login to the Acquia dashboard and go to the server's Overview page.
  2. Click the "SSL" link in the left-side navigation.
  3. Find the CSR in the list on the center of the page and click the "View" link.
  4. At the bottom of the summary, on the "Certificate request" line, click the "Show" link. Copy this text to a text file. It should start similar to the following, but much longer: 
    -----BEGIN CERTIFICATE REQUEST-----
MIIDBTCCAe0CAQAwfjELMAkGA1UEBhMCVVMxETAPBgNVBAgMCE1hcnlsYW5kMRIw
EAYDVQQHDAlSb2NrdmlsbGUxIjAgBgNVBAoMGU5hdGlvbmFsIENhbmNlciBJbnN0
aXR1dGUxDTALBgNVBAsMBE9DUEwxFTATBgNVBAMMDCouY2FuY2VyLmdvdjCCASIw
DQYJKoZIhvcNAQEBBQADggEPADCCAQoCggEBAME07Zq+R1IVwstRMVbOZnS9uCJt
  5. Enter a ServiceNow ticket for the CBIIT Hosting team
    • Request a new SSL certificate to be used with the new host.
    • Attach the CSR text file from the previous step.

Upload the certificate

  1. Login to the Acquia dashboard and go to the server's Overview page.
  2. Click the "SSL" link in the left-side navigation.
  3. On the CSR's line in the summary, click the "Install" link.
  4. Provide the SSL certifcate's details
    1. Label: A meaningful label, such as the server's hostname.
    2. SSL Certificate: copy the text of the certificate file into this field (include the BEGIN and END markers).
    3. SSL private key: this field should already be populated. If it isn't, you probably clicked the wrong installation link. Do not modify this field.
    4. CA intermediate certificates: Copy the contents of the Digicert certificate file.

Create SAML configuration files

Create secrets file.

In /mnt/files/$AH_SITE_GROUP.$AH_SITE_ENVIRONMENT, create the file secrets.settings.php.

This file follows the form of:

<?php

if(!class_exists('SamlSecrets')) {
  class SamlSecrets {

    public const SECRET_SALT = 'some 32 alpha-numeric string';

    public const TECH_CONTACT_NAME = 'a name';
    public const TECH_CONTACT_EMAIL = 'an email address';

    public const AUTH_ADMIN_PASSWORD = 'a strong password.';
  }
}
  • The SECRET_SALT value may be generated by executing the following command from a bash prompt: 
    LC_CTYPE=C tr -c -d '0123456789abcdefghijklmnopqrstuvwxyz' </dev/urandom | dd bs=32 count=1 2>/dev/null;echo
  • TECH_CONTACT_NAME and TECH_CONTACT_EMAIL should be the OCPL application alerts distribution list.
  • AUTH_ADMIN_PASSWORD should be a strong password and shared with the appropriate team members.

Create the signing certificate

This is a self-signed SSL certificate, used for signing SAML login requests. (This is separate from the certificate for HTTPS.)

In /mnt/files/$AH_SITE_GROUP.$AH_SITE_ENVIRONMENT/saml/certificate, execute the command:

openssl req -x509 -sha256 -nodes -days 3652 -newkey rsa:2048 -keyout saml.pem -out saml.crt

Exchange SAML metadata

After a code deployment which includes SAML configuration, the metadata can be obtained by going to the server's /simplesaml/module.php/core/frontpage_federation.php path and clicking on the "Show metadata" link. (NOTE: This requires the SAML admin password, set in the AUTH_ADMIN_PASSWORD member of the secrets.settings.php created in the Create secrets file step above.

The location for obtaining metadata for the NIH IDP varies according to the deployment tier:

Updating SAML metadata

NIH may periodically make changes to the login system requiring the SAML metadata to be updated (e.g. rotating the signing certificate). Updating the metadata requires synchronization with the login team in order to prevent an outage.

IMPORTANT: Because our sites share a single copy of the IDP metadata, they must all be updated at the same time!

Steps:

  1. Obtain the updated metadata XML from the relevant IDP (see above list of links, but expect the embedded version number to change).
  2. Convert the XML to the SimpleSAMLphp format.
    1. Login to the CMS site's /simplesaml/module.php/core/frontpage_federation.php page. (NOTE: This requires the SAML admin password, set in the AUTH_ADMIN_PASSWORD member of the secrets.settings.php created in the Create secrets file step above.
    2. Under the "Tools" heading, click the "XML to SimpleSAMLphp metadata converter" link.
    3. Paste the XML into the "XML metadata" field.
    4. Click the "Parse" button at the bottom of the page.
    5. Copy the output from the "saml20-idp-remote" field into a file named saml20-idp-remote.php-new.
  3. Upload the converted metadata file. 
    scp saml20-idp-remote.php-new AH_SITE_GROUP@SERVER_NAME:/mnt/files/AH_SITE_GROUP.AH_SITE_ENVIRONMENT/saml/config
    • AH_SITE_GROUP is the userid for sshing to the server.
    • SERVER_NAME is the specific server.
    • AH_SITE_ENVIRONMENT is environment name.
    • The AH_SITE_GROUP and AH_SITE_ENVIRONMENT are, of course, the same values as the matching environment variables. 😉
  4. Switch out the metadata file.
    • Obviously, this is the step requiring coordination with the login team.
    1. ssh to the server being updated.
    2. cd /mnt/files/$AH_SITE_GROUP.$AH_SITE_ENVIRONMENT/saml/config
    3. cp saml20-idp-remote.php saml20-idp-remote.php-old
    4. When the login team is ready: 
      cp saml20-idp-remote.php-new saml20-idp-remote.php`

Activating SAML authentication

This step will go away soon.

Activating SAML will disable non-SSO login for users who don't have the Administrator role (and that should be disabled too).

To activate SAML authentication:

  1. Login to the server as a user with the Administrator role.
  2. In the Admin UI, navigate to Configuration > People > SimpleSAMLphp Auth Settings.
  3. Under "Basic Settings", check the box for "Activate authentication via SimpleSAMLphp"
  4. Scroll to the bottom of the page and click the "Save configuration" button.