Add new OpenID Connect client#

Gafaelfawr can also serve as an OpenID Connect server, allowing third-party applications running inside Phalanx and OpenID Connect clients outside of Phalanx environments to authenticate users in the same way that the Science Platform does.

Each OpenID Connect client of Gafaelfawr must be pre-registered and assigned a client ID and password. To complete an authentication, the client must authenticate with that client ID and password. See the Gafaelfawr documentation.

This page describes how to register a new client of Gafaelfawr. You will need the following information:

  • The Phalanx environment to which you’ll be adding the new client.

  • A short, human-readable name of the new client you’re adding.

  • The return URL to which the user will be sent after authentication.

Note

The instructions here are specific to SQuaRE-managed Phalanx environments. For other environments, you should update the oidc-clients portion of your static secrets. See Static secret sources for more information.

Add secret#

OpenID Connect clients are configured in the oidc-server-secrets key of the gafaelfawr secret. The value of this key is a JSON representation of all of the clients. It is therefore not maintained directly, but instead is generated from structured data stored elsewhere.

For SQuaRE-managed environments, “elsewhere” is the oidc-clients 1Password item. To add a new client, use the following process:

  1. Open 1Password. Go to the 1Password vault for static secrets for the Phalanx environment where you want to add an OpenID Connect client.

  2. Create or edit an item named oidc-clients. If it doesn’t already exist, create it as an item of type Server.

  3. Add a new section for the new client. Set the section title to a short, human-readable name for the OpenID Connect client. This name should be enough to tell someone looking at this secret what this client is used for.

  4. Add a text field to the new section. Change the label to id. Change the contents to random-id.clients.fqdn where the random ID is the results of os.urandom(16).hex() in Python and the FQDN is the FQDN of the environment. For example, de5dd2c1fbf648e11d50b6cf3aa72277.clients.data.lsst.cloud.

  5. Add a password field to the new section, changing the label as secret. You can let 1Password generate a random 20-character password if you want, or generate one of equivalent entropy however you choose.

  6. Add a final text field to the new section. Change the label to return_uri. Set the value to the return URL of the client. This should be provided by the OpenID Connect client and will be the URL to which the user is sent after authentication.

Share the secret with the client#

You will now need to convey the client ID and secret to the administrator of the OpenID Connect client. These are the id and secret values above. In the OpenID Connect protocol, they are called client_id and client_secret. They will need to configure their client software to use that ID and secret whenever performing an OpenID Connect authentication.

The easiest way to do this is often to create a separate 1Password secret and share it with the client.

Warning

DO NOT SHARE THE SECRET CREATED ABOVE. The client should not have access to the oidc-clients secret, since this contains secrets for other clients than their own.

  1. Go to the SQuaRE vault and create a new secret. Use a name like Gafaelfawr <client> OIDC, replacing <client> with a short human-readable name for the client. Use the Server item type.

  2. Add the information above. It’s best to call the fields client_id, client_secret, and return_uri, since those are the field names in the OpenID Connect standard and therefore what is usually used in software documentation. Enter the same information as above.

When sharing with someone who is managing multiple related clients, feel free to put all of the secrets in the same 1Password item in separate sections.

Now, you can create a one-time 1Password link for this secret and share it with the user in Slack or via email.

Configure Gafaelfawr#

If this is the first OpenID Connect client for Gafaelfawr, you will need to enable OpenID Connect server support. Do this by setting config.oidcServer.enabled to true in the Gafaelfawr values-environment.yaml file. See the Gafaelfawr documentation for more details.

If the purpose of this OpenID Connect client is to provide services to an IDAC or another external client that may need data rights information (see DMTN-253), ensure the configuration of the Gafaelfawr OpenID Connect server is correct and has a dataRightsMapping setting. See the Gafaelfawr documentation for more information.

Then, whether or not you needed to make configuration changes, you will need to sync secrets for this environment. Follow the normal process (Sync secrets for an environment) to do that.

Finally, you will need to restart Gafaelfawr to pick up the new secret. Do this by selecting Restart on the deployment in Argo CD (see Restarting a Deployment).

Note

Since this requires a Gafaelfawr restart, you will normally want to do this during a maintenance window for a production environment.