Azure AD

Microsoft Azure AD can be used for OAuth2 authorization of webPDF's web services. For this purpose, the provider must be configured in the server to be able to check the issued access tokens of the provider.

Use the Admin Portal to configure the provider.

Below is the description of how to set up webPDF in Azure AD to use the tokens created by Azure AD in webPDF server.

OAuth2 authorization

caution

The description refers to the use of the tokens in the direct webPDF API call (web service call) and not to the login/use in the portal.

After setup in Azure AD, the webPDF server must be configured accordingly so that the tokens issued by Azure AD are recognized (validated) by the webPDF server. After configuration, the tokens can then be used directly in the web service calls. It is then no longer necessary to log in to the webPDF server, but the tokens issued by Azure AD can be passed directly in the Authorization header as Bearer tokens in the HTTP request. The webPDF server validates the issued tokens based on the configuration and thus controls the authorization for the web services.

info

On the Azure AD side, the configuration can be done as one "app" for the web service API and the client together, or both parts can be created as separate "apps".

The following description assumes that the webPDF web service API is created as "App" webPDF API and the client as "App" webPDF Client M2M.

Registering the web service API as an "App"

Register an "App" named "webPDF API" in Microsoft AD as described at https://learn.microsoft.com/en-us/azure/active-directory/develop/quickstart-register-app. This function registers the webPDF web service API as an "App" in Azure AD. Hereafter, this registration will be referred to as API App.

The configuration of a Redirect URI is not necessary at this point, because only the API is defined as App here.

For the configuration in the webPDF server the following specifications of the API App are needed later:

