Globus Connect Server v5.4 OIDC Server Installation Guide

Last Updated: Feb 09, 2022

1. Introduction

This document describes the common tasks a Globus administrator would need to do to create and manage a Globus OIDC server for the endpoints they administer.

The Globus OIDC module is used in scenarios where the authentication service needed to access collections on the endpoint is not one of the identity providers that can be used to log into Globus. Using this module an administrator can allow users to log in with their local Linux identities (or LDAP identities) to access collections hosted on this endpoint. The module uses Linux Pluggable Authentication Module (PAM) and the administrator can configure a suitable PAM module and authentication to use.

If you have an existing OIDC server that you would like to use for authenticating access to your endpoint, see the globus-connect-server oidc register command.

2. Globus OIDC Server Overview

2.1. Installation Overview

The OIDC server should be set up after creation of the endpoint and installation of the data transfer node(s). The following commands should be run on one of the data transfer nodes, and the configuration will be automatically propagated to the rest of the nodes.

Important

Note that the OIDC server configuration is automatically propagated to all the other nodes, however the login page customizations and the server certificates (if --manage-certificate-and-key was not specified during the oidc create) must be manually updated on all nodes.

This document assumes that you have already created and deployed an endpoint by following the Globus Connect Server version 5 Installation Guide. The commands in this guide assume you have access to the globus-connect-server command-line tool.

A Globus OIDC server is created by:

  1. Configuring the domain for the OIDC server

  2. Installing the Globus OIDC server using the globus-connect-server oidc create command on one of the GCS nodes

  3. Configuring the HTML and CSS for the Globus OIDC login page on each data transfer node. More information on this can be found below in Customizing the Globus OIDC Login Page

Once the OIDC server is setup, any GCS storage gateway can be configured to accept identities from the OIDC instance using the --domain parameter. More information on this step can be found in the Data Access Admin Guide

2.2. Command Overview

Globus OIDC instances are configured and managed via the globus-connect-server oidc commands:

globus-connect-server oidc create

Create a Globus OIDC server for the endpoint

globus-connect-server oidc update

Update an existing Globus OIDC configuration

globus-connect-server oidc show

Show a Globus OIDC server definition

3. Globus OIDC Server Prerequisites

3.1. Linux PAM Module Support

The following Linux PAM configuration is required for the Globus OIDC server to operate correctly:

  • All data transfer nodes will host OIDC servers so if you are using the login PAM module, which is the default setting, the Linux users need to exist on all the data transfer nodes

  • If you are using a custom PAM module (such as for LDAP integration), the PAM module should be set up on all of the data transfer nodes

3.2. Domain Configuration

The Globus OIDC server can either use a custom domain, or it can be configured as a sub-domain under the Globus Connect Server endpoint. If you elect to use a sub-domain under the endpoint, the user identity will be <username>@identity.<UUID>.data.globus.org.

It is recommended that all production Globus OIDC servers are configured with a custom domain. This ensures that users can readily identify the servers they are authenticating against.

Important
If you use the fully-qualified hostname of the local node as the custom domain, it may cause conflicts between httpd’s default virtual host configuration and the OIDC virtual host configuration which could result in a nonfunctional OIDC service.
Important

Note that only one Globus Connect Server is allowed to assert identities for a given domain, so once a domain is claimed by an instance it must be manually released before it can be reassigned. Once users sign in they will build roles and permissions based on the identity in the domain. Reassigning the domain has security implications, and careful consideration should be given for the domain used for test and production. It is recommended that test installations make use of the Globus Connect Server sub-domains option --quickstart-server-name, and a custom domain be used for production deployments.

3.2.1. Configuring a Custom Domain

When configuring a custom domain you will need to set up the following:

  1. A record that resolves the domain into the Globus Connect Server instance(s). In multi-node configurations the A record should resolve to at least one IP, however it is recommended that all instances are added to the record.

  2. TXT record with the endpoint’s client ID to validate ownership of the domain.

  3. Certificates for the domain.

More information on configuring the TXT record and the certificates is provided below.

Domain TXT Record

A DNS entry is also needed in domain records to validate the ownership of the domain. During the installation of the first node, this record will be validated. To create this entry:

  • Create a domain TXT record for the fully-qualified domain name for the OIDC server

  • Put the endpoint’s Globus Auth client ID in the TXT record (note that this is the endpoint’s client ID)

  • Confirm that this is correctly retrieved by using a domain record checker (such as dig) before running the oidc create command

Certificates

The certificates for the Globus OIDC domain should be available on the machine when running the oidc create command.

If you do not currently have SSL certificates they can be generated using certbot with LetsEncrypt. More information can be found at LetsEncrypt.

It is possible for GCS to manage the certificates so that they will be automatically installed on each GCS node. This can be enabled by adding the --manage-certificate-and-key flag when running oidc create.

3.2.2. Using the Globus Connect Server Domain

Alternatively, the GCS OIDC server can also be registered as a sub-domain under the GCS endpoint. Enable this option with the --quickstart-server-name parameter. Provide this parameter with a short identifier (e.g. identity) and the Globus OIDC server will be created as a child of the endpoint, e.g. identity.[endpoint].data.globus.org. In this case, only the --quickstart-server-name should be specified, and neither the --server-name nor the certificates should be provided. Note that the identifier should be unique and cannot be reused.

