grove
Contact us
Documentation menu

Using Grove

OverviewSearch syntaxCode navigationCommit and diff searchSaved searches and contextsAI assistants (MCP)Browser extension

Running Grove

DeploymentConfigurationAuthenticationCode hosts

Authentication

Users sign in with your OIDC provider or through an authenticating reverse proxy. Scripts, CI jobs and AI assistants use API keys or service tokens. The modes combine: for example OIDC for people and service tokens for agents.

OIDC / OAuth 2.1

Set OIDC_PROVIDER_URL, OIDC_CLIENT_ID and OIDC_CLIENT_SECRET to enable browser sign-in. Any OIDC-compliant provider works. Sessions are stored server-side; users can see and end their sessions under Settings → Sessions.

PUBLIC_URL=https://grove.example.com
OIDC_PROVIDER_URL=https://accounts.google.com
OIDC_CLIENT_ID=your-client-id
OIDC_CLIENT_SECRET=your-client-secret

PUBLIC_URL is required with OIDC. The redirect URI Grove registers is built from it:

https://grove.example.com/auth/callback

Register this exact URI in your provider’s OAuth app settings.

Account matching

Grove identifies an OIDC user by the ID token’s issuer (iss) and subject (sub); each new pair gets its own account on first sign-in. The email claim is optional and only used for display and saved-search notifications. It never selects an account, so two identities with the same email get separate accounts. An email the provider marks as email_verified: false is not stored.

Proxy-header users are identified by the email header and get accounts separate from OIDC users, even with the same email.

First superuser

Sign in once, then promote that account from the server’s command line:

./server createsuperuser                          # binary
docker exec -it <container> ./server createsuperuser  # Docker image

It asks for the account’s email or user ID. If several accounts share the email, it lists their IDs to choose from. After that, superusers can promote others under Settings → Users.

Google

  1. Go to Google Cloud Console → APIs & Services → Credentials
  2. Click Create credentials → OAuth 2.0 Client ID
  3. Application type: Web application
  4. Add https://grove.example.com/auth/callback to Authorized redirect URIs
  5. Copy the client ID and secret
OIDC_PROVIDER_URL=https://accounts.google.com
OIDC_CLIENT_ID=123456789-abc.apps.googleusercontent.com
OIDC_CLIENT_SECRET=GOCSPX-…

To restrict login to a specific Google Workspace domain, you can enforce this at the provider level via domain restriction in the OAuth consent screen.

GitHub

GitHub sign-in is OAuth, not OIDC. Put an OIDC bridge such as Dex with its GitHub connector in front and configure Dex as Grove’s provider.

Microsoft Entra ID (Azure AD)

  1. Go to Azure Portal → Microsoft Entra ID → App registrations → New registration
  2. Name: anything (e.g. “Grove”)
  3. Supported account types: Accounts in this organizational directory only
  4. Redirect URI: Web — https://grove.example.com/auth/callback
  5. After creating, go to Certificates & secrets → New client secret and copy the value
  6. Note your Application (client) ID and Directory (tenant) ID
OIDC_PROVIDER_URL=https://login.microsoftonline.com/<tenant-id>/v2.0
OIDC_CLIENT_ID=<application-client-id>
OIDC_CLIENT_SECRET=<client-secret-value>

Replace <tenant-id> with your Azure tenant ID (a UUID).

To show users’ emails and send them saved-search notifications, add the email optional claim to the ID token under Token configuration. Entra only fills it for users whose mail attribute is set.

Self-hosted GitLab as OIDC provider

  1. Go to GitLab → Admin Area → Applications → New application
  2. Redirect URI: https://grove.example.com/auth/callback
  3. Scopes: openid, email, profile
  4. Copy the Application ID and Secret
OIDC_PROVIDER_URL=https://gitlab.example.com
OIDC_CLIENT_ID=<application-id>
OIDC_CLIENT_SECRET=<secret>

API keys

API keys let scripts, CI pipelines and MCP clients act as the user who created them, without the browser flow.

  1. Go to Settings → API keys (or use Set me up in the top bar).
  2. Create a key, give it a name and copy the value.

Keys look like grove_<64 hex characters>. Grove stores only a hash and shows the key once. The list shows when each key was last used; delete a key to revoke it. Superusers can also create and revoke keys for other users.

Service tokens

Service tokens are read-only credentials that don’t belong to a user, for CI jobs and shared agents. Create one under Settings → API keys → Service tokens, optionally with an expiry date. They are accepted wherever API keys are, including MCP.

Using a key

Pass the key as a Bearer token:

curl -H "Authorization: Bearer grove_your_key_here" \
  https://grove.example.com/graphql \
  -d '{"query":"{ repositories(page:0,pageSize:5) { nodes { path } } }"}'

See AI assistants (MCP) for using keys with MCP clients.

Proxy headers

If you run Grove behind a reverse proxy that authenticates users (e.g. Authentik, Authelia, oauth2-proxy), you can forward identity via headers instead of configuring OIDC directly in Grove.

AUTH_PROXY_HEADER_USER=X-Auth-User
AUTH_PROXY_HEADER_EMAIL=X-Auth-Email

Both variables must be set. Grove reads the username from X-Auth-User and the email from X-Auth-Email on every request. The proxy is responsible for verifying identity before the request reaches Grove.

Only enable proxy auth if Grove is not publicly reachable — anyone who can send requests directly to Grove can spoof these headers.

Public instances

Set PUBLIC_INSTANCE=true to let anyone search and read code without signing in, including over MCP. Settings, saved searches and API keys still need an account.

Development / no auth

Set INSECURE_ALLOW_ALL=true to disable all authentication checks. Every request is treated as authenticated. Never use this in production.

Cookies over HTTPS

When TLS ends at a proxy, set COOKIE_SECURE=true (or an https:// PUBLIC_URL) so the session cookie is never sent over plain HTTP.