diff --git a/docs/content/guides/auth/azure-ad.md b/docs/content/guides/auth/azure-ad.md deleted file mode 100644 index db8ac0486..000000000 --- a/docs/content/guides/auth/azure-ad.md +++ /dev/null @@ -1,41 +0,0 @@ -# Authentication Guide: Azure Active Directory - -1. Login or Sign-up on portal.azure.com - -2. Navigate to Azure Active Directory from the homepage or the sidebar. - ![azure active directory service in azure portal page](../../images/auth/azure-active-directory-navigation.png) - -3. Navigate to App Registration - ![where to create new app registration](../../images/auth/azure-active-directory-new-registration.png) - -4. Enter Name "HedgeDoc". Then click on Register - ![how to register an app](../../images/auth/azure-active-directory-register.png) - -5. In the next page, click on `Add a certificate or secret` then navigate to `Client Secrets`. - Create a new client secret, add a description of your choice and copy the secret value. - ![generate new secret key](../../images/auth/auzre-active-directory-new-secret.png) - -6. Navigate to authentication page, then add a new platform. Select web as the platform. - ![Authentication page showing how to add a new web platform](../../images/auth/azure-active-directory-authentication.png) - -7. Set the `Redirect URI` to `https://YOURHOSTNAME/auth/oauth2/callback`. Check `ID Tokens` and uncheck `Access Token`. - ![configuring redirection uri](../../images/auth/azure-active-directory-redirect-uri.png) - -8. Retrieve the APPLICATION-ID and DIRECTORY-ID from the "Overview" section. - ![Find application id and directory id from overview page](../../images/auth/azure-active-directory-overview.png) - -9. Pass in your credentials as environment variables down below. - -```sh -CMD_OAUTH2_USER_PROFILE_URL=graph.microsoft.com/v1.0/me -CMD_OAUTH2_USER_PROFILE_USERNAME_ATTR=userPrincipalName -CMD_OAUTH2_USER_PROFILE_DISPLAY_NAME_ATTR=displayName -CMD_OAUTH2_USER_PROFILE_EMAIL_ATTR=mail -CMD_OAUTH2_USER_PROFILE_ID_ATTR=id -CMD_OAUTH2_TOKEN_URL=https://login.microsoftonline.com/**DIRECTORY-ID**/oauth2/v2.0/token -CMD_OAUTH2_AUTHORIZATION_URL=https://login.microsoftonline.com/**DIRECTORY-ID**/oauth2/v2.0/authorize -CMD_OAUTH2_CLIENT_ID=APPLICATION-ID -CMD_OAUTH2_CLIENT_SECRET=CLIENT-SECRET -CMD_OAUTH2_PROVIDERNAME=AzureAD -CMD_OAUTH2_SCOPE=openid offline_access email profile User.Read -``` diff --git a/docs/content/guides/auth/entra-id.md b/docs/content/guides/auth/entra-id.md new file mode 100644 index 000000000..795696ea0 --- /dev/null +++ b/docs/content/guides/auth/entra-id.md @@ -0,0 +1,92 @@ +# Authentication Guide: Microsoft Entra ID + +!!! info + Azure Active Directory was renamed to Microsoft Entra ID. Additionally, Microsoft Entra Connect v1 has been + retired starting October 2023, so you should switch to Microsoft Entra Connect v2.x when using that. + +## Pre-requisites + +We assume, you've created an account on portal.azure.com and configured a tenant to use with Microsoft Entra ID. +If you haven't done so, please follow the [official guide for that](https://learn.microsoft.com/en-us/entra/fundamentals/create-new-tenant). + +Open a text editor alongside to temporarily copy the id, secret and endpoints into it. + +## Step-by-step + +### Register the HedgeDoc app in Azure + +In the Azure Portal navigate to the Microsoft Entra ID service and select "App registrations" in the sidebar. + +![Azure Portal with Microsoft Entra ID service dashboard](../../images/auth/entra-id-dashboard.png) + +Select "New registration". + +![Azure Portal Microsoft Entra ID App registrations page](../../images/auth/entra-id-app-register.png) + +On the registration page enter a name like "HedgeDoc" and select which organizations should have access (the default allows only your tenant). +If you want to allow any Microsoft account to be able to use your HedgeDoc instance, select the 3rd option. +Finally confirm with the "Register" button. + +![Azure Portal App registration](../../images/auth/entra-id-app-registration.png) + +### Creating the OAuth2 bindings in Azure + +You will now get to the details screen for your just created application. Copy the "Application (client) ID" into your temporary text editor as we need it later on. +Continue by selecting "Authentication" in the sidebar. + +![Azure Portal App details page](../../images/auth/entra-id-app-details.png) + +Click the button "Add a platform" and select the "Web" target. + +![Azure Portal Add platform for app](../../images/auth/entra-id-create-platform.png) + +As a next step, navigate to "Certificates & secrets" via the sidebar and click the "New secret" button. +Enter a description as you like and select the expiry time. + +!!! warning + Set yourself a reminder before the secret expires to create a new secret and update the configuration of HedgeDoc. + Otherwise your users won't be able to sign-in anymore. + +![Azure Portal Create secret](../../images/auth/entra-id-client-secret.png) + +Copy the secret value after creation from the page, as you can't access it anytime later again. + +Return back to the overview of your HedgeDoc app in Azure and select "Endpoints" from the top bar. +Copy the values of the "OAuth 2.0 authorization endpoint (v2)" and the "OAuth 2.0 token endpoint (v2)". +Ensure, you copied the v2 URLs as the v1 URLs will stop working in the future. + +![Azure Portal Endpoints](../../images/auth/entra-id-endpoints.png) + +### Configure HedgeDoc + +Add the following environment variables to your configuration (for example in the `docker-compose.yml`). +Be sure to replace the values as mentioned in the comments below. + +```sh +# Replace these URLs with the ones previously copied. +CMD_OAUTH2_AUTHORIZATION_URL="https://login.microsoftonline.com/123456/oauth2/v2.0/authorize" +CMD_OAUTH2_TOKEN_URL="https://login.microsoftonline.com/123456/oauth2/v2.0/token" + +# Replace these values with the previously copied ID and secret. +CMD_OAUTH2_CLIENT_ID="APPLICATION-ID" +CMD_OAUTH2_CLIENT_SECRET="CLIENT-SECRET" + +# Change the name if you like it +CMD_OAUTH2_PROVIDERNAME="Microsoft Account" + +# Leave these values unchanged +CMD_OAUTH2_USER_PROFILE_URL="https://graph.microsoft.com/oidc/userinfo" +CMD_OAUTH2_USER_PROFILE_USERNAME_ATTR="sub" +CMD_OAUTH2_USER_PROFILE_DISPLAY_NAME_ATTR="name" +CMD_OAUTH2_USER_PROFILE_EMAIL_ATTR="email" +CMD_OAUTH2_USER_PROFILE_ID_ATTR="sub" +CMD_OAUTH2_SCOPE="openid email profile" +``` + +### Test your login + +After configuring, start your HedgeDoc instance. In the login dialog, there should be an orange new button for logging in +via your Microsoft Account. After clicking it, sign-in with your Microsoft Account as usual and confirm the requested permissions. +Now you're logged in. + +![Microsoft login page asking for permissions](../../images/auth/entra-id-login.png) diff --git a/docs/content/images/auth/auzre-active-directory-new-secret.png b/docs/content/images/auth/auzre-active-directory-new-secret.png deleted file mode 100644 index 4447de565..000000000 Binary files a/docs/content/images/auth/auzre-active-directory-new-secret.png and /dev/null differ diff --git a/docs/content/images/auth/azure-active-directory-authentication.png b/docs/content/images/auth/azure-active-directory-authentication.png deleted file mode 100644 index 0fc13f341..000000000 Binary files a/docs/content/images/auth/azure-active-directory-authentication.png and /dev/null differ diff --git a/docs/content/images/auth/azure-active-directory-navigation.png b/docs/content/images/auth/azure-active-directory-navigation.png deleted file mode 100644 index b63b57228..000000000 Binary files a/docs/content/images/auth/azure-active-directory-navigation.png and /dev/null differ diff --git a/docs/content/images/auth/azure-active-directory-new-registration.png b/docs/content/images/auth/azure-active-directory-new-registration.png deleted file mode 100644 index 3a7aae766..000000000 Binary files a/docs/content/images/auth/azure-active-directory-new-registration.png and /dev/null differ diff --git a/docs/content/images/auth/azure-active-directory-overview.png b/docs/content/images/auth/azure-active-directory-overview.png deleted file mode 100644 index 467db6d99..000000000 Binary files a/docs/content/images/auth/azure-active-directory-overview.png and /dev/null differ diff --git a/docs/content/images/auth/azure-active-directory-redirect-uri.png b/docs/content/images/auth/azure-active-directory-redirect-uri.png deleted file mode 100644 index 773dea4a4..000000000 Binary files a/docs/content/images/auth/azure-active-directory-redirect-uri.png and /dev/null differ diff --git a/docs/content/images/auth/azure-active-directory-register.png b/docs/content/images/auth/azure-active-directory-register.png deleted file mode 100644 index d427ea45b..000000000 Binary files a/docs/content/images/auth/azure-active-directory-register.png and /dev/null differ diff --git a/docs/content/images/auth/entra-id-app-details.png b/docs/content/images/auth/entra-id-app-details.png new file mode 100644 index 000000000..4a51d0f29 Binary files /dev/null and b/docs/content/images/auth/entra-id-app-details.png differ diff --git a/docs/content/images/auth/entra-id-app-register.png b/docs/content/images/auth/entra-id-app-register.png new file mode 100644 index 000000000..1831f3b33 Binary files /dev/null and b/docs/content/images/auth/entra-id-app-register.png differ diff --git a/docs/content/images/auth/entra-id-app-registration.png b/docs/content/images/auth/entra-id-app-registration.png new file mode 100755 index 000000000..010ea8e96 Binary files /dev/null and b/docs/content/images/auth/entra-id-app-registration.png differ diff --git a/docs/content/images/auth/entra-id-client-secret.png b/docs/content/images/auth/entra-id-client-secret.png new file mode 100644 index 000000000..210c3020e Binary files /dev/null and b/docs/content/images/auth/entra-id-client-secret.png differ diff --git a/docs/content/images/auth/entra-id-create-platform.png b/docs/content/images/auth/entra-id-create-platform.png new file mode 100644 index 000000000..30ea87397 Binary files /dev/null and b/docs/content/images/auth/entra-id-create-platform.png differ diff --git a/docs/content/images/auth/entra-id-dashboard.png b/docs/content/images/auth/entra-id-dashboard.png new file mode 100644 index 000000000..9df75e1a2 Binary files /dev/null and b/docs/content/images/auth/entra-id-dashboard.png differ diff --git a/docs/content/images/auth/entra-id-endpoints.png b/docs/content/images/auth/entra-id-endpoints.png new file mode 100644 index 000000000..f109216b6 Binary files /dev/null and b/docs/content/images/auth/entra-id-endpoints.png differ diff --git a/docs/content/images/auth/entra-id-login.png b/docs/content/images/auth/entra-id-login.png new file mode 100755 index 000000000..debd7c921 Binary files /dev/null and b/docs/content/images/auth/entra-id-login.png differ diff --git a/docs/mkdocs.yml b/docs/mkdocs.yml index cc4ab961d..782f3fbeb 100644 --- a/docs/mkdocs.yml +++ b/docs/mkdocs.yml @@ -28,7 +28,7 @@ nav: - Nextcloud: guides/auth/nextcloud.md - Twitter: guides/auth/twitter.md - Authelia: guides/auth/authelia.md - - Azure Active Directory: guides/auth/azure-ad.md + - Microsoft Entra ID (Azure AD): guides/auth/entra-id.md - Media Backend: - MinIO: guides/minio-image-upload.md - S3: guides/s3-image-upload.md