Authentication

HedgeDoc supports multiple authentication mechanisms that can be enabled and configured. An authentication method is always linked to an account on the HedgeDoc instance. However, an account can also have multiple authentication methods linked.

Each user has a unique username. By this username, other users can invite them to their notes.

When first logging in with a new authentication method, a new account will be created. If a user already has an account, they can link a new authentication method in their settings.

Supported authentication methods

• Username and password (Local account)
• LDAP
• OpenID Connect (OIDC)

While HedgeDoc provides a basic local account system, we recommend using an external authentication mechanism for most environments.

For LDAP and OIDC you can configure multiple auth providers of that type. You need to give each of them a unique identifier that is used in the configuration and in the database. The identifier should consist of only letters (a-z, A-Z), numbers (0-9), and dashes (-).

Profile sync

A HedgeDoc account stores generic profile information like the display name of the user and optionally a URL to a profile picture. Depending on your configuration, users can change this information in their settings. You can also configure HedgeDoc to sync this information from an external source like LDAP or OIDC. In this case, changes made by the user will be overridden on login with the external source, that is configured as sync source.

Account merging

There's no built-in account merging in HedgeDoc. So if you registered with different auth methods, you will have different accounts. To manually resolve this situation, you can do the following:

1. Log in with the second account (this should be merged into the first one).
2. Visit every note, you own on that account and change the note ownership to your first account.
3. Ensure, there's nothing left anymore. Then delete the second account.
4. Log in with the first account.
5. Link the auth method of the former second account to your account in the settings.

Common configuration

environment variable	default	example	description
HD_SESSION_SECRET	(not set)	5aaea9250828ce6942b35d170a385e74c41f1f05, just random data	Required. The secret used to sign the session cookie.
HD_SESSION_LIFETIME	1209600	604800, 1209600	The lifetime of a session in seconds. After this time without activity, a user will be logged out.
HD_AUTH_ALLOW_PROFILE_EDITS	true	true, false	Allow users to edit their profile information.
HD_AUTH_ALLOW_CHOOSE_USERNAME	true	true, false	If enabled, users may freely choose their username when signing-up via an external auth source (OIDC). Otherwise the username from the external auth source is taken.
HD_AUTH_SYNC_SOURCE	(not set)	gitlab, if there's an auth method (LDAP or OIDC) with the identifier gitlab	If enabled, the auth method with the configured identifier will update user's profile information on login.