Questions about self-hosted grist and authentik with OIDC

I don’t even know where to start my questions :frowning:
Let me preface this long thread by saying that I have read Self-managed Grist - Grist Help Center and most related pages and am still struggling to understand the whole concept related to teams, organizations, users and authentication. I’d appreciate any clarifications even simple links to documentation I might have missed.
if anyone is using authentik + OIDC I’d be very happy to compare the settings in authentik. I had to guess at most of them.

My first try at a self-hosted grist instance was using authentik as a reverse proxy authentication. This worked perfectly fine. I also added these envs to my compose file:

- GRIST_DEFAULT_EMAIL=me@domain.tld

This way, as soon as I logged in via authentik, I was logged in into grist, with this single email address and had access to the admin panel and the team called “sheets”

My next try was to use authentik as an OIDC provider and then I also experimented by enabling multiple team sites.

This meant removing these two envs:

- GRIST_DEFAULT_EMAIL=me@mydomain.tld

And adding these:

- GRIST_OIDC_IDP_ISSUER=https://authentik.mydomain.tld/application/o/grist/.well-known/openid-configuration

This also worked in the sense that I could log into grist when logged into authentik. Since my authentik suer uses the same email as I used for GRIST_DEFAULT_EMAIL this worked just fine.

Now here are the confusing parts:

The login method does not reflect in my grist user profile:

I am now missing any link to the grist admin panel:

A new option to “add account” has appeared. To what/where do I add these accounts? To grist? To my team? This will not work anyway, since I guess it needs to be properly set up and redirected to some authentik signup page, which I haven’t done. Just asking for clarity’s sake.

Why does it say “legacy” next to the personal site? All I find about personal sites is this: Creating team sites - Grist Help Center - waht are they? Are they meant for sheets not shared with a team?

I just wanted to mention, that after signing out of both grist and authentik, and randomly clicking back and forth I somehow ended up on my grist instance as a guest. I didn’t even know this was possible, not sure how to get back here on purpose except for manually typing in the URL, but I am wondering what I can do as a guest? It looks like anyone can get here as a guest and add new docs?

@Ovi could you try setting this variable ^ again? Grist needs to know who the initial administrator is, and this is one way to set it.

For the question about guests, there’s a GRIST_ANON_PLAYGROUND that can control that functionality in multi-site operation. There’s also a GRIST_FORCE_LOGIN flag to require logins in all circumstances. See the README for details. I hope we’ll be surfacing and highlighting this behavior in the admin panel in the future, along with other security checks we’re adding now.

For the question about accounts. It is possible in a single browser session to log in as multiple accounts, and see all the sites you have access to. You need to be deep into Grist usage to care about this, and not likely to matter for you. From the README, I think you could hide the option by making GRIST_HIDE_UI_ELEMENTS contain multiAccounts, though I haven’t checked this.

Personal sites are a little space users have for documents that by default are private. The (Legacy) label worries me a bit. Thoughts @georgegevoian @jarek ?

That’s surprising. The default product shouldn’t be labeled as legacy, and I just checked it isn’t on a fresh account.

@Ovi could you check if you’ve set GRIST_DEFAULT_PRODUCT in your environment? The default behavior (when unset) is to use a plan type that has no limits or restrictions.


I just checked, and I did not set that variable mainly because I did not understand its explanation. I did not understand where to find names of PRODUCTS.

if set, this controls enabled features and limits of new sites. See names of PRODUCTS in Product.ts.

I will do that and try again, thanks for the idea.

I will also set:


If I understood their meaning correctly, the first option will disable the “playground” meaning no unwelcome guests can play with my grist instance and the second one will still allow me to use features like sharing docs publicly with guests without them having an account on my grist instance?

Btw. if you have any other suggestions, I am more than happy to wipe my instance and start fresh as I haven’t used it productively yet. As you can see I am still busy setting it up securely and properly.

I have two more questions, since it appears they have been overlooked earlier.

A) What happens when I use the above shown “add account”? Where does this account get created, and where does it get added? I mean is it tied to the authentication method I use? Will the account be on org, team site or workspace level?

Sorry about A) I missed you already addressing this. I’ll leave the question though people don’t get confused by the edit.

From the README, I think you could hide the option by making GRIST_HIDE_UI_ELEMENTS contain multiAccounts , though I haven’t checked this.

B) What exactly is the relationship between orgs, team sites, workspaces, and users in the self-hosted version?

Say I have a grist instance for personal use, and enable GRIST_SINGLE_ORG. Now there’s only one org, fine. If I give another person access via my OIDC login, he gets a user account on my grist instance in my org, right, or do I somehow need to create a grist account for him too?

