GristConnect#

Discourse is popular forum software made to be integrated with many sites (including our own). It is annoying if users need a login for a forum that is separate to their login on the rest of a site. The protocol Discourse created for solving this is quite well done and is called DiscourseConnect. We decided to have Grist support the same protocol, so any software that has plugins for letting Discourse use its logins (such as WordPress) can also let Grist use its logins. This isn’t an official standard so we called our implementation of it “GristConnect” rather than “DiscourseConnect”.

Setting up GristConnect requires some settings for Grist, and a plugin or custom coding for your site or SSO. The Grist settings are as follows:

  • GRIST_CONNECT_URL: setting this environment variable will enable GristConnect. It should be an URL address of an external site where users will be redirected on login/signup request.
  • GRIST_CONNECT_SECRET: (required) a secret key, used to sign (hash) query parameters in URLs used during login flow.
  • GRIST_CONNECT_LOGOUT_URL: (optional) an URL address users will be redirected to after signing out. By default - Grist’s existing sign-out page.
  • GRIST_CONNECT_ENDPOINT: (optional) a callback endpoint exposed by Grist where users should be redirected to after a successful login attempt in the external Identity Provider site (default value: /connect/login).

For your site or SSO, you may find that the software you use supports DiscourseConnect, in which case you can enable that and coordinate with the Grist settings. Otherwise, here are the exact details of what needs to happen:

  • When users try to login into Grist, they are redirected to a GRIST_CONNECT_URL with signed query parameters, for example, https://auth-provider.example.com?sso=PAYLOADBASE64&sig=cAlculateDHash
  • The payload is a Base64 encoded query string containing:
    • nonce - a one time token generated by Grist
    • return_url - a URL to redirect the user to after successful login - this always will be set to the full Grist URL for GRIST_CONNECT_ENDPOINT.
  • User should sign in using the GRIST_CONNECT_URL login screen.
  • An external provider should create a new url-encoded payload with the following parameters
    • nonce - (required) a token that was sent from Grist
    • external_id - (required) any string that is unique to the user and will never change
    • email - (required) a valid user email
    • name - (required) a user name
    • avatar_url - (optional) an URL to user’s profile photo. Note that Grist will also accept picture parameter for the same purpose.
    • This payload should be base64 encoded and properly escaped to be a valid query string.
  • A provider should calculate a HMAC_SHA256 hash of a payload.
  • A user should redirect to the GRIST_CONNECT_ENDPOINT endpoint with a signed query string parameters, for example, https://grist.customhost.com/connect/login?sso=ENCODEDPAYLOD&sig=HASH
  • Grist will create a new user or update an existing one. Users will be identified by external_id parameter.
  • The user will be signed into Grist.