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”.

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> / http://localhost:8484
  • GRIST_OIDC_IDP_ISSUER = https://gitlab.com/.well-known/openid-configuration
  • GRIST_OIDC_IDP_SCOPES = "openid profile email"
  • GRIST_OIDC_IDP_CLIENT_ID = “…” (the client ID generated by Gitlab for the application)
  • GRIST_OIDC_IDP_CLIENT_SECRET = “…” (the client secret generated by Gitlab for the application)
  • GRIST_OIDC_IDP_SKIP_END_SESSION_ENDPOINT = true (Gitlab don’t propose end_session_endpoint)

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> / http://localhost:8484
  • GRIST_OIDC_IDP_ISSUER = https://<your-auth0-app-domain>
  • GRIST_OIDC_IDP_SCOPES = "openid profile email"
  • GRIST_OIDC_IDP_CLIENT_ID = “…” (the client ID generated by Auth0 for the application)
  • GRIST_OIDC_IDP_CLIENT_SECRET = “…” (the client secret generated by Auth0 for the application)

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> / http://localhost:8484
  • GRIST_OIDC_IDP_ISSUER = https://<keycloak-domain>/realms/<your-realm>
  • GRIST_OIDC_IDP_SCOPES = "openid profile email"
  • GRIST_OIDC_IDP_CLIENT_ID = “…” (the ID you chose for the Keycloak client)
  • GRIST_OIDC_IDP_CLIENT_SECRET = “…” (the client secret generated by Keycloak retrieved earlier)