A Basic Globus Login for Apache Websites

One of the features Globus users appreciate is its user-friendly login mechanism. Globus allows users to login using Google, ORCID, or identities from any of the thousands of academic/research organizations that participate in InCommon or eduGAIN.

Did you know you can easily add the Globus login function to your own Apache-hosted website or web application? In this blog post, I’ll demonstrate how to use Globus Auth to do just that.

Globus Auth is based on OpenID Connect (OIDC), a widely used social login mechanism. This means you can use any of the open source and commercial OIDC adapters, plugins, and code modules to add Globus Auth to your website or application.

But if you’re looking for something simple and universal, it’s hard to get more basic than using the Apache web server’s built-in authentication functions. You can add Globus logins to any Apache website using the open source mod_auth_openidc module for Apache web servers. With this module and a few lines in your Apache server’s configuration files, your website can log users in and access their identity information. You can then use any programming language or web framework you like to keep track of users as they visit your site.

Note: To follow the examples in this post, you’ll need an Apache web server with SSL/TLS encryption (for https:// addresses) enabled. If you don’t have SSL/TLS on your web server, the easiest (and free!) way to add it is to use Let’s Encrypt.

Get the module

The mod_auth_openoidc module isn’t pre-installed on most Apache installations, so you’ll need to add it to your Apache web server. The module’s GitHub site offers pre-built packages of the latest versions for Windows, Debian/Ubuntu, and CentOS/Redhat.

Most Linux package repositories also have a mod_auth_openidc package available, although these are seldom the latest release.  The following commands will install mod_auth_openidc on your Linux server.

Debian/Ubuntu:

% sudo apt-get install libapache2-mod-auth-openidc

CentOS/RedHat:

% sudo yum install mod_auth_openidc

Configure Apache to use Globus Auth

Once you’ve installed mod_auth_openidc, you need to add a few lines to your Apache configuration files to tell it how to use Globus Auth.

Figure 1 offers an example of the Apache configuration. In this example, any page or application on your web server that has a URI beginning with /protected will require the user to be logged in with Globus. Once the user has logged in, these pages and applications will have access to the user’s identity returned from Globus.

# Load the mod_auth_openidc module
LoadModule auth_openidc_module modules/mod_auth_openidc.so

# Configure the module to use Globus Auth
OIDCProviderMetadataURL https://auth.globus.org/.well-known/openid-configuration
OIDCClientID CLIENT_ID
OIDCClientSecret CLIENT_SECRET
OIDCRedirectURI https://your.hostname.here/protected/redirect_uri
OIDCCryptoPassphrase ANY-LONG-RANDOM-SEQUENCE-OF-CHARACTERS
OIDCScope "openid email profile"

# Specify the part of your server space that will require the user to login
<Location /protected>
   AuthType openid-connect
   Require valid-user
</Location>

Figure 1. Sample Apache server configuration for Globus Auth and mod_auth_openidc

You’ll notice that the example in Figure 1 requires you to supply a CLIENT_ID and CLIENT_SECRET. These will be unique for your web server, and you must get them from Globus. Follow the instructions for registering your application with Globus, and you’ll receive these values. (When you register your application, use the OIDCRedirectURI value in Figure 1 for the Redirect needed by Globus.)

After you’ve added this configuration to your Apache server, restart your server to make the configuration changes take effect. Now, create a directory named “protected” in your server’s DocumentRoot directory (where your HTML content is stored). Then open a web browser and enter the address “https://your.hostname.here/protected/”. Even if you have no content in the protected directory, you should see the Globus login page. Login with Globus, and when you’re finished, you’ll receive the “page not found” error in your browser indicating that you’ve returned to your website and there’s no content there yet.

Access the login information in your web pages

Now that you have a login function on your web server, you need to access and use the user’s identity.  When using mod_auth_openidc, the user’s identity information is added to the $_SERVER environment that is passed to your web pages or applications in the /protected space. Within the $_SERVER environment, the identity information is accessible via variables beginning with the prefix OIDC_CLAIM_. For example, the user’s name is available in the variable, OIDC_CLAIM_name. The user’s email address is OIDC_CLAIM_email. The name of the identity provider that is supplying the user’s identity to Globus is OIDC_CLAIM_identity_provider_display_name. Figure 2 provides an example using PHP code in a web page to display the user’s identity.

<html>
  <body>
    <h1>Welcome</h1>

    <p>Hello, <?php echo($_SERVER['OIDC_CLAIM_name']) ?>
       from <?php echo($_SERVER['OIDC_CLAIM_identity_provider_display_name'])?>.
    </p>
  </body>
</html>

Figure 2. Example HTML with PHP code that displays the logged-in user’s identity

If you have PHP enabled for your web server, create a file named index.php in the /protected directory for your web server and use the example HTML from Figure 2. Now, when you visit https://your.hostname.here/protected/ in your browser, you should see a message in your web browser that looks like Figure 3. Of course, the name and identity provider information will be replaced by yours, depending on how you logged into Globus.

Figure 3. Web browser output from the example in Figure 2

Tracking user visits

Now that you see how mod_auth_openidc works, you can use this simple mechanism to track users and their visits. Whether you build your site with PHP like the examples above, or use a framework like Django or Ruby, the $_SERVER data provided by Apache and mod_auth_openidc will provide the user’s identity. You can use a simple database like MySQL, MariaDB, MongoDB, or Cassandra to keep track of users between visits.

If you need a reliable key for each user’s identity in your database, we recommend using the OIDC_CLAIM_sub value. (“Sub” is short for “subject” and refers to a unique person.) The value will be a UUID string (e.g., “b16ac48c-d274-11e5-8e40-3b85f20c1bc0”), and it will always be the same for a given person in Globus. People sometimes change their profile information (name, email address, organization, etc.), but the OIDC_CLAIM_sub value that Globus returns will remain the same.  Use OIDC_CLAIM_sub for the database key, and you can update the name and other information whenever the user returns to your site.

For more information about mod_auth_oidc, visit the Frequently Asked Questions on GitHub. For more information about Globus Auth, visit the Globus Auth Developer’s Guide.