Configuration

Core configuration is provided through environment variables. This section describes the environment variables which must be populated, and how the data may be stored or accessed.

Required Variables

WORKGROUP_STEM: This is the name of the Workgroup stem that will be used to hold SGGM-created Workgroups. The trailing colon must not be present.
WORKGROUP_API_TIER: The tier to use for the Workgroups API. This can either be ‘PROD’ or ‘UAT’.
WORKGROUP_API_KEY: The private key used to connect to the Workgroups API. This key needs to be PEM-encoded, with no encryption passphrase.
WORKGROUP_API_CERT: The certificate—matching the private key set in WORKGROUP_API_KEY—to use for authenticating to the Workgroups API. It must also be PEM-encoded.
GLOBUS_CLIENT_ID: The ID of the Globus Auth Confidential Client used by this application.
GLOBUS_CLIENT_SECRET: A Client Secret for the Globus Auth Confidential Client.

Optional Variables

GLOBUS_PREFIX: If present, this string will be included in created Globus Group names, and in Workgroup descriptions. It is meant to denote non-production, so the convention is to leave this variable un-set in the producton environment.

If set, the value will be uppercased and placed in square brackets at the start of the Globus Group’s name, in the format “[$prefix] …”. In the Workgroup, it will be lowercased and placed at the start of the Workgroup description in the format “$prefix environment—“.

Hard-Coded Variables

Some settings are hard-coded, because it is very unlikely that they will change.

APPS_DOMAIN: All Globus Identity usernames take the form of user@domain. Every Globus Auth Confidential Client has its own Globus Identity, in a common domain. This setting holds that common domain. Right now it is clients.auth.globus.org.
DOMAIN: Every Stanford person has a Globus Identity in a common domain. This setting holds that domain. Right now it is stanford.edu.

Note

Stanford people who log in to Globus via Google will have an Identity username of the form sunetid@stanford.edu@accounts.google.com. This setting does not recognize those Globus Identities as Stanford people, so clients will need to take care to check that users are logging in via “Stanford University”, not via SAML.

Value Formats

For some environment variables, it is not safe storing the actual value in the environment variable. For this reason, all values are first parsed through Python’s urlparse function. If a recognized scheme is found, the value of the environment variable is taken as a URL to find the variable’s actual value.

The following schemes are recognized:

Files: If the scheme is file, the value is taken as a path to a file.

The format is file:path for paths relative to the current working directory, and file:/path for absolute paths.
Google Cloud Secrets: If the scheme is gcs, the value is taken from a Secret in Google Cloud Secret Manger.

The format is gcs://project/name?version. All three components are required, but you can use the special string “latest” to refer to the latest version of a specific Secret.

This required that SGGM is built with the gcs option.

.env File

In local installations, it is possible to put configuration into a local file, named .env. That file should be placed in the project’s root directory (whatever that means for your installation).

Here is an example dotenv file:

GLOBUS_PREFIX=DEV
GLOBUS_CLIENT_ID=67a9fc42-cbe6-11ec-9a66-bb2cbd847dfd
GLOBUS_CLIENT_SECRET=gcs://myproject/globus?latest

WORKGROUP_STEM=globus
WORKGROUP_API_TIER=UAT
WORKGROUP_API_CERT=file:workgroup.pem
WORKGROUP_API_KEY=gcs://myproject/workgroup?latest

The contents of the “dotenv” file are read when the program is first started, and will be overridden by variables that are set in the actual environment. In other words, if your dotenv file sets GLOBUS_PREFIX to “a”, and the OS environment sets it to “b”, the actual value used will be “b”.

Both the dotenv file and the OS environment are read at program start only, so a full program restart is needed in order to pick up changes.