mirror of
https://github.com/hedgedoc/hedgedoc.git
synced 2024-11-01 00:20:35 -04:00
57 lines
4.2 KiB
Markdown
57 lines
4.2 KiB
Markdown
|
# 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)](./local.md)
|
||
|
|
- [LDAP](./ldap.md)
|
||
|
|
- [OpenID Connect (OIDC)](./oidc.md)
|
||
|
|
|
||
|
|
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. |
|