Add OIDC documentation (#285)

help/install/oidc.md

@@ -0,0 +1,79 @@
+OpenID Connect {: .tag-core .tag-ee }
+====
+
+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_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](https://docs.gitlab.com/ee/integration/oauth_provider.html). 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](https://auth0.com/docs/get-started/auth0-overview/create-applications) (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)

help/self-managed.md

@@ -34,12 +34,12 @@ sections. For clarity, the sections are tagged
 with which flavor they apply to, for example:
 {: .tag-core .tag-ee }
 
-The full source code for Grist Core is always available at 
+The full source code for Grist Core is always available at
 [github.com/gristlabs/grist-core](https://github.com/gristlabs/grist-core/)
 and is under an Apache-2.0 license. You may use and redistribute Core
 freely, under the terms of the free software license.
 The full source for Grist Enterprise
-is also available, at 
+is also available, at
 [github.com/gristlabs/grist-ee](https://github.com/gristlabs/grist-ee/),
 under a proprietary license that does not grant any automatic
 rights to use or redistribute the software. You can evaluate Enterprise
@@ -82,7 +82,7 @@ If using some other tool or service, here are the important points:
    will populate it. Without this volume, nothing you do will be stored long-term.
  * Port `8484` on the container needs to be exposed. This can be changed
    if you also set the `PORT` environment variable for the container.
- * The environment variable `GRIST_SESSION_SECRET` should be set 
+ * The environment variable `GRIST_SESSION_SECRET` should be set
    to something secret for the container.
 
 Installed this way, Grist is accessible only to you. Typically you want to
@@ -94,7 +94,7 @@ take at least the following steps:
     so you can collaborate live with others.
   * Enable an authentication method so users can log in. Often you'll want
     to hook Grist up to an "SSO" (Single Sign-On) service you already use.
-	We support some very 
+	We support some very
     [general authentication methods](self-managed.md#how-do-i-set-up-authentication) that cover many cases,
 	and a [special authentication method](self-managed.md#are-there-other-authentication-methods) for custom cases.
   * Consider enabling [snapshot support](self-managed.md#how-do-i-set-up-snapshots) if you want Grist to handle document backups.
@@ -118,7 +118,7 @@ you can create a document and then check that this formula
 gives an empty result:
 
 ```
-import glob 
+import glob
 glob.glob('/etc/*')
 ```
 
@@ -139,11 +139,11 @@ docker run ...
 ```
 
 You will need to place a "reverse proxy" in front of Grist to
-handle "ssl termination" (decrypting encypted traffic) using 
+handle "ssl termination" (decrypting encypted traffic) using
 a certificate that establishes ownership of the site. If you don't
 know what this means, you could try using the
 [Grist Omnibus](https://github.com/gristlabs/grist-omnibus) which
-packages Grist with a reverse proxy that will 
+packages Grist with a reverse proxy that will
 use [Let's Encrypt](https://letsencrypt.org/) to get a certificate
 for you automatically.
 
@@ -173,10 +173,11 @@ you don't need.
 ### How do I set up authentication? {: .tag-core .tag-ee }
 
 Authentication can be set up in many ways for Grist Core and Enterprise, using
-SAML or forwarded headers. Between the two, many popular SSOs can be hooked
+SAML, OpenID Connect or forwarded headers. Between the two, many popular SSOs can be hooked
 up, such as Google or Microsoft sign-ins.
 
   * [SAML](install/saml.md).
+  * [OpenID Connect](install/oidc.md)
   * [Forwarded headers](install/forwarded-headers.md).
 
 For any authentication method, you may want to also consider setting the
@@ -205,7 +206,7 @@ Activation keys are used to run Grist Enterprise after a trial period
 of 30 days has expired.
 Get an activation key by [signing up for Grist Enterprise](https://www.getgrist.com/pricing).
 You don't need an activation key to run Grist Core.
- 
+
 Place the contents of your activation key in an environment variable called
 `GRIST_ACTIVATION`, or place it in a directory available to Grist and
 provide the full path to the file with the environment variable
@@ -317,7 +318,7 @@ format as our `manifest.json`.
 
 ### How do I set up email notifications? {: .tag-ee }
 
-In Grist SaaS, we send emails such as invitations to share a 
+In Grist SaaS, we send emails such as invitations to share a
 document using [SendGrid](https://sendgrid.com/).
 The same mechanism is available in Grist Enterprise. There is
 not yet an equivalent in Grist Core.

mkdocs.yml

@@ -78,6 +78,7 @@ nav:
   - Self-Managed:
     - Self-managed Grist: self-managed.md
     - SAML: install/saml.md
+    - OIDC: install/oidc.md
     - Forwarded headers: install/forwarded-headers.md
     - Cloud storage: install/cloud-storage.md
     - GristConnect: install/grist-connect.md
@@ -90,16 +91,16 @@ nav:
     - 2023/10: newsletters/2023-10.md
     - 2023/09: newsletters/2023-09.md
     - 2023/08: newsletters/2023-08.md
-    - 2023/07: newsletters/2023-07.md  
-    - 2023/06: newsletters/2023-06.md   
-    - 2023/05: newsletters/2023-05.md   
-    - 2023/04: newsletters/2023-04.md     
-    - 2023/03: newsletters/2023-03.md      
-    - 2023/02: newsletters/2023-02.md      
-    - 2023/01: newsletters/2023-01.md       
-    - 2022/12: newsletters/2022-12.md    
-    - 2022/11: newsletters/2022-11.md     
-    - 2022/10: newsletters/2022-10.md    
+    - 2023/07: newsletters/2023-07.md
+    - 2023/06: newsletters/2023-06.md
+    - 2023/05: newsletters/2023-05.md
+    - 2023/04: newsletters/2023-04.md
+    - 2023/03: newsletters/2023-03.md
+    - 2023/02: newsletters/2023-02.md
+    - 2023/01: newsletters/2023-01.md
+    - 2022/12: newsletters/2022-12.md
+    - 2022/11: newsletters/2022-11.md
+    - 2022/10: newsletters/2022-10.md
     - 2022/09: newsletters/2022-09.md
     - 2022/08: newsletters/2022-08.md
     - 2022/07: newsletters/2022-07.md
@@ -145,7 +146,7 @@ nav:
       - Reference Columns Guide: examples/2021-05-reference-columns.md
       - Summary Tables Guide: examples/2021-06-timesheets.md
       - Time and User Stamps: examples/2021-07-auto-stamps.md
-      - Restrict Duplicate Records: examples/2023-01-acl-memo.md   
+      - Restrict Duplicate Records: examples/2023-01-acl-memo.md
       - Proposals & Contracts: examples/2023-07-proposals-contracts.md
   - Reference:
     - Shortcuts: keyboard-shortcuts.md