mirrors/hedgedoc
1
0
Fork 0
mirror of https://github.com/hedgedoc/hedgedoc.git synced 2025-05-09 13:51:57 -04:00
Code Issues Projects Releases Packages Wiki Activity Actions

feat(auth): refactor auth, add oidc
Some checks are pending
Docker / build-and-push (frontend) (push) Waiting to run
Details
Docker / build-and-push (backend) (push) Waiting to run
Details
Deploy HD2 docs to Netlify / Deploys to netlify (push) Waiting to run
Details
E2E Tests / backend-sqlite (push) Waiting to run
Details
E2E Tests / backend-mariadb (push) Waiting to run
Details
E2E Tests / backend-postgres (push) Waiting to run
Details
E2E Tests / Build test build of frontend (push) Waiting to run
Details
E2E Tests / frontend-cypress (1) (push) Blocked by required conditions
Details
E2E Tests / frontend-cypress (2) (push) Blocked by required conditions
Details
E2E Tests / frontend-cypress (3) (push) Blocked by required conditions
Details
Lint and check format / Lint files and check formatting (push) Waiting to run
Details
REUSE Compliance Check / reuse (push) Waiting to run
Details
Scorecard supply-chain security / Scorecard analysis (push) Waiting to run
Details
Static Analysis / Njsscan code scanning (push) Waiting to run
Details
Static Analysis / CodeQL analysis (push) Waiting to run
Details
Run tests & build / Test and build with NodeJS 20 (push) Waiting to run
Details

Browse source 
Thanks to all HedgeDoc team members for the time discussing,
helping with weird Nest issues, providing feedback
and suggestions!

Co-authored-by: Philip Molares <philip.molares@udo.edu>
Signed-off-by: Philip Molares <philip.molares@udo.edu>
Signed-off-by: Erik Michelson <github@erik.michelson.eu>
This commit is contained in:
Erik Michelson 2024-03-23 02:10:25 +01:00
parent 1609f3e01f
commit 7f665fae4b
109 changed files with 2927 additions and 1700 deletions
Download patch file Download diff file Expand all files Collapse all files

6
docs/content/concepts/api-auth.md
View file

@ -48,11 +48,7 @@ using one of the supported authentication methods:
- Username & Password (`local`)
- LDAP
- SAML
- OAuth2
- GitLab
- GitHub
- Google
- OIDC
The `SessionGuard`, which is added to each (appropriate) controller method of the private API,
checks if the provided session is still valid and provides the controller method

2
docs/content/concepts/user-profiles.md
View file

@ -16,7 +16,7 @@ which contains the following information:
HedgeDoc 2 supports multiple authentication methods per user.
These are called *identities* and each identity is backed by an
auth provider (like OAuth, SAML, LDAP or internal auth).
auth provider (like OIDC, LDAP or internal auth).
One of a users identities may be marked as *sync source*.
This identity is used to automatically update profile attributes like the

56
docs/content/references/config/auth/index.md Normal file
View file

@ -0,0 +1,56 @@
# 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. |

19
docs/content/references/config/auth/ldap.md
View file

