Configuration
Internally, Overleaf OIDC module uses the passport-openidconnect library. If you are having issues configuring OpenID Connect, it is worth reading the README forpassport-openidconnect to get a feel for the configuration it expects.
The environment variable EXTERNAL_AUTH is required to enable the OIDC authentication module. This environment variable specifies which external authentication methods are activated. The value of this variable is a list. If the list includes oidc then OIDC authentication will be activated.
For example: EXTERNAL_AUTH=ldap oidc
When using the OIDC authentication method, a user is redirected to the Identity Provider (IdP) authentication site. If the IdP successfully authenticates the user, the Overleaf users database is checked for a record containing a thirdPartyIdentifiers field structured as follows:
externalUserId must match the user ID in the profile returned by the IdP server (see the OVERLEAF_OIDC_USER_ID_FIELD environment variable), and providerId must match the ID of the OIDC provider (see the OVERLEAF_OIDC_PROVIDER_ID).
If no matching record is found, the database is searched for a user with the primary email address matching the email in the IdP user profile:
- If such a user is found, the
thirdPartyIdentifiersfield is updated. - If no matching user is found and JIT account creation is not disabled, a new user is created with the email address and
thirdPartyIdentifiersfrom the IdP profile.
/user/settings page.
Finding the values with the discovery document
Every OpenID Provider (OP) publishes a discovery document at<issuer>/.well-known/openid-configuration. Copy the values from it instead of typing them by hand; one wrong character is enough to break the login.
Find the discovery URL

Authentik: the discovery URL and the issuer of a provider (test instance)
- Keycloak:
https://keycloak.example.com/realms/<realm>/.well-known/openid-configuration - Authentik:
https://authentik.example.com/application/o/<application-slug>/.well-known/openid-configuration
Read the values