• Application (client) ID ("Overview" page of the "App")
• directory (tenant) ID (overview page of the app)
• Endpoint URL` ("Endpoints" page of the "App" - see below)

note

Please note that in this scenario the webPDF server itself does not perform any login, i.e. no OAuth2 flow. This is the task of your client application, which fetches the token and "offers" it to the webPDF server for authorization in the web service call. The webPDF server only needs to be configured to validate the provided token.

Define roles

In order for the webPDF server to distinguish between execution with normal or administrative privileges when calling the web service API and authorization (through the Azure AD token), two roles are available.

• user - normal call to the web service API
• admin - call to the web service API with administrative rights.

caution

Jeder Webservice-Aufruf muss die Rolle user im Token enthalten, d.h. Sie müssen mindestens diese Rolle anlegen.

Create the role user as described in https://learn.microsoft.com/en-us/azure/active-directory/develop/howto-add-app-roles-in-azure-ad-apps. If you want the API App to be able to provide administrative rights to clients later on, then also create the admin role.

Make sure that the values user or admin are entered under Value, the spelling is correct and the roles are activated. The defined roles are provided by Azure AD in the token under the claim roles.

tip

In "Role registration" you only define which roles should basically be available in the API App. Which role the respective client gets later, when it uses this API App, is defined via API permissions in the Client App.

Provide API

To make the created API App also available for clients, it must be activated via Expose to API. For this you have to create a URI ID under Application ID URI and the function Set. This URI ID will be used later by the client for the token request (in scope).

Azure AD V2 Token

In order for the webPDF server to correctly process (validate) the tokens issued by Azure AD and for all necessary claims (such as roles or azp) to be present, V2 tokens must be issued by Azure AD. Therefore, care must be taken to ensure that V2 tokens are enabled for the registered API App or that such tokens are requested by the client application.

For this purpose, the manifest data of the API App must be adapted. Under Manifest the entry accessTokenAcceptedVersion must be set to the value 2.

note

Attribute differences between Azure AD Graph and Microsoft Graph formats

In the Microsoft graph format, the accessTokenAcceptedVersion property has been moved and renamed to requestedAccessTokenVersion, which now belongs to the api attribute.

Endpoint URL

In order for the webPDF server to validate the Azure AD tokens, information (such as the certificates used) is required from Azure AD. This information can be automatically retrieved by webPDF via the Discovery URL from the OpenID Connect metadata document.

You can find the URL under the item Endpoints on the page App registrations (see also https://learn.microsoft.com/en-us/azure/active-directory/develop/v2-protocols-oidc#find-your-apps-openid-configuration-document-uri). From there take the entry OpenID Connect metadata document.

Example: https://login.microsoftonline.com/{YOUR_TENANT_ID}/v2.0/.well-known/openid-configuration

Registering the client as an "App"

Now that the web service API has been defined, a client can be registered for use. This client is the application from which you want to use the webPDF web service API, i.e. the API app. This client must retrieve the token from Azure AD and then pass it in the webPDF web service calls.

In this case, we register a client that retrieves and uses the token in a "machine to machine" (M2M) communication. In this scenario, the token is retrieved as a "Client Credential Flow" from Azure AD.

Create a new "App" with the name webPDF Client M2M (short Client App) as described above.

caution

From the created Client App the Application (client) ID is needed for the later webPDF Server configuration.

Grant access to the API

In order for the Client app to have access to the API app (and thus access to webPDF web service API), the access rights must be granted. As described in https://learn.microsoft.com/en-us/azure/active-directory/develop/quickstart-configure-app-access-web-apis, the rights must be assigned via API permission.

note

At this point you specify whether access is only with normal user rights or also with administrative rights.

Do not forget that the corresponding assignments must also be confirmed by means of "admin grant".

Instructions for granting access can also be found in https://learn.microsoft.com/en-us/azure/active-directory/develop/howto-add-app-roles-in-azure-ad-apps#assign-app-roles-to-applications.

Credentials

In order to now use the Client app and trigger a corresponding "OAuth2 client credentials flow", a "Secret" is still required. Under Certificates & Secrets you can now create such a "Secret". This "Secret" is needed to request the token and does not play any role for the webPDF server configuration.

Configuration of the webPDF server

Open the Admin Portal of the webPDF server and go there under Server to the dialog OAuth. Select Azure AD as provider and click Add. In the dialog that appears, fill in the following data:

• For Client ID enter the Application (client) ID of the Client app.
• For Application ID enter the Application (client) ID of the API app.
• For Tenant ID enter the Directory (tenant) ID of the API app.
• The Scope entry can remain empty.
• For Discovery URL enter the Endpoint URL (see API app) or check if this is not already correct. The URL can contain the placeholder {tenantId} which will be automatically replaced by your tenant ID.
• You do not need to adjust the configuration of the claims and names of the roles.

Save the settings with Add and restart the webPDF server.

After the restart, Azure AD tokens can be passed in the webPDF server's web service calls. webPDF validates the tokens and checks the roles in the token. If the information is correct, then the call is authorized and executed.

Client for token retrieval

To get a corresponding token to call the API app and thus the webPDF web service API, you must now use a client.

On the page https://learn.microsoft.com/en-us/azure/active-directory/develop/web-api-quickstart?pivots=devlang-aspnet or https://learn.microsoft.com/en-us/azure/active-directory/develop/sample-v2-code#web-api you can find many examples of such a client in different programming languages.

When calling the webPDF web service API, the server represents a "protected web API" (in the form of the API app) and this is called by a client (Client app). The client can take different forms, such as a desktop, service or web application.

Verify token

With https://jwt.io/#debugger-io or https://jwt.ms/ a token created by Azure AD can be decoded. This makes it easy to check the content of the token if, for example, the webPDF server does not accept the token.

For example, it lets you check whether the necessary "claims" (such as azp or roles) are present and also contain the correct values.

• aud=Application (client) IDof theAPI app`.
• azp = Application (client) ID of the Client app.
• iss = a URL containing the Directory (tenant) ID.
• roles = user or admin (or both)
• ver = With the value 2.0 (see "Azure AD V2 Token" above)

Azure AD in configuration file

Below is an example of the configuration in the conf/server.xml for the provider:

<oauth>  
    <providers>  
        <provider name="azureAd"  
                  displayName="Microsoft"  
                  flow="clientCredentials"  
                  id="azure_client"  
                  tenantId="{YOUR_TENANT_ID}"  
                  clientId="{YOUR_CLIENT_ID_OF_REGISTERED_APPLICATION}"  
                  applicationId="{YOUR_ID_OF_REGISTERED_APPLICATION}"  
                  scope=""  
                  discoveryUrl="https://login.microsoftonline.com/{YOUR_TENANT_ID}/v2.0/.well-known/openid-configuration"  
                  claimSessionId="sub"  
                  claimClientId="azp"  
                  claimRoles="roles"  
                  roleNameAdmin="admin"  
                  roleNameUser="user"  
        />  
    </providers>  
</oauth>

caution

The configuration of the application at the OAuth2 provider must be done as OAuth2 "Client Credentials Flow".