Can we now both use our respective personal site, create teams and workspaces within those team sites as well as share access to documents/workspaces/teams independently?

That’s correct. Your setting for the GRIST_FORCE_LOGIN flag is already the default.

Broadly, your OIDC setup handles authentication, meaning it will work with users to verify their identity, and then vouch for that to Grist. Within Grist, you can control authorization, meaning: what does the user have the right to do. That’s where the team site sharing setup is useful:

In the team site sharing setup, it is possible to authorize a user that your OIDC setup would not allow through. In that case, your OIDC setup takes precedence, since the user will just never reach Grist.
It is also perfectly normal to have someone that your OIDC setup recognizes and authenticates, but they are not actually authorized to access a team site.
By default, users do not have access to team sites until it is specifically authorized (or some material on the site is shared in a public and list-able way). There are some reasonable feature requests around this. ANCT contributed a bulk-add-user UI to speed things up for themselves.

If GRIST_SINGLE_ORG is set, then no, that flag constrains Grist to have a single team site, so personal sites simply cannot be reached I believe.

Coming back to the relationship between orgs, team sites, workspaces, and users in the self-hosted version:

  • Orgs is an old synonym for team sites that survives in environment variable names and source code.
  • Workspaces are like non-nestable folders. They contain documents, and each workspace is in a team site.
  • For users, I’m hoping the sketch of the separation of authentication and authorization responsibilities above helps a bit. User authorization operates at the site, workspace, and doc level - each have a “Manage Users” option. There is default inheritance of authorization by nested resources such as docs within workspaces within team sites. This can be overridden.
    There’s not much that is special to say about authorization, the support documentation should hold for self-hosted in large part, apart from stray references to SaaS limits.

Well thanks for all that input and explanations. I tested 2 scenarios:


This worked out exactly as expected, the email provided via GRIST_DEFAULT_EMAIL had admin access.I was now running a single org or team site to which I could add workspaces and invite team members to give access to.
I logged in as a second user and as expected OIDC let me through, but grist said: you have no access.


The OIDC user with that email had admin access as expected. When I visit grist with this user it looks this way:

Seems fine to me as /o/docs/ looks like the default, the personal site works (no legacy shown any more) there is a workspace and a file I created.

Now switching to an anonymous browser with a second OIDC user:

Looks great, the workspace separation seems to work perfectly. Apparently any user I let through via OIDC, gets his own personal site?

Next I tried creating a team site. Seemed to work but threw an error:

Docker Logs show this error:

		 2024-06-07 10:11:58.596 - [33mwarn[39m: client error stack=TypeError: Cannot read properties of null (reading 'callback')                                │
│       at s.callAll (https://sheets.mydomain.tld/v/unknown/main.bundle.js:2:1057910)                                                                           │
│       at i.emit (https://sheets.mydomain.tld/v/unknown/main.bundle.js:2:1057437)                                                                              │
│       at S.setAndTrigger (https://sheets.mydomain.tld/v/unknown/main.bundle.js:2:1061444)                                                                     │
│       at S.set (https://sheets.mydomain.tld/v/unknown/main.bundle.js:2:1061361)                                                                               │
│       at u (https://sheets.mydomain.tld/v/unknown/main.bundle.js:2:856073), message=Cannot read properties of null (reading 'callback'), docId=undefined, p   │
│   age=https://sheets.mydomain.tld/o/docs/ws/2/, language=en-GB, platform=Win32, userAgent=Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHT   │
│   ML, like Gecko) Chrome/ Safari/537.36, org=docs, email=ovidiu@mydomain.tld, userId=5, altSessionId=uEmN66PXvMH7SBz9G6GDgB                          │

The created team site works as expected. My second user had no access, upon invite he did. After I removed his access, he gets this message when still trying to access that team site:

The add account link, leads to ma authentik OIDC, and back to the same error message as expected because I have not customized any user creation flows on authentik.

I think this link to “add account” as well as the one in the next screenshot which btw both users see, not only the admin account could be hidden as explained above although I haven’t tested it yet

GRIST_HIDE_UI_ELEMENTS contain multiAccounts


Perfect, I have figured everything out and it works as expected. Thanks everyone for your help. Btw. I will not use GRIST_SINGLE_ORG so that I can give i.e. my brother access to use my grist instance, while both having perfectly separate files/workspaces by default.

Bonus questions:

A) How do I delete a team site?
B) When creating a team site, I simply entered test as the domain and got an error. Entering testetesttest worked so there seems to be a minimum length check?

C) When managing a team, its URL still points towards even though it is working perfectly fien with ym own domain.