Authentik: the endpoints of a provider (test instance)
Copy them into variables.env
Check that Overleaf can reach the OP
200.Environment Variables
The values of the following five required variables can be found using.well-known/openid-configuration endpoint of your OpenID Provider (OP), see above.
OVERLEAF_OIDC_ISSUER(required)OVERLEAF_OIDC_AUTHORIZATION_URL(required)OVERLEAF_OIDC_TOKEN_URL(required)OVERLEAF_OIDC_USER_INFO_URL(required)OVERLEAF_OIDC_LOGOUT_URL(required)
OVERLEAF_OIDC_CLIENT_ID(required)OVERLEAF_OIDC_CLIENT_SECRET(required)OVERLEAF_OIDC_SCOPE- Default:
openid profile email
- Default:
OVERLEAF_OIDC_PROVIDER_ID- Arbitrary ID of the OP, defaults to
oidc.
- Arbitrary ID of the OP, defaults to
OVERLEAF_OIDC_PROVIDER_NAME- The name of the OP, used in the
Linked Accountssection of the/user/settingspage, defaults toOIDC Provider.
- The name of the OP, used in the
OVERLEAF_OIDC_IDENTITY_SERVICE_NAME- Display name for the identity service, used on the login page (default:
Log in with $OVERLEAF_OIDC_PROVIDER_NAME).
- Display name for the identity service, used on the login page (default:
OVERLEAF_OIDC_PROVIDER_DESCRIPTION- Description of OP, used in the
Linked Accountssection (default:Log in with $OVERLEAF_OIDC_PROVIDER_NAME).
- Description of OP, used in the
OVERLEAF_OIDC_PROVIDER_INFO_LINKLearn moreURL in the OP description, default: noLearn morelink in the description.
OVERLEAF_OIDC_PROVIDER_HIDE_NOT_LINKED- Do not show OP on the
/user/settingspage, if the user’s account is not linked with the OP, defaultfalse.
- Do not show OP on the
OVERLEAF_OIDC_USER_ID_FIELD- The value of this attribute will be used by Overleaf as the external user ID, defaults to
id. Other possible reasonable values areemailandusername(corresponding topreferred_usernameOIDC claim).
- The value of this attribute will be used by Overleaf as the external user ID, defaults to
OVERLEAF_OIDC_ALLOWED_EMAIL_DOMAINS- Restricts Just-in-Time (JIT) account creation for users authenticating via OIDC. If set to a comma-separated list of domain names, a new account will be created only if the domain of the user’s email address matches one in the listed domains. If the domain does not match, an admin must manually create the user account using the OIDC user’s email address, with either a strong random password or, preferably, without the
hashedPasswordfield at all. Domain names may include a leading*.wildcard to match subdomains.- Example: To allow JIT account creation for users with email address like
name@example.comandname@math.example.com:
OVERLEAF_OIDC_ALLOWED_EMAIL_DOMAINS=example.com, *.example.com - Example: To completely disable JIT account creation:
OVERLEAF_OIDC_ALLOWED_EMAIL_DOMAINS=
- Example: To allow JIT account creation for users with email address like
- Restricts Just-in-Time (JIT) account creation for users authenticating via OIDC. If set to a comma-separated list of domain names, a new account will be created only if the domain of the user’s email address matches one in the listed domains. If the domain does not match, an admin must manually create the user account using the OIDC user’s email address, with either a strong random password or, preferably, without the
OVERLEAF_OIDC_UPDATE_USER_DETAILS_ON_LOGIN- If set to
true, updates the userfirst_nameandlast_namefield on login, and disables the user details form on/user/settingspage.
- If set to
OVERLEAF_OIDC_IS_ADMIN_FIELDandOVERLEAF_OIDC_IS_ADMIN_FIELD_VALUE- When both environment variables are set, the login process updates
user.isAdmin = trueif the profile returned by the OP contains the attribute specified byOVERLEAF_OIDC_IS_ADMIN_FIELDand its value either matchesOVERLEAF_OIDC_IS_ADMIN_FIELD_VALUEor is an array containingOVERLEAF_OIDC_IS_ADMIN_FIELD_VALUE(for example thegroupsclaim), otherwiseuser.isAdminis set tofalse. IfOVERLEAF_OIDC_IS_ADMIN_FIELDisemailthen the value of the attributeemails[0].valueis used for match checking.
- When both environment variables are set, the login process updates
https://my-overleaf-instance.com/oidc/login/callback.
Sample variables.env file
Sample variables.env file
Step-by-step: goauthentik
This walks through a setup that is tested against goauthentik. Replacehttps://overleaf.example.com with your OVERLEAF_SITE_URL and https://authentik.example.com with the address of your Authentik.
Create the provider
- Client Type:
Confidential. - Redirect URIs (under Protocol settings): add
https://overleaf.example.com/oidc/login/callbackwith the matching modeStrict. - Copy Client ID and Client Secret now, into
OVERLEAF_OIDC_CLIENT_IDandOVERLEAF_OIDC_CLIENT_SECRET.

Authentik: Client ID and Client Secret of a new provider
Create the application
overleaf, and select the provider. The slug becomes part of the issuer: https://authentik.example.com/application/o/overleaf/.Copy the URLs
Map the admins (optional)
groups claim, an array. To make the members of the Authentik group Admins admins of Overleaf:Tested variables.env for goauthentik
Tested variables.env for goauthentik
Q&A
The admin claim is set, but users do not become administrators
The admin claim is set, but users do not become administrators
- Version. Before v6.3.0, Overleaf did not read custom claims such as
groups, so onlyOVERLEAF_OIDC_IS_ADMIN_FIELD=emailworked. Upgrade to v6.3.0 or later. - The claim must be in the UserInfo response. Overleaf reads the claim from
OVERLEAF_OIDC_USER_INFO_URL, not from the ID token. If your OP adds the claim only to the ID token, also add it to UserInfo, for example with Add to userinfo on a Keycloak mapper. - The value must match exactly, including case, for example
Admins.
Can I use GitHub as the OIDC provider?
Can I use GitHub as the OIDC provider?
ID token not present in token response.To let users log in with their GitHub account, use an identity provider such as goauthentik or Keycloak, with GitHub as its login source, and connect Overleaf to that provider with OIDC.Can I use GitLab as the OIDC provider?
Can I use GitLab as the OIDC provider?
- Redirect URI:
https://my-overleaf-instance.com/oidc/login/callback - Scopes:
openid,profileandemail
https://gitlab.com/.well-known/openid-configuration, or from the same path on your GitLab, as described in Finding the values with the discovery document. For gitlab.com, the issuer is https://gitlab.com, without a trailing slash.
