> ## Documentation Index
> Fetch the complete documentation index at: https://ayakaleaf-pro.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# 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](https://ayakaleaf-pro.mintlify.site/on-premises/configuration/overleaf-toolkit/authentication/oidc-authentication.md) 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](https://ayakaleaf-pro.mintlify.site/on-premises/configuration/overleaf-toolkit/authentication/oidc-authentication.md#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](https://ayakaleaf-pro.mintlify.site/on-premises/configuration/kubernetes/horizontal-scaling.md)):

```yaml title="30-config.yaml (additions)" wrap theme={null}
  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](https://ayakaleaf-pro.mintlify.site/on-premises/configuration/overleaf-toolkit/authentication/oidc-authentication.md#environment-variables) for every `OVERLEAF_OIDC_*` setting; all of them go into the ConfigMap except the client secret.

> [!WARNING]
>
> 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**

```bash theme={null}
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](https://ayakaleaf-pro.mintlify.site/on-premises/configuration/kubernetes#certificates-and-other-files)) and point Node.js at it:

```yaml theme={null}
  NODE_EXTRA_CA_CERTS: /var/lib/overleaf/certs/ca.pem
```

**5. Apply and restart**

```bash theme={null}
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:

```bash theme={null}
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

> [accordion] 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`.

> [accordion] Where do I see why a login failed?
>
> **Answer:** In the web log of the pod that served the request, not in `kubectl logs`:
>
> ```bash theme={null}
> kubectl -n overleaf exec deploy/overleaf -- grep -i oidc /var/log/overleaf/web.log | tail
> ```
>
> With several replicas, check each `overleaf-N`.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.