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 usee 2 IDP providers - one for prod and one for all non-prod.

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

• The non-prod IDP provider is the IAM test provider at sso-test.boston.gov.

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

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

• The tile on Access Boston Test launches d8-stg.boston.gov (stage).

• 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 dev => https://d8-dev.boston.gov/saml/login

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

  • Boston.gov local => https://boston.lndo.site/saml/login

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 request the IDP Metadata XML from IAM. This info will come as a single file per environment - with the extension .xml. See the next box to work out which part of the metadata is the certificate.

For Acquia Environments:

1. Login to the Acquia Cloud Console

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

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

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

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.