diff --git a/help/install/oidc.md b/help/install/oidc.md new file mode 100644 index 000000000..62c659e21 --- /dev/null +++ b/help/install/oidc.md @@ -0,0 +1,72 @@ +OpenID Connect {: .tag-core .tag-ee } +==== + +Configuration for OIDC, useful for organization single-sign-on logins. +A good informative overview of OIDC is at + +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 accronym for OpenID Connect + +Expected environment variables: + + * `GRIST_OIDC_SP_HOST` - this is just the base URL of the Grist site, + such as `https://` (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_ISSUER` - the issuer URL for the IdP, passed to node-openid-client, see: . + **This variable turns on the OIDC login system.** + * `GRIST_OIDC_IDP_SCOPES` - the scopes to request from the IdP, as a space-separated list. Defaults to `"openid email profile"`. + * `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. + +## Example: Gitlab + +See [how to create an OAuth2 application in Gitlab in this documentation](https://docs.gitlab.com/ee/integration/oauth_provider.html). The redirection URI should be `https:///oauth2/callback` (or `http://localhost:8484/oauth2/callback` if tested locally, change `8484` to the port you listen on). + +Once the application is set up and start grist with these settings: + + - `GRIST_OIDC_SP_HOST` = `https://` / `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) + +## 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 created, ensure to add at least the following configuration for the app: + + * Allowed callback URLs: `https:///oauth2/callback` + * Allowed logout URLs: `http:///*` (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://` / `http://localhost:8484` + - `GRIST_OIDC_IDP_ISSUER` = `https://` + - `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 Auht0 for the application) + +## Example: Keycloak + +First of all, setup Keycloak as explained in one of these "Getting started" guides: . + +Once keycloak is setup, 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://` + - 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://` / `http://localhost:8484` + - `GRIST_OIDC_IDP_ISSUER` = `https:///realms/` + - `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 Keycload retrieved earlier) diff --git a/help/self-managed.md b/help/self-managed.md index d1d74ed2c..1abe4b33b 100644 --- a/help/self-managed.md +++ b/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. diff --git a/mkdocs.yml b/mkdocs.yml index 8045fc0e5..d6a6bed38 100644 --- a/mkdocs.yml +++ b/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