Documentation of authentication workflows

[kcranston]

To help debug #61 (and future authentication issues), we want documentation of the authentication workflows:

• default authentication workflow using OIDC clients in CILogon
• the long-lived token workflow used by submission system

Will likely require input from @joneubank but we can put together a draft PR first and then tag you with specific questions.

[daisieh]

I'm just going to start documenting here and then we can decide where this goes later.

• An authz service has a single CILogon/COmanage instance, specified in the configuration as PCGL_ISSUER.
• There is a default OIDC client and secret set up in the environment, either in the secrets.sh file or in the argoCI configuration, listed as PCGL_CLIENT_ID and PCGL_CLIENT_SECRET. The user gets the access token from the CILogon server in the usual way, as described here: https://www.cilogon.org/oidc#h.p_KQlPDWoD9pgr
• A service that needs tokens with different longevity parameters, such as using a refresh token as a long-lived token, can set up its own OIDC client in COManage.
  • When the service is registered with authz (using the POST /service endpoint), the specific client ID and secret can be specified in the body. The body also needs to specify if the tokens that are being used by the service are going to be access tokens or refresh tokens.
  • The service can then use that OIDC client to get tokens (using the usual method). The service then needs to use the POST /service/{service_id}/verify endpoint to get a service token and pass that in the X-Service-Token header, along with the user token, to authorize the user.