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.

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

Select "New registration".

Azure Portal Microsoft Entra ID App registrations page

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

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

Click the button "Add a platform" and select the "Web" target.

Azure Portal Add platform for app

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

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

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.

# 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"

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