Azure AD

In the default installation of webPDF the users are read from the XML database conf/users.xml. It is also possible to use the users from an AzureAD, i.e. an online Active Directory.

In the current version, configure Azure AD in the Admin Portal under Portal > User source.

tip

Use the Admin Portal to configure the user source whenever possible. Manual editing of conf/server.xml should normally only be used for recovery if the Admin Portal is not accessible.

Azure AD Registration

To use Azure AD as a user source, register an application in Microsoft Entra ID and use the resulting application settings in webPDF.

Register the application

1. Open the Azure portal and go to Microsoft Entra ID > App registrations.
2. Select New registration.
3. Enter an application name.
4. Select the supported account type that matches your environment.
5. Complete the registration.

After the application is created, open its Overview page and note the Application (client) ID. This value is required as clientId in the webPDF configuration.

Configure authentication

1. Open the registered application.
2. Go to Authentication.
3. Under Advanced settings, enable Allow public client flows.
4. Save the changes.

Configure API permissions

1. Open the registered application.
2. Go to API permissions.
3. Add the required Microsoft Graph delegated permissions.
4. Ensure that User.Read is available for the application.
5. Grant consent if your tenant requires it.

Map the Azure AD registration to webPDF

Use the values from the Azure portal as follows:

Azure portal value	webPDF setting	Description
Application (client) ID	clientId	Identifies the registered application
Tenant-specific login endpoint or organizational endpoint	authority	Defines which Microsoft Entra ID tenant is used for sign-in
User.Read	scope	Defines the delegated permission requested during sign-in

Typical authority values:

• Multi-tenant configuration: https://login.microsoftonline.com/organizations/
• Single-tenant configuration: https://login.microsoftonline.com/<TENANT_ID>/

Choose the authority that matches the tenant where your users and groups are managed.

Verify the setup

1. Configure the Azure AD settings in conf/server.xml.
2. Restart the webPDF server.
3. Open the login page and sign in with a test user.
4. Verify that a standard user receives the user role.
5. Verify that an administrator is assigned to both the configured admin group and user group.

tip

If sign-in starts but does not complete successfully, review the authority, clientId, granted permissions, and tenant consent settings first.

Manual configuration

By adjusting the settings in conf/server.xml the user database can be changed.

caution

If possible, use the server's Admin Portal to modify the user database.

To use the users from an AzureAD, you need to add the "azureAd" entry in "user":

<user roleUserGroup="webPDFUser" roleAdminGroup="webPDFAdmin">
    <azureAd authority="https://login.microsoftonline.com/organizations/"
        clientId="4c0f....-....-....-....-......650a68"
        scope="user.read"/>
</user>

In the azureAd entry you have to specify the login URL authority of the Azure AD. You also need to configure the clientId (ID of the application's registration on the Azure AD portal).

Use the entries "roleAdminGroup" and "roleUserGroup" to define the group names to be assigned to the webPDF groups "user" and "admin". Change the group names to your AD groups:

<user roleAdminGroup="webPDFAdmin" roleUserGroup="webPDFUser">

Users who need administrator access should also be members of the group configured via roleUserGroup, so that they receive both the admin role and the required user role.

Troubleshooting

Admin Portal login is not possible

If Azure AD settings prevent access to the Admin Portal, manually edit conf/server.xml and restore the local XML user source:

<user>
    <xml/>
</user>

This switches the server back to the local conf/users.xml user database. Restart the webPDF server after saving the file so the change takes effect.

caution

Before manually editing conf/server.xml, create a backup copy of the file. Manual editing should only be used as a recovery step when the Admin Portal is not accessible.

Authentication succeeds, but the user has no access

If the Azure AD login succeeds but the user still cannot use the portal or web services, verify the role mapping:

• The user must be assigned to the group configured via roleUserGroup.
• Users who need administrator permissions should also be assigned to the group configured via roleAdminGroup.
• Administrators should be assigned to both groups so that they receive both the user role and the admin role.

The Azure AD application is not configured correctly

Verify the Azure AD application registration:

• Confirm that clientId matches the registered application.
• Confirm that the configured authority matches the intended tenant or tenant type.
• Confirm that Allow public client flows is enabled if the selected login flow requires it.
• Confirm that the configured scope, for example user.read, is allowed for the application registration.

Wrong tenant or authority URL

If login fails before a token is issued, verify that the authority URL points to the correct Microsoft Entra ID tenant.

If multiple tenants or directories are used, confirm that the configured authority matches the directory where the users and groups are managed.

Consent or tenant policies block sign-in

If authentication starts but does not finish successfully, review the Azure AD tenant configuration:

• Confirm that the required consent has been granted for the configured scope.
• Confirm that tenant policies or Conditional Access rules do not block the login flow.
• Confirm that the application is allowed for the affected users in the tenant.

The user is not assigned to the expected groups

If a user can sign in but does not receive the expected permissions, verify the Azure AD group assignments:

• Confirm that the user is a member of the group configured by roleUserGroup.
• Confirm that administrators are also members of the group configured by roleAdminGroup.
• Confirm that the configured group names match the values expected by webPDF.

Check the server logs

If the configuration still does not work, inspect the server logs for authority or tenant errors, consent-related issues, token validation problems, and group or role mapping failures.

After all adjustments have been made, the webPDF server must be restarted so that all settings are activated and users are read.