This option should only be used with testing or development instances and is not recommended for production systems.

4. Installing the Globus OIDC Server

We’re going to walk through creating a Globus OIDC server for a given endpoint, discussing the configuration associated with the different aspects of the server.

Important

When naming your OIDC instance, note that the --display-name is limited to 64 characters.

4.1. Creating the Globus OIDC Server Configuration

The Globus OIDC server is configured at the endpoint level. The creation step indicates that the server will be installed on each data transfer node. We’ll call the OIDC server Example OIDC Server, which is hosted at example.org with the matching certificate, and we will provide contact information. These fields are required parameters to create the OIDC server, and the following command should be run only once on any data transfer node that has already been configured:

Example 1. Create the Globus OIDC Configuration
% sudo globus-connect-server oidc create \
    --display-name "Example OIDC Server" \
    --server-name example.org \
    --certificate-path "$(pwd)/cert.pem" \
    --certificate-chain-path "$(pwd)/fullchain.pem" \
    --private-key-path "$(pwd)/privkey.pem" \
    --manage-certificate-and-key \
    --support-contact "Test User" \
    --support-email testuser@example.org
OIDC server enabled for this endpoint.
Important

The certificate paths should be full paths.

4.1.1. Using a Custom PAM Module for Authentication

The OIDC server is configured by default to authenticate users against the local PAM module login. This allows local user-based configuration and authentication, however you can specify any PAM module during the create step. To specify a custom PAM module use the --pam-service.

Important

Ensure that the PAM module is set up on each data transfer node for the endpoint.

4.1.2. Using a Quickstart Globus Connect Server Sub-Domain

You can install the OIDC server using a Globus Connect Server sub-domain, and the option does not require the certificates parameters. For example:

Example 2. Create the Globus OIDC Configuration
% sudo globus-connect-server oidc create \
    --display-name "Example OIDC Server" \
    --quickstart-server-name identity \
    --support-contact "Test User" \
    --support-email testuser@example.org
OIDC server enabled for this endpoint.

The OIDC server will assert identities in the identity.<UUID>.data.globus.org domain, where the UUID is the endpoint UUID.

4.2. Updating the Globus OIDC Server Configuration

You can update the certificates, display name, support contact information, or PAM module using the update command. Only the parameters that are being updated should be provided.

Example 3. Update the Globus OIDC Server Configuration
% sudo globus-connect-server oidc update \
    --display-name "New Name" \
    --support-contact "Test User" \
    --support-email testuser@example.org \
    --pam-service login
Globus OIDC server has been successfully updated.

If you have multiple nodes, the other nodes will be automatically updated.

4.3. Showing the Globus OIDC Server Configuration

The Globus OIDC configuration can be displayed to allow users to validate the configuration as well as to provide information for troubleshooting.

Example 4. Show the Globus OIDC Server Configuration
% sudo globus-connect-server oidc show
Current OIDC server configuration:
{
  "auth_client": {
    "client_id": "03535ffe-76a9-4a8c-b2f5-3bd9c52fe024",
    "domain": "example.org",
    "env": "test"
  },
  "clients": {},
  "oidc_server": {
    "display_name": "Test OIDC Server",
    "first_install": true,
    "pam_service": "login",
    "support_contact": "TestUser",
    "support_email": "testuser@example.org"
  }
}

4.4. Customizing the Globus OIDC Login Page

It is recommended that the login page is updated with a title, logo, and information about the organization.

Once the Globus OIDC server has been set up, the HTML, page logo, and CSS for the login page should be updated on all data transfer nodes. Note that you will need to be root to make changes to the content. The elements can be found in the following locations:

  • Login page HTML: /var/lib/globusoidc/globus-oidc/site/login.mako

  • Login page logo: /var/lib/globusoidc/globus-oidc/site/assets/logo_here.png

  • Login page CSS: /var/lib/globusoidc/globus-oidc/site/assets/styles.css

All nodes should be updated with the changes to ensure consistency.

Important

Your browser cache should be cleared after modifying the files to ensure that the latest content is retrieved.

5. Setting the Domain on the Storage Gateway

Once the OIDC server is setup, it can be used to configure a storage gateway to require a user from the OIDC server. This can be done with the --domain parameter when configuring the storage gateway, and more information on this can be found in Data Access Admin Guide.

Note that it is possible to use the same Globus OIDC domain across multiple endpoints by specifying --domain on storage gateways related to other endpoints. However, the Globus OIDC instance is part of the original endpoint, and removing the original endpoint will also remove the Globus OIDC instance.

6. Endpoint Deletion and Globus OIDC Servers

When removing endpoints, it should be noted that after removal of the endpoint the identities and accounts will still be associated with the domain in Globus Auth. The domain cannot be automatically registered with another endpoint, and the installation will fail if the domain is already assigned. If you would like to remove a Globus OIDC server and reassign the domain, a ticket should be opened by emailing support@globus.org from an administrator of the endpoint and we can enable re-registration of the domain.

Important

Note that a domain reassignment will remove the identities associated with the original Globus OIDC server. Users signing in via the new Globus OIDC instance will be assigned a new identity. Shares, group memberships, and other identity information will be cleared.