SAML#

Configuration for SAML, useful for enterprise single-sign-on logins. A good informative overview of SAML is at https://www.okta.com/integrate/documentation/saml/

Note:

  • SP is “Service Provider”, in our case, the Grist application.
  • IdP is the “Identity Provider”, somewhere users log into, e.g. Okta or Google Apps.

We will need one or more certificates from the IdP, in PEM format. This is a public key that Grist will use to check messages from the IdP are legit.

We will need a private and public key pair for Grist to use when communicating with the IdP. The IdP will need to know the public key for Grist, to check messages from Grist are legit.

Expected environment variables:

  • GRIST_SAML_SP_HOST - this is just the base URL of the Grist site, such as https://<grist-domain> (when SAML is active, there will be a /saml/assert endpoint available here for implementing the protocol).
  • GRIST_SAML_SP_KEY - path to a file with our private key, in PEM format. This is the private key of the key pair created for Grist to use with the IdP.
  • GRIST_SAML_SP_CERT - path to file with our public key, in PEM format. This is the public key of the key pair created for Grist to use with the IdP. It is not the public key/certificate of the IdP.
  • GRIST_SAML_IDP_LOGIN - login url to redirect user to for log-in.
  • GRIST_SAML_IDP_LOGOUT - logout URL to redirect user to for log-out.
  • GRIST_SAML_IDP_SKIP_SLO - if set and non-empty, don’t attempt “Single Logout” SAML flow, but simply redirect to GRIST_SAML_IDP_LOGOUT after clearing session. Whether this flow is possible will depend on the IdP.
  • GRIST_SAML_IDP_CERTS - comma-separated list of paths for certificates from the IdP, in PEM format. This is not the private or public key created for Grist.
  • GRIST_SAML_IDP_UNENCRYPTED - if set and non-empty, allow unencrypted assertions, relying on https for privacy.

Example: Auth0#

For example, when running on localhost and http, settings that work with the Auth0 SAML IdP are:

  • GRIST_SAML_IDP_SKIP_SLO not set
  • GRIST_SAML_SP_HOST = http://localhost:8484
  • GRIST_SAML_IDP_UNENCRYPTED = 1
  • GRIST_SAML_IDP_LOGIN = https://...auth0.com/samlp/xxxx
  • GRIST_SAML_IDP_LOGOUT = https://...auth0.com/samlp/xxxx (these are same for Auth0)
  • GRIST_SAML_IDP_CERTS = .../auth0.pem (downloaded per Auth0 instructions)
  • GRIST_SAML_SP_KEY = .../saml.pem (created)
  • GRIST_SAML_SP_CERT = .../saml.crt (created)

When used with docker, make sure that the key and certificate files are accessible within a shared volume. The key/cert pair were created following instructions here:

In your Auth0 settings also make sure that:

  • The “Application Callback URL” is set to https://<grist-domain>/saml/assert.

Example: Authentik#

In Authentik, add a Provider called Grist with:

  • ACS URL: https://<grist-domain>/saml/assert
  • Set Service provider binding to Post
  • Select or add a signing certificate. You’ll need to download this to use as GRIST_SAML_IDP_CERTS in Grist configuration.
  • Add a verification certificate. This will be the public part of a key pair your create for GRIST_SAML_SP_KEY/GRIST_SAML_SP_CERT in Grist configuration.

Then, still in Authentik, add an Application also called Grist (I’m not very imaginative) that:

  • Uses the Grist Provider.
  • Has Launch URL set to https://<grist-domain>.

The Grist settings follow the same pattern as for Auth0. The login and logout URLs with Authentik at the time of writing look like:

  • GRIST_SAML_IDP_LOGIN = https://...authentik.../application/saml/grist/sso/binding/redirect/
  • GRIST_SAML_IDP_LOGOUT = https://...authentik.../if/session-end/grist/

Troubleshooting#

We expect IdP to provide us with name_id, a unique identifier for the user. We also use optional attributes for the user’s name, for which we accept any of:

  • FirstName
  • LastName
  • http://schemas.xmlsoap.org/ws/2005/05/identity/claims/givenname
  • http://schemas.xmlsoap.org/ws/2005/05/identity/claims/surname

You may need to tweak your IdP’s defaults to match Grist’s expectations.