Skip to main content
Version: 10.0

Portal Azure AD

To log in to the Portal using single sign-on and Azure AD, you have to set up an application in the Microsoft Entra admin center.

App registration​

To create a new application, go to Applications, select App registrations and then New Registration.

New application registration

Enter a Name (1) for the application (here: Portal Access) and enter the Redirect URI.

important

The definition of the URI is necessary because the portal is a Single Page Application (SPA) which, after logging in on the provider side, requires the executed login to be able to call up the web services. After successfully logging in to the OAuth provider, the user is redirected to this page to log in to the portal.

The URI must be defined for your server and end with /webPDF/oauth.

Example: http://localhost:8080/webPDF/oauth

After creating the application, you will see the most important information about the application on the Overview page. Make a note of the settings Application (Client) Id (1) and Directory (Tenant) ID (2) for entry in the webPDF configuration.

Application overview

Expose the API​

Next, create an API with Add to Application ID URI (3).

Create a new Application ID URI under Expose an API with Add (1). Make a note of the ID created for later input.

You must now create the scopes Edit and Read via Add a scope.

  • Edit - Allows the user to edit content (e.g. as an administrator (see Roles below) which allows to modify the server configuration)
  • Read - Allows the user to read content (as a normal portal user)
note

The names are only default values that the server uses. These values can be adjusted via the OUAth provider configuration. If you use other names, you must take this into account in the further configuration.

Create the two scopes and pay attention to the correct spelling.

Expose API

Application roles​

The next step is to create the roles (1) with App roles, which the server needs to distinguish between a normal user and an administrator. To do this, webPDF uses the fixed roles user for a normal user and admin for a user with administrator rights, i.e. access to the admin portal.

Use Create app role (2) to create two roles admin and user. Please pay attention to the correct spelling.

Create app roles

Modify the manifest​

Next, under Manifest of the application, the application must be set to provide tokens that work with version 2.0 of the OAuth endpoints API. To do this, the value requestedAccessTokenVersion must be set to 2.

Change Manifest

The last step is to define which effective rights a user who logs on to the portal with this application receives. To do this, the roles and scopes created must be assigned. This is done under API permissions (1).

Assign effective rights

Assign permissions​

Use Add a permission (2) to assign the role (from App role) user and the Scope (from Expose to API) Read (3).

important

It is important that the permissions are activated with Granted ... (4).

In this case, only access as a normal user is permitted. If the user is to be granted access as an administrator, the role admin and the scope Edit must also be assigned.

Server configuration​

Once the application has been created, the defined values can be set in the server's Admin portal.

The provider Azure AD can be selected and created via the Portal toolbar under OAuth. The corresponding values for the application must be entered in the dialog.

App configuration in the server

Enter the Client ID (1), the Application ID (2) and the Tenant ID from the application.

important

It is important that you add the Application URI ID from the application to the Scope entry (4).

The remaining values are the default values of the Azure AD OAuth provider and can generally be adopted.

tip

The names of the scopes can be changed under Name of the group '...' (5) if you have not used the default values during registration.

After all values have been adjusted, the values must be accepted with Add and the server restarted. The additional login is then available in the login dialog.

Control application access​

By default, all users of the domain are allowed to use the registered application. If you want to change this, you must adjust the access for the registered application in Entra admin center under Applications -> Enterprise applications.

To do this, open the created app under All applications and go to Properties. Activate Assignment required to Yes so that only selected users can use the app.

Then define the users and groups that are allowed to use the app under Users and groups.

Azure AD in the configuration file​

Below is an example of the configuration in conf/server.xml for the Azure AD OAuth provider. The variables {....} must be replaced with the values from the configured App registration.

<oauth>
    <providers>
        <provider name="azureAd"
                  displayName="Microsoft"
                  flow="authorizationCodeWithPkce"
                  id="azure_authorize"
                  tenantId="{YOUR_TENANT_ID}"
                  clientId="{YOUR_CLIENT_ID_OF_REGISTERED_APPLICATION}"
                  applicationId="{YOUR_ID_OF_REGISTERED_APPLICATION}"
                  scope="offline_access openid api://{YOUR_ID_OF_REGISTERED_APPLICATION}/.default"
                  discoveryUrl="https://login.microsoftonline.com/{YOUR_TENANT_ID}/v2.0/.well-known/openid-configuration"
                  claimSessionId="sub"
                  claimClientId="azp"
                  claimRoles="scp"
                  roleNameAdmin="Edit"
                  roleNameUser="Read">
            <!-- https://docs.microsoft.com/en-us/azure/active-directory/develop/v2-protocols-oidc#send-a-sign-out-request -->
            <logout url="https://login.microsoftonline.com/common/oauth2/v2.0/logout?post_logout_redirect_uri={redirectUrl}"/>
        </provider>
    </providers>
</oauth>