Microsoft Entra ID

With Entra ID (formerly Azure Active Directory), your people sign in with the Microsoft account they use for Outlook and Teams – including your multi-factor authentication and conditional access policies.

You register DDM in your own Entra tenant and enter the result in DDM under Settings › Single sign-on. Nobody else is involved, and no other company's tenant can sign in to your organisation.

You need an account that may register applications in Entra ID – e.g. Application Developer or Cloud Application Administrator – and, for the consent in step 3, an administrator.

1. Register DDM

https://cms.documentdistributionmanager.com/api/auth/sso/callback

2. Create a client secret

1. Open Certificates & secrets › Client secrets › New client secret.
2. Enter a description (e.g. DDM) and choose how long it is valid – at most 24 months.
3. Copy the Value straight away. It is shown only once.

3. Permissions and the e-mail claim

API permissions – the app needs the delegated Microsoft Graph permissions openid, email and profile (User.Read is already there and may stay). Click Add a permission › Microsoft Graph › Delegated permissions, tick the three, then Grant admin consent for … – so your people are not asked themselves.

Token configuration – click Add optional claim, token type ID, and tick email. Entra ID then puts your people's e-mail address into the sign-in, which DDM matches against your domains.

4. Enter it in DDM

Under Settings › Single sign-on › Identity provider:

Click Save, then Test connection, and switch on Single sign-on active – see Single sign-on.

5. Optional: only certain people

By default, everybody in your tenant may use the app. To limit it to certain people or groups, go to Entra ID › Enterprise applications › DDM › Properties, set Assignment required? to Yes, and add the people or groups under Users and groups.

That is a second gate in front of DDM's own: whether somebody gets in at all is still decided by your confirmed domains and Create accounts on first sign-in.

6. Map groups

To have DDM put people into groups by their Entra ID groups:

1. In the app registration, open Token configuration › Add groups claim.
2. Tick Security groups (or Groups assigned to the application, if you assign groups under Enterprise applications › Users and groups – recommended, it keeps the token small). Leave the ID token's format at Group ID.
3. In DDM, under Groups, enter groups as the Group claim and add a mapping for each group: the group's Object ID – in Entra ID under Groups › the group › Overview – and the DDM group.

7. Optional: bring the calendar along

With Connect the calendar at sign-in (OpenID Connect only), the sign-in also asks for the calendar, and the Outlook calendar is connected in DDM as soon as somebody signs in:

1. In Entra ID, under API permissions › Microsoft Graph › Delegated permissions, add Calendars.ReadWrite and offline_access and Grant admin consent – otherwise Microsoft asks every person once.
2. In DDM, switch on Connect the calendar at sign-in for the Microsoft sign-in.

Anybody already signed in gets the calendar at their next sign-in. Calendar access comes first: if it already connects the calendar, that stays. This does not work with SAML – SAML brings no tokens.

With SAML instead

Entra ID can also connect DDM by SAML – for example if your security team requires it.

1. Under Settings › Single sign-on, add a provider with Microsoft Entra ID and SAML 2.0. DDM shows three values for it.
2. In the Microsoft Entra admin center, go to Entra ID › Enterprise applications › New application › Create your own application, name it DDM and choose Integrate any other application you don't find in the gallery (Non-gallery).
3. Open Single sign-on › SAML. Under Basic SAML Configuration, enter DDM's Identifier (Entity ID) and Reply URL (ACS URL).
4. Under Attributes & Claims, the e-mail address is sent by default as http://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddress – exactly what DDM suggests as the E-mail attribute. For groups, click Add a group claim; they arrive as http://schemas.microsoft.com/ws/2008/06/identity/claims/groups – enter that as the Group claim in DDM.
5. Under SAML Certificates, copy the App Federation Metadata Url and enter it in DDM under Your provider's metadata › Metadata URL. Save.
6. Assign the people or groups who may use DDM under Users and groups.

When the certificate approaches its expiry, Entra ID creates a new one; activate it there, then click Reload metadata in DDM.

Common errors

Microsoft sign-in for the whole installation

Independently of the above, whoever runs a DDM installation can offer Sign in with Entra ID to every organisation on it – with one app registration for all of them, set up on the server (MICROSOFT_CLIENT_ID, MICROSOFT_CLIENT_SECRET, NUXT_PUBLIC_SSO_PROVIDERS="microsoft", redirect URI <BETTER_AUTH_URL>/api/auth/callback/microsoft, a multitenant registration). It does not create accounts and is the same for everybody; an organisation that wants its own tenant, its own rules or Okta uses single sign-on as described above.