Pantheon setup

Pantheon’s standard approach to building Drupal sites is called Integrated Composer. This workflow provides a way to assemble external code during deployment from a list of dependencies defined in the site. Pantheon’s documentation succinctly summarizes this approach:

Composer encourages a mental model where code not written specifically for a given project is a dependency. Only files unique to the project are tracked as part of the project’s main source repository, also referred to as the canonical site repository.

With Integrated Composer, a new Drupal Kit site can be created entirely through the Pantheon dashboard.

Creating a new site

  1. Request access to the University of Texas organization (see https://ut.service-now.com/sp?id=kb_article&number=KB0014813).

  2. Sign in at https://dashboard.pantheon.io/login

  3. Use this link to create a new UT Drupal Kit site: https://dashboard.pantheon.io/sites/create?upstream_id=f0de5643-e2ce-4614-8fc0-c555634219bc

  • Enter a name for the site.

  • Use “United States” for the region. Click Continue.

Important

After you click Continue, it will take several minutes for the platform to set everything up. You can confirm the platform is set up by checking that the Workflow button shows no in-progress processes. Attempting to visit the site while processes are still running can cause the site to malfunction.

  1. Still in the Dev tab, click Visit Development Site and follow the prompts to complete the CMS installation.

For local development, return to the Dev tab, set the site’s Development Mode to Git, and clone the site locally. Then, in your local terminal, from the project root directory, run composer install.

Anatomy of the Pantheon codebase

Your Pantheon dashboard’s DEV tab includes a button to “Clone with Git” for local development. Doing so will show a codebase that consists, in its entirety, of the following:

├── .editorconfig
├── .gitignore
├── COPYRIGHT.txt
├── LICENSE
├── README.md
├── composer.json
├── composer.lock
├── config
│   └── .htaccess
├── pantheon.upstream.yml
├── upstream-configuration
│   ├── composer.json
│   └── scripts
│       └── ComposerScripts.php
└── web
    └── sites
        └── default
            └── settings.php

Note that the site repository does not contain any of the actual files related to Drupal core or the custom theme and modules provided by the UT Drupal Kit. These elements are pulled in via Composer during each code deployment process on Pantheon. See Integrated Composer for more details about Composer on Pantheon.

Your codebase includes a connection to the Pantheon “upstream.” The upstream supplies the UT Drupal Kit code and sets which version of the Kit your site is using. This means that some files in your codebase should not be directly modified; when you use the Pantheon dashboard to apply UT Drupal Kit updates, these files will be updated by the upstream repository. The following table should be used as a reference for which files should not be modified:

File

Safe to change?

Notes

.gitignore

Yes

Directs certain files or directories not to be committed to a Git repository. Generally speaking, developers should not have to modify this file for use with Pantheon sites, but it can be used as needed per standard Git methodology.

.editorconfig

Yes

Default code editing configuration settings. These may be changed or removed by individual sites without consequence.

composer.json

Yes

Developers can use standard Composer commands to manage site specific dependencies and configuration.

composer.lock

No

This file should not be directly modified. It contains metadata about requirements.

config/

Yes

If you decide to use Configuration Management, your site configuration can be stored here.

pantheon.upstream.yml

No

Defines default values for site settings such as PHP version and HTTPS enforcement. It should not be directly modified. If you need to override these values, you should add a pantheon.yml file.

settings.php

No

Unlike a typical Drupal site, this file is reserved for ITS to push settings changes to sites. Your settings should go in a settings.site.php file.

upstream-configuration/

No

Local repository of the information related to the UT Drupal Kit. It should not be directly modified. Changes to the UT Drupal Kit will appear here will new releases are available, and those changes can be applied via the Pantheon dashboard.

Further reading

For more information on what is included in this scaffolding and how it is designed to work, see the following topics:

Integrating Enterprise Authentication

By default, site accounts leverage a local username/password combination for authentication. Sites may switch to EID authentication using the university’s Enterprise Authentication system.

This requires the Drupal Kit team to configure Security Assertion Markup Language (SAML) metadata for the site. This process is described below.

Request integration

ITS must add metadata about your Pantheon site for it to leverage Enterprise Authentication. To start this process, complete the Pantheon SAML Integration request form, which will open a new ticket in ServiceNow.

You may still proceed with the installation while ITS completes the provisioning process.

Note

It takes several hours after the integration process is completed by ITS staff for Enterprise Authentication to be available for your site. If the EID sign-in screen displays the message “The application you have accessed is not registered for use with Enterprise Authentication” for more than 24 hours after ITS has completed integration, email pantheon-support@utlists.utexas.edu to open a support ticket.

Add the “Pantheon SAML Integration” plugin

ITS maintains a Composer plugin that facilitates Enterprise Authentication integration. In the local directory where you installed your site (see above), run the following:

composer require utexas/pantheon_saml_integration

These are dependencies downloaded by the above package:

  • The simplesamlphp library.

  • The simplesamlphp_auth contributed module.

  • The utexas_saml_auth_helper custom module.

After the Composer process completes, make sure to version control and deploy to Pantheon.

Once you have your changes deployed, enable both the simplesamlphp_auth and the utexas_saml_auth_helper modules in your Pantheon environment.

Go to your.pantheonsite.io/admin/people/create, add your EID in the Username (UT EID) field and save.

Once ITS has completed adding metadata about your site, you will be able to use SAML authentication.

The final step is to activate SAML authentication by going to “Configuration” > “SimpleSAMLphp Auth Settings” (/admin/config/people/simplesamlphp_auth), ticking “Activate authentication via SimpleSAMLphp,” and saving the configuration.

To test authentication, go to your.pantheonsite.io/saml_login and verify the university’s Enterprise Authentication sign-in screen is provided. Verify you can sign in with the EID-based user account you created above.

Convert Drupal users to Enterprise Authentication

You can use a drush command provided by utexas_saml_auth_helper module the to convert all eligible users or specific usernames. In this context, conversion means setting the module column in the authmap table to simplesamlphp_auth, effectively instructing that module to handle authentication.

Note

The following steps require the use of Terminus, Pantheon’s command-line utility. See Pantheon’s documentation for more information about installing and using Terminus

terminus drush <site>.<environment> -- saml-convert all
# Automatically updates all users in the system, excepting User 1, whose usernames pass EID regex validation.
terminus drush <site>.<environment> -- saml-convert "[username]"
# Converts a given [username] individually, so long as it passes EID regex validation.
terminus drush <site>.<environment> -- saml-convert
# Provides an interactive shell prompt for each eligible username in the system as shown below
# Convert username [username]?
# [0] : Cancel
# [1] : Yes