OIDC Authentication

Let users log in through an OpenID Connect provider on a Kubernetes deployment.

OIDC login is handled by the web service (the authentication module) inside every Ayakaleaf Pro pod. It has no background job and no separate pod. The provider side (client, redirect URIs, admin claim) is the same as on the Toolkit, so set up your OpenID Provider (OP) with OIDC Authentication first, then put the values into Kubernetes as below.

Where things run

Service	web, in every Ayakaleaf Pro pod; settings are read when web starts
Pod → OP	OVERLEAF_OIDC_TOKEN_URL and OVERLEAF_OIDC_USER_INFO_URL, at every login
Browser → OP	OVERLEAF_OIDC_AUTHORIZATION_URL, and OVERLEAF_OIDC_LOGOUT_URL on logout
OP → Overleaf	none: the OP only redirects the browser back
Login state	the session in Redis, shared by all replicas
Periodic jobs	none

Configuration

1. Register Overleaf at the OP

   Allow these addresses in your OP, built from OVERLEAF_SITE_URL:

   Purpose	URI
   Redirect URI (login)	${OVERLEAF_SITE_URL}/oidc/login/callback
   Post-logout redirect URI	${OVERLEAF_SITE_URL}
   Post-logout redirect URI, after linking an existing account	${OVERLEAF_SITE_URL}/user/settings

   Find the five URLs in the OP’s discovery document as described in Finding the values with the discovery document.

2. Add the settings to the ConfigMap

   Add to overleaf-env (30-config.yaml, or 60-config.yaml for several replicas):

   30-config.yaml (additions)

     EXTERNAL_AUTH: oidc
     OVERLEAF_OIDC_PROVIDER_ID: authentik
     OVERLEAF_OIDC_PROVIDER_NAME: Authentik
     OVERLEAF_OIDC_IDENTITY_SERVICE_NAME: Log in with Authentik
     OVERLEAF_OIDC_ISSUER: https://authentik.example.com/application/o/overleaf/
     OVERLEAF_OIDC_AUTHORIZATION_URL: https://authentik.example.com/application/o/authorize/
     OVERLEAF_OIDC_TOKEN_URL: https://authentik.example.com/application/o/token/
     OVERLEAF_OIDC_USER_INFO_URL: https://authentik.example.com/application/o/userinfo/
     OVERLEAF_OIDC_LOGOUT_URL: https://authentik.example.com/application/o/overleaf/end-session/
     OVERLEAF_OIDC_CLIENT_ID: <Client ID>
     OVERLEAF_OIDC_USER_ID_FIELD: username
     OVERLEAF_OIDC_IS_ADMIN_FIELD: groups
     OVERLEAF_OIDC_IS_ADMIN_FIELD_VALUE: Admins
     OVERLEAF_OIDC_UPDATE_USER_DETAILS_ON_LOGIN: "true"
   

   EXTERNAL_AUTH takes a space-separated list, for example ldap oidc. See Environment Variables for every OVERLEAF_OIDC_* setting; all of them go into the ConfigMap except the client secret.

   Quote "true" and "false": a ConfigMap only holds strings. A key set to "" is not the same as a missing key: OVERLEAF_OIDC_ALLOWED_EMAIL_DOMAINS: "" turns off account creation at the first login, while leaving the key out allows every domain.

3. Put the client secret into the Secret

   kubectl -n overleaf patch secret overleaf-secrets --type merge \
     -p '{"stringData":{"OVERLEAF_OIDC_CLIENT_SECRET":"<Client Secret>"}}'
   
4. Trust a private CA (optional)

   If the OP’s certificate comes from your own CA, add the CA to the Secret overleaf-certs mounted at /var/lib/overleaf/certs (see Certificates and other files) and point Node.js at it:

     NODE_EXTRA_CA_CERTS: /var/lib/overleaf/certs/ca.pem
   
5. Apply and restart

   kubectl apply -f 30-config.yaml
   kubectl -n overleaf rollout restart deployment/overleaf     # or statefulset/overleaf
   kubectl -n overleaf rollout status deployment/overleaf
   

   Then check that every pod reaches the token endpoint. The pods call it, not the browser, so a firewall or DNS problem shows up only here:

   for p in $(kubectl -n overleaf get pod -l app=overleaf -o name); do   # app=overleaf-ha for several replicas
     kubectl -n overleaf exec "$p" -- curl -sS -o /dev/null -w "$p %{http_code}\n" \
       https://authentik.example.com/application/o/token/
   done
   

   Any HTTP status (405 for a GET) means the endpoint is reachable; 000 means it is not.

Several replicas

Nothing extra. The state value of a login and the ID token used for logout are kept in the session, which lives in Redis, so the callback works on whichever replica receives it.

Tested on Kubernetes

With goauthentik as the OP, on Kubernetes 1.37 with three replicas behind HAProxy, our end-to-end tests for OIDC pass (35 cases): login, and logout through the OP; the admin mapping by group, by email and by a single value, and without mapping; name and admin flag updated at each login; linking and unlinking accounts; password reset and password changes of OIDC accounts; suspended accounts; OVERLEAF_OIDC_ALLOWED_EMAIL_DOMAINS; OVERLEAF_DISABLE_LOCAL_LOGIN; and OIDC together with public access.

Q&A

Login fails with "Unable to verify authorization request state"

Answer: The browser did not send the session cookie back with the callback. On Kubernetes the usual causes are:

• OVERLEAF_SECURE_COOKIE is set, but users open the site over plain HTTP, so the browser never stores the cookie. Any value of OVERLEAF_SECURE_COOKIE, even "false", turns secure cookies on; remove the key instead.
• The site is opened under another address than OVERLEAF_SITE_URL.
• Behind HTTPS, your ingress or load balancer does not send X-Forwarded-Proto: https, or its address is missing from OVERLEAF_TRUSTED_PROXY_IPS.

Where do I see why a login failed?

Answer: In the web log of the pod that served the request, not in kubectl logs:

kubectl -n overleaf exec deploy/overleaf -- grep -i oidc /var/log/overleaf/web.log | tail

With several replicas, check each overleaf-N.