github/hedgedoc
1
0
Fork 0
mirror of https://github.com/hedgedoc/hedgedoc.git synced 2024-11-26 11:43:59 -05:00
Code Issues Projects Releases Packages Wiki Activity
hedgedoc/docs/content/references/config/auth/oidc.md
Erik Michelson 603ad8088c enhancement(auth/oidc): allow manual defining end_session_endpoint URL 
For non-OIDC compliant OAuth2 providers it was only possible to define
the authorize, token and userinfo URLs but not the end_session_endpoint.
This commit adds that functionality.

Signed-off-by: Erik Michelson <github@erik.michelson.eu>
2024-09-18 18:03:22 +02:00

8.2 KiB
Raw Blame History

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_END_SESSION_URL - https://auth.example.com/oauth2/logout The URL to which the user should be redirected to end the session.
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
GitHub only OAuth2 https://github.com GitHub Docs
GitLab OIDC https://gitlab.com or your instance domain GitLab Docs
Facebook OIDC https://www.facebook.com Facebook Docs
Discord only OAuth2 https://discord.com Discord Docs
Azure OIDC https://login.microsoftonline.com/{tenant}/v2.0, replace accordingly Azure OIDC
Auth0 OIDC https://{yourDomain}.us.auth0.com/, replace accordingly Auth0 OIDC
Keycloak OIDC https://keycloak.example.com/auth/realms/{realm}, replace accordingly Keycloak Docs
Authentik OIDC https://authentik.example.com/application/o/{app}/, replace accordingly Authentik Docs
Authelia OIDC https://authelia.example.com, replace accordingly Authelia Docs