@ -1,22 +1,25 @@
# LDAP
HedgeDoc can use one or multiple LDAP servers to authenticate users. To do this,
you first need to tell HedgeDoc the names of servers you want to use (`HD_AUTH_LDAPS`),
and then you need to provide the configuration for those LDAP servers
HedgeDoc can use one or multiple LDAP servers to authenticate users. To do this, you
first need to tell HedgeDoc identifiers for the servers you want to use (`HD_AUTH_LDAP_SERVERS`).
Then you need to provide the configuration for these LDAP servers
depending on how you want to use them.
Each of those variables will contain the given name for this LDAP server.
For example if you named your LDAP server `MY_LDAP` all variables for this server
will start with `HD_AUTH_LDAP_MY_LDAP`.
Each of these variables will contain the identifier for the LDAP server.
For example, if you chose the identifier `MYLDAP` for your LDAP server, all variables
for this server will start with `HD_AUTH_LDAP_MYLDAP_`.
Replace `$NAME` with the identifier of the LDAP server in the table below accordingly.
| environment variable | default | example | description |
|--------------------------------------------|----------------------|----------------------------------------------------|---------------------------------------------------------------------------------------------------------------|
| `HD_AUTH_LDAPS` | - | `MY_LDAP` | A comma-seperated list of names of LDAP servers HedgeDoc should use. |
| `HD_AUTH_LDAP_SERVERS` | - | `MYLDAP` | A comma-seperated list of names of LDAP servers HedgeDoc should use. |
| `HD_AUTH_LDAP_$NAME_PROVIDER_NAME` | `LDAP` | `My LDAP` | The display name for the LDAP server, that is shown in the UI of HegdeDoc. |
| `HD_AUTH_LDAP_$NAME_URL` | - | `ldaps://ldap.example.com` | The url with which the LDAP server can be accessed. |
| `HD_AUTH_LDAP_$NAME_SEARCH_BASE` | - | `ou=users,dc=LDAP,dc=example,dc=com` | The LDAP search base which contains the user accounts on the LDAP server. |
| `HD_AUTH_LDAP_$NAME_SEARCH_FILTER` | `(uid={{username}})` | `(&(uid={{username}})(objectClass=inetOrgPerson))` | A LDAP search filter that filters the users that should have access. |
| `HD_AUTH_LDAP_$NAME_SEARCH_ATTRIBUTES` | - | `username,cn` | A comma-seperated list of attributes that the search filter from the LDAP server should access. |
| `HD_AUTH_LDAP_$NAME_USERID_FIELD` | `uid` | `uid`, `uidNumber`, `sAMAccountName` | The attribute of the user account which should be used as an id for the user. |
| `HD_AUTH_LDAP_$NAME_USER_ID_FIELD` | `uid` | `uid`, `uidNumber`, `sAMAccountName` | The attribute of the user account which should be used as an id for the user. |
| `HD_AUTH_LDAP_$NAME_DISPLAY_NAME_FIELD` | `displayName` | `displayName`, `name`, `cn` | The attribute of the user account which should be used as the display name for the user. |
| `HD_AUTH_LDAP_$NAME_PROFILE_PICTURE_FIELD` | `jpegPhoto` | `jpegPhoto`, `thumbnailPhoto` | The attribute of the user account which should be used as the user image for the user. |
| `HD_AUTH_LDAP_$NAME_BIND_DN` | - | `cn=admin,dc=LDAP,dc=example,dc=com` | The dn which is used to perform the user search. If this is omitted then HedgeDoc will use an anonymous bind. |

6
docs/content/references/config/auth/local.md
View file

@ -1,8 +1,8 @@
# Local
HedgeDoc provides local accounts, handled internally. This feature only provides basic
functionality, so for most environments we recommend using an external authentication mechanism,
which also enable more secure authentication like 2FA or WebAuthn.
functionality, so for most environments, we recommend using an external authentication mechanism,
which also enables more secure authentication like 2FA or Passkeys.
| environment variable | default | example | description |
|-------------------------------------------|---------|-------------------------|-----------------------------------------------------------------------------------------------------|
@ -16,7 +16,7 @@ The password score is calculated with [zxcvbn-ts][zxcvbn-ts-score].
| score | meaning | minimum number of guesses required (approximated) |
|:-----:|-------------------------------------------------------------------|---------------------------------------------------|
| 0 | All passwords are allowed | - |
| 0 | All passwords with minimum 6 characters are allowed | - |
| 1 | Only `too guessable` passwords are disallowed | 1.000 |
| 2 | `too guessable` and `very guessable` passwords are disallowed | 1.000.000 |
| 3 | `safely unguessable` and `very unguessable` passwords are allowed | 100.000.000 |

68
docs/content/references/config/auth/oidc.md Normal file
View file

