Drupal SAML Knowledgebase

This has been updated for Drupal 10, as at October 2023.

Important Terminology.

IDP: Identity Provider - The IDP is Ping Federate which is managed by the City's IAM team. The actual user accounts are stored in Microsoft Active Directory and other City managed domain services which are connected to Ping. The IDP's function is to provide the user "authentication" checking user credentials and reporting security roles - reducing or removing the SP 's responsibility for verifying access and maintaining the security element of user accounts.

SP: Service Provider - The SP can be thought of as as a series of authentication functions within an application. In most implementations, the IDP and SP communicate using a SAML protocol. On successful authentication with the IDP, the SP receive standard and authoritative message (usually via a SAML formatted cookie) defailing the users name, email and (ideally but optionally) the Users security roles/groups.

SAML Implementation in Drupal.

In the case of boston.gov the SP is Drupal, or more specifically the SamlAuth module in Drupal.

The SamlAuth module (config-UI here) manages the communication with Ping (IDP) and exchanges SAML messages during a standard SAML process.

The IDP is used only to authenticate the user and SamlAuth receives a SAML message back from Ping (IDP) containing the username (cn), firstname, lastname and email of the authenticated user. If Authentication at Ping fails, the user cannot login to Drupal.

• SamlAuth maps user accounts from Ping with user accounts in Drupal, where the cn from Ping equals the username in Drupal. If no matching account exists, SamlAuth automatically creates an account in Drupal, and assigns the content_authorrole.

• Security Groups in Ping are not reported to Drupal/SamlAuth, so no attempt is made to synchronize roles between Ping and Drupal. Even though it is not done at this time, this can be simply implemented in the future. Therefore, changes to user groups in Ping and Drupal are independent and never synchronized.

• Drupal requires an email address to create an account. The email address does not need to be on the boston.gov domain, and it does not need to be unique. Ping (actually the IAM authoritative record systems behind Ping) cannot guarantee to provide an email address, so SamlAuth has been modified to create a "fake" email address using the pattern [e-mail] when there is no email in the SAML response from Ping.

• SamlAuth requires an x509 security certificate (issued from or by the IDP (Ping)) in order to verify authenticity of the SAML response, and to decrypt the SAML message contents. This x509 certificate is created and distributed by IAM and is stored in environment variables and accessed by SamlAuth via the Key module.

In COB, we use just one IDP providers.

• The IDP provider is accessed via to sso.boston.gov.

Boston.gov users typically use Access Boston to login to boston.gov (Drupal).

• The Main tile on Access Boston Production launches content.boston.gov (prod)

• The Dev tile on Access Boston launches d8-dev.boston.gov (development).

• The Test tile on Access Boston launches d8-uat.boston.gov (UAT).

• To use SSO to login to any other Acquia environment, you cannot use Access Boston and need to use the saml/login link. For example:

  • Boston.gov stage => https://d8-stg.boston.gov/saml/login

  • Boston.gov dev2 => https://d8-dev2.boston.gov/saml/login

  • Boston.gov CI => https://d8-ci.boston.gov/saml/login

  • Boston.gov local => https://boston.lndo.site/saml/login (SAML keys will need to be manually added to this environment for SSO to work p- but it will work).

Update IDP Certificate

From time to time the IDP certificate will expire and need to be re-issued by the Identity and Access Management team.

You should receive the IDP Metadata XML from IAM (or just the x509 certificate). This info will come as a single file per IAM environment. We are only interested in the IAM PRODUCTION environment metadata/certificate). See the next box to extract the x509 certificate from the metadata.

For each Acquia environment: To allow the certificate to be changed with no downtime, we have 2 environment variables, mapped to 2 keys inside Drupal. Drupal will allow multiple certificates to be active simultaneously, and will rotate through expired or invalid certificates until a valid entry is found.

For Acquia Environments:

1. Login to the Acquia Cloud Console

2. Navigate to the environment you wish to update, and select the variablessection

3. Find and note which environment variable (iam_x509_cert/ iam_x509_cert_test) has the current active key.

4. Update the OTHER environment variable with the new certificate (cut and paste it over the existing entry) and save.

5. Note: The change will be immediate on the environment.

6. Note: For performance it is best to have the currently active key at the top of the list in the Identity Provider section of the SAML config page (admin/config/people/saml). You can drag and drop to re-order, then save the page.

For your Local Dev Environment:

Your local dev environment uses the IDP Metadata from the IAM Test environment.

1. Login to your local Drupal

2. On this page, edit the key you wish to update

3. On the key page, in the certificate box, paste the new x509 certificate

4. Save the page.

Finding the certificate in the metadata

The certificate is the X509Certificate field in the IDP Metadata file.

The IDP Metadata file (XML) can be opened in any text editor, and it will look as follows:

  $metadata['urn:XXX:sso:boston.gov'] = array (
  
  ...
  
  'keys' => array (
      0 => array (
        'encryption' => false,
        'signing' => true,
        'type' => 'X509Certificate',
        'X509Certificate' => ,
      ),
    ),
    
    ...

  );

Tip

You can check the expiry of the IDP certificate by clicking the info button the key entry console.