OpenID Connect#

Configuration for OIDC, useful for organization single-sign-on logins. A good informative overview of OIDC is at https://developer.okta.com/blog/2019/10/21/illustrated-guide-to-oauth-and-oidc

Note:

  • SP is “Service Provider”, in our case, the Grist application.
  • IdP is the “Identity Provider”, somewhere users log into, e.g. Keycloak, Authelia, …
  • OIDC is the acronym for OpenID Connect

Expected environment variables:

  • GRIST_OIDC_IDP_ISSUER - the issuer URL for the IdP, passed to node-openid-client, see: https://github.com/panva/node-openid-client/blob/a84d022f195f82ca1c97f8f6b2567ebcef8738c3/docs/README.md#issuerdiscoverissuer. This variable turns on the OIDC login system.
  • GRIST_OIDC_IDP_CLIENT_ID - the client ID for the application, as registered with the IdP.
  • GRIST_OIDC_IDP_CLIENT_SECRET - the client secret for the application, as registered with the IdP.
  • GRIST_OIDC_IDP_SCOPES (optional) - the scopes to request from the IdP, as a space-separated list. Defaults to "openid email profile".
  • GRIST_OIDC_SP_HOST (optional) - this is just the base URL of the Grist site, such as https://<grist-domain> (when OIDC is active, there will be a /oauth2/callback endpoint available here for implementing the protocol). If omitted, APP_HOME_URL will be used.
  • GRIST_OIDC_IDP_END_SESSION_ENDPOINT (optional) - If set, overrides the IdP’s end_session_endpoint with an alternative URL to redirect user upon logout (for an IdP that has a logout endpoint but does not support the OIDC RP-Initiated Logout specification).
  • GRIST_OIDC_IDP_SKIP_END_SESSION_ENDPOINT (optional) - If set to “true”, on logout, there won’t be any attempt to call the IdP’s end_session_endpoint (the user will remain logged in in the IdP). You should only set it to “true” if the IdP does not provide such endpoint (for example if you use Gitlab).
  • GRIST_OIDC_SP_PROFILE_NAME_ATTR (optional) - The key of the attribute to use for the user’s name. If omitted, the name will be the concatenation of given_name + family_name if they are provided or the name attribute otherwise.
  • GRIST_OIDC_SP_PROFILE_EMAIL_ATTR (optional) - The key of the attribute to use for the user’s email. Defaults to “email”.
  • GRIST_OIDC_IDP_ENABLED_PROTECTIONS (optional) - A comma-separated list of protections to enable. Supported values are PKCE, STATE, NONCE. Defaults to PKCE,STATE, which is the recommended settings. It’s highly recommended that you enable STATE, and at least one of PKCE or NONCE, depending on what your OIDC provider requires/supports.
  • GRIST_OIDC_IDP_ACR_VALUES (optional) - A space-separated list of ACR values to request from the IdP.
  • GRIST_OIDC_IDP_EXTRA_CLIENT_METADATA (optional) - A JSON object with extra client metadata to pass to openid-client. Be aware that setting this object may override any other values passed to the openid client. More info: https://github.com/panva/node-openid-client/tree/main/docs#new-clientmetadata-jwks-options

Example: Gitlab#

See how to create an OAuth2 application in Gitlab in this documentation. While creating the application, set the redirect URI to https://<grist-domain>/oauth2/callback (or http://localhost:8484/oauth2/callback if tested locally, change 8484 to the port you listen on) and select the scopes you will specify in GRIST_OIDC_IDP_SCOPES.

Once the application is set up, start Grist with these settings:

GRIST_OIDC_SP_HOST=https://<grist-domain> # or http://localhost:8484
GRIST_OIDC_IDP_ISSUER=https://gitlab.com/.well-known/openid-configuration
GRIST_OIDC_IDP_SCOPES=openid profile email

# the client ID generated by Gitlab for the application
GRIST_OIDC_IDP_CLIENT_ID=...

# the client secret generated by Gitlab for the application
GRIST_OIDC_IDP_CLIENT_SECRET=...

# Gitlab doesn't propose `end_session_endpoint`
GRIST_OIDC_IDP_SKIP_END_SESSION_ENDPOINT=true

This format is suitable for an .env file or similar. From a shell invocation, remember to quote values with spaces, such as GRIST_OIDC_IDP_SCOPES="openid profile email".

Example: Auth0#

Create an application in Auth0 as explained in this documentation (you can select the app type named Regular Web Applications). Once the application is created, ensure to add at least the following configuration for the app:

  • Allowed callback URLs: https://<grist-domain>/oauth2/callback
  • Allowed logout URLs: http://<grist-domain>/* (you can also replace the wildcard with the whole path in order to be stricter)

Then you should be able to start Grist with the following settings:

GRIST_OIDC_SP_HOST=https://<grist-domain> # or http://localhost:8484
GRIST_OIDC_IDP_ISSUER=https://<your-auth0-app-domain>
GRIST_OIDC_IDP_SCOPES=openid profile email

# the client ID generated by Auth0 for the application
GRIST_OIDC_IDP_CLIENT_ID=...

# the client secret generated by Auth0 for the application
GRIST_OIDC_IDP_CLIENT_SECRET=...

This format is suitable for an .env file or similar. From a shell invocation, remember to quote values with spaces, such as GRIST_OIDC_IDP_SCOPES="openid profile email".

Example: Keycloak#

First of all, set up Keycloak as explained in one of these “Getting started” guides: https://www.keycloak.org/guides#getting-started.

Once keycloak is set up with a realm and a user, create a new client with the following configuration:

  • Client type: OpenID Connect
  • Authentication flow: Standard Flow
  • Root URL: https://<grist-domain>
  • Valid redirect URIs: /oauth2/callback
  • Valid post logout redirect URIs: /* (you can also replace the wildcard with the whole path in order to be stricter)

Submit your settings and go to the Credentials tab to retrieve the client secret.

Then, you can start Grist with the following configuration:

GRIST_OIDC_SP_HOST=https://<grist-domain> # or http://localhost:8484
GRIST_OIDC_IDP_ISSUER=https://<keycloak-domain>/realms/<your-realm>
GRIST_OIDC_IDP_SCOPES=openid profile email

# the ID you chose for the Keycloak client
GRIST_OIDC_IDP_CLIENT_ID=...

# the client secret generated by Keycloak retrieved earlier
GRIST_OIDC_IDP_CLIENT_SECRET=...

This format is suitable for an .env file or similar. From a shell invocation, remember to quote values with spaces, such as GRIST_OIDC_IDP_SCOPES="openid profile email".