@ -0,0 +1,68 @@
# OpenID Connect (OIDC)
HedgeDoc can use one or multiple OIDC servers to authenticate users. To do this, you first need
to tell HedgeDoc identifiers for the servers you want to use (`HD_AUTH_OIDC_SERVERS`). Then you
need to provide the configuration for these OIDC servers depending on how you want to use them.
Each of these variables will contain the identifier for the OIDC server.
For example, if you chose the identifier `MYOIDC` for your OIDC server, all variables
for this server will start with `HD_AUTH_OIDC_MYOIDC_`.
Replace `$NAME` with the identifier of the OIDC server in the table below accordingly.
| environment variable | default | example | description |
|------------------------------------|------------------|--------------------------------------------|---------------------------------------------------------------------------------------------------------------------------------------------------|
| `HD_AUTH_OIDC_SERVERS` | - | `MYOIDC` | A comma-seperated list of identifiers of OIDC servers HedgeDoc should use. |
| `HD_AUTH_OIDC_$NAME_PROVIDER_NAME` | `OpenID Connect` | `My OIDC Single-Sign-On` | The display name for the OIDC server, that is shown in the UI of HegdeDoc. |
| `HD_AUTH_OIDC_$NAME_ISSUER` | - | `https://auth.example.com` | The base url of the OIDC issuer. It should serve a file `.well-known/openid-configuration` |
| `HD_AUTH_OIDC_$NAME_CLIENT_ID` | - | `hd2` | The id with which HedgeDoc is registered at the OIDC server. |
| `HD_AUTH_OIDC_$NAME_CLIENT_SECRET` | - | `c3f70208375cf26700920678ec55b7df7cd75266` | The secret for the HedgeDoc application, given by the OIDC server. |
| `HD_AUTH_OIDC_$NAME_THEME` | - | `gitlab`, `google`, ... | The theme in which the button on the login page should be displayed. See below for a list of options. If not defined, a generic one will be used. |
As redirect URL you should configure
`https://hedgedoc.example.com/api/private/auth/oidc/$NAME/callback` where `$NAME`
is the identifier of the OIDC server. Remember to update the domain to your one.
You can also configure servers that only support plain OAuth2 but
no OIDC (e.g., GitHub or Discord). In this case, you need the following additional variables:
| environment variable | default | example | description |
|--------------------------------------------|----------------------|--------------------------------------------|------------------------------------------------------------------------------------------|
| `HD_AUTH_OIDC_$NAME_AUTHORIZE_URL` | - | `https://auth.example.com/oauth2/auth` | The URL to which the user should be redirected to start the OAuth2 flow. |
| `HD_AUTH_OIDC_$NAME_TOKEN_URL` | - | `https://auth.example.com/oauth2/token` | The URL to which the user should be redirected to exchange the code for an access token. |
| `HD_AUTH_OIDC_$NAME_USERINFO_URL` | - | `https://auth.example.com/oauth2/userinfo` | The URL to which the user should be redirected to get the user information. |
| `HD_AUTH_OIDC_$NAME_SCOPE` | - | `profile` | The scope that should be requested to get the user information. |
| `HD_AUTH_OIDC_$NAME_USER_ID_FIELD` | `sub` | `sub`, `id` | The unique identifier that is returned for the user from the OAuth2 provider. |
| `HD_AUTH_OIDC_$NAME_USER_ID_FIELD` | `sub` | `sub`, `id` | The unique identifier that is returned for the user from the OAuth2 provider. |
| `HD_AUTH_OIDC_$NAME_USER_NAME_FIELD` | `preferred_username` | `preferred_username`, `username` | The unique identifier that is returned for the user from the OAuth2 provider. |
| `HD_AUTH_OIDC_$NAME_DISPLAY_NAME_FIELD` | `name` | `name`, `displayName` | The field that contains the display name of the user. |
| `HD_AUTH_OIDC_$NAME_PROFILE_PICTURE_FIELD` | - | `picture`, `avatar` | The field that contains the URL to the profile picture of the user. |
| `HD_AUTH_OIDC_$NAME_EMAIL_FIELD` | `email` | `email`, `mail` | The field that contains the email address of the user. |
## Themes
To integrate the brand colors and icons of some popular OIDC providers into the login button,
you can use one of the following values:
- `google`
- `github`
- `gitlab`
- `facebook`
- `discord`
- `mastodon`
- `azure`
## Common providers
| Provider | support | issuer variable | Docs |
|-----------|-------------|---------------------------------------------------------------------------|------------------------------------------------------------------------------------------------------|
| Google | OIDC | `https://accounts.google.com` | [Google Docs](https://developers.google.com/identity/openid-connect/openid-connect) |
| GitHub | only OAuth2 | `https://github.com` | [GitHub Docs](https://docs.github.com/en/developers/apps/building-oauth-apps/authorizing-oauth-apps) |
| GitLab | OIDC | `https://gitlab.com` or your instance domain | [GitLab Docs](https://docs.gitlab.com/ee/integration/openid_connect_provider.html) |
| Facebook | OIDC | `https://www.facebook.com` | [Facebook Docs](https://developers.facebook.com/docs/facebook-login/overview) |
| Discord | only OAuth2 | `https://discord.com` | [Discord Docs](https://discord.com/developers/docs/topics/oauth2) |
| Azure | OIDC | `https://login.microsoftonline.com/{tenant}/v2.0`, replace accordingly | [Azure OIDC](https://docs.microsoft.com/en-us/azure/active-directory/develop/v2-protocols-oidc) |
| Auth0 | OIDC | `https://{yourDomain}.us.auth0.com/`, replace accordingly | [Auth0 OIDC](https://auth0.com/docs/authenticate/protocols/openid-connect-protocol) |
| Keycloak | OIDC | `https://keycloak.example.com/auth/realms/{realm}`, replace accordingly | [Keycloak Docs](https://www.keycloak.org/docs/latest/server_admin/#sso-protocols) |
| Authentik | OIDC | `https://authentik.example.com/application/o/{app}/`, replace accordingly | [Authentik Docs](https://docs.goauthentik.io/docs/providers/oauth2/) |
| Authelia | OIDC | `https://authelia.example.com`, replace accordingly | [Authelia Docs](https://www.authelia.com/integration/openid-connect/introduction/) |

3
docs/content/references/config/general.md
View file

@ -9,8 +9,5 @@
| `HD_INTERNAL_API_URL` | Content of HD_BASE_URL | `http://localhost:3000` | This URL is used by the frontend to access the backend directly if it can't reach the backend using the `HD_BASE_URL` |
| `HD_LOGLEVEL` | warn | | The loglevel that should be used. Options are `error`, `warn`, `info`, `debug` or `trace`. |
| `HD_SHOW_LOG_TIMESTAMP` | true | | Specifies if a timestamp should be added to the log statements. Disabling is useful for extern log management (systemd etc.) |
| `HD_FORBIDDEN_NOTE_IDS` | - | `notAllowed,alsoNotAllowed` | A list of note ids (separated by `,`), that are not allowed to be created or requested by anyone. |
| `HD_MAX_DOCUMENT_LENGTH` | 100000 | | The maximum length of any one document. Changes to this will impact performance for your users. |
| `HD_PERSIST_INTERVAL` | 10 | `0`, `5`, `10`, `20` | The time interval in **minutes** for the periodic note revision creation during realtime editing. `0` deactivates the periodic note revision creation. |
[faq-entry]: ../../faq/index.md#why-should-i-want-to-run-my-renderer-on-a-different-sub-domain

6
docs/content/references/config/index.md
View file

@ -4,9 +4,9 @@ HedgeDoc can be configured via environment variables either directly or via an `
## The `.env` file
The `.env` file should be in the working directory of the backend and contains key-value pairs of
environment variables and their corresponding value.
In the official Docker container this is `/usr/src/app/backend/`
The `.env` file should be in the root directory of the HedgeDoc application and
contains key-value pairs of environment variables and their corresponding value.
In the official Docker container this is `/usr/src/app/.env`
This can for example look like this:
<!-- markdownlint-disable proper-names -->

1
docs/content/references/config/notes.md
View file

@ -7,3 +7,4 @@
| `HD_GUEST_ACCESS` | `write` | `deny`, `read`, `write`, `create` | Defines the maximum access level for guest users to the instance. If guest access is set lower than the "everyone" permission of a note then the note permission will be overridden. |
| `HD_PERMISSION_DEFAULT_LOGGED_IN` | `write` | `none`, `read`, `write` | The default permission for the "logged-in" group that is set on new notes. |
| `HD_PERMISSION_DEFAULT_EVERYONE` | `read` | `none`, `read`, `write` | The default permission for the "everyone" group (logged-in & guest users), that is set on new notes created by logged-in users. Notes created by guests always set this to "write". |
| `HD_PERSIST_INTERVAL` | 10 | `0`, `5`, `10`, `20` | The time interval in **minutes** for the periodic note revision creation during realtime editing. `0` deactivates the periodic note revision creation. |

2
docs/mkdocs.yml
View file

@ -41,8 +41,10 @@ nav:
- Notes: references/config/notes.md
- Database: references/config/database.md
- Authentication:
- Overview: references/config/auth/index.md
- 'Local accounts': references/config/auth/local.md
- LDAP: references/config/auth/ldap.md
- 'OpenID Connect (OIDC)': references/config/auth/oidc.md
- Customization: references/config/customization.md
- Media Backends:
- Azure: references/config/media/azure.md