Document configuring an endpoint with Globus OIDC

docs/endpoints/endpoints.rst

@@ -888,6 +888,7 @@ following ``configure`` subcommand options:
      minute, even though it is possible to set required authorizations for high
      assurance policies to smaller time intervals.
 
+.. _apply-existing-auth-policy:
 
 Apply an Existing Authentication Policy
 ---------------------------------------

docs/endpoints/multi_user.rst

@@ -585,6 +585,70 @@ authentications.
 Please refer to :ref:`auth-policies` for more information.
 
 
+With Globus OIDC
+----------------
+
+Administrators can create a custom OIDC server by following the `Globus OIDC guide`__.
+(Note that this requires an existing Globus Connect Server endpoint.) This OIDC server
+can then be combined with Globus Auth Policies to authenticate users on a multi-user
+endpoint.
+
+__ https://docs.globus.org/globus-connect-server/v5.4/globus-oidc-guide/
+
+.. note::
+
+   When configuring a custom Globus OIDC server, administrators have the choice between
+   a custom domain or a sub-domain under the Globus Connect Server endpoint, e.g.
+   ``my-gcs-oidc.my-institution.edu`` or ``identity.00000000-1111-2222-3333-444444444444.globuscs.info``.
+   This section uses ``<OIDC-domain>`` as a placeholder for either option.
+
+When configuring a new multi-user endpoint, use the ``--allowed-domains`` option to
+restrict access to users authenticated via the OIDC server:
+
+.. code-block:: console
+
+   $ globus-compute-endpoint configure \
+       --allowed-domains "<OIDC-domain>" \
+       my_oidc_compute_endpoint
+
+To apply the same restriction to an existing multi-user endpoint, create an
+authentication policy using either the `Globus Auth API <https://docs.globus.org/api/auth/reference/#create_policy>`_
+or the `Globus SDK <https://globus-sdk-python.readthedocs.io/en/stable/services/auth.html#globus_sdk.AuthClient.create_policy>`_,
+with ``domain_constraints_include`` set to something like ``[<OIDC-domain>]``.
+Then, :ref:`add that policy to the endpoint config <apply-existing-auth-policy>`.
+
+Finally, create an :ref:`identity mapping configuration <example-idmap-config>` so
+OIDC-authenticated users can run tasks on the endpoint. The following config maps
+identities of the form ``user@<OIDC-domain>`` to the local username ``user`` (which
+must exist on the endpoint host system):
+
+.. code-block:: json
+   :caption: ``identity_mapping.json``
+   :emphasize-lines: 8
+
+   [
+      {
+         "comment": "Map OIDC identities to local usernames",
+         "DATA_TYPE": "expression_identity_mapping#1.0.0",
+         "mappings": [
+            {
+               "source": "{username}",
+               "match": "(.*)@<OIDC-domain>",
+               "output": "{0}"
+            }
+         ]
+      }
+   ]
+
+Save this configuration to a file (e.g., ``identity_mapping.json``) and reference it in
+the endpoint's ``config.yaml`` under the ``identity_mapping`` key:
+
+.. code-block:: yaml
+   :caption: ``config.yaml``
+
+   identity_mapping: /path/to/identity_mapping.json
+
+
 Administrator Quickstart
 ========================