InterFormNG2 Manual

This section describes the authentication for integration with Microsoft Entra ID.

 

Configuration steps on Microsoft Entra ID

First create and configure the application in Microsoft Entra ID Active Directory Admin Center as follows.

 

Create an app registration for InterFormNG2... Same description as step 1-5 for SharePoint configuration.

On the app registration, go to “Authentication” and press the button “Add a platform”. Select “Web” and add a redirect URI with the URL on which the users access InterFormNG2, followed by the exact path “/openId”. For instance: https://example.com:8086/openId. Check both “access token” and “ID token”, then press the “Configure” button.

 

Note that InterFormNG2 uses the claim “preferred_user name” from the access token as user name.

When using the built-in authorization together with Microsoft Entra ID authentication, then users have to be created in InterFormNG2 with the username that matches the “preferred_username”. With Microsoft Entra ID authorization, this user name is only used for visual display and logging.

 

Please note: Username is case sensitive and must be exactly the same case as in Microsoft Entra.

 

Microsoft Entra ID Authorization

If you want to use Microsoft Entra ID for authorization, then you need to create the application roles on Microsoft Entra ID. To do this, in the app registration for InterFormNG2, go to the section “App roles”.

Use the button “Create App role” to create the following roles (the “value” and “allowed member types” fields must be exactly as described here, you can choose your own description and display name):

 

 

In a single tenant environment, all users will automatically have access to the “home” tenant.

For multi-tenant environments, you also need to create a role for each tenantId. This role gives users access to that particular tenant.

Note: When using Microsoft Entra ID authentication and authorization, it is currently only possible for a user to have access to one tenant, i.e. you should only assign one tenant role to each user.

Security warning: Since access to the “home” tenant is automatically granted to all users with no tenant access role, it is recommended that the “home” tenant is not used for confidential/production data on multi-tenant systems.

 

If you are running a multi-tenant environment, then for each tenantId, create a role with the value “TENANT_” + tenantId, for instance:

 

 

 

Assigning users to roles

After creating the application roles above, you can assign users to each role.

Go to “Enterprise applications” and select the InterFormNG2 app registration from the list. Press the button “Assign users and groups” and then press “Add user/group”. Under “select a role” select the app role (or tenant access role) that you want to assign users to. Then under “users and groups” select all the users that should have this role. Then press the “Assign” button.

Repeat the above for each role that you want to assign users to. In multi-tenant environments, make sure to also assign one (and only one) tenant access role to each user.

 

Configuration for web service clients on Microsoft Entra ID

Even when using built-in authorization, if you want to do one of the following:

 

•Use OAuth2 web-service input for workflows with a client app that does not require user login.

•Use one of the InterFormNG2 APIs with a client app that does not require user login.

•Use the InterFormNG2 remote output client.

 

Then you need to grant API permissions on the app registration, so that web service clients can use the “client credentials flow” to obtain an access token, and have the necessary role “ROLE_WEB_SERVICE” assigned in the token. So even when using built-in authorization, you need to create the app role “ROLE_WEB_SERVICE” as described above.

 

To grant API permissions, in the app registration for InterFormNG2, go the section “Expose an API”, press the link “Set” next to “Application ID URI”. Save the generated API name.

 

Then go to the section “API permissions”. Press the button “Add a permission”, then select the “My APIs” tab, select the InterFormNG2 app registration, mark the checkbox on “ROLE_WEB_SERVICE” then press the button “Add permissions”. Note: If the role does not show up on the list, try reloading the page.

 

To enable the permission, you need a person with AzureAD admin rights to grant consent to the permission.

 

Configuration steps on InterFormNG2

Before enabling AzureAD authentication, you need to use the built-in authentication to log in as a system admin user and set some settings for AzureAD.

 

Log in as an admin user, select “settings” and go to the section “Authentication provider”. As “Authentication provider” select “Microsoft Entra ID”. If you also want to use Microsoft Entra ID for authorization, then select “Microsoft Entra ID” as authorization provider, otherwise select “built-in”. As “client secret” use a client secret from the AzureAD app registration. As redirect URI, specify the URL on which the users access InterFormNG2, followed by the exact path “/openId”. For instance: https://example.com:8086/openId. This redirect URI also needs to be registered on the Microsoft Entra ID app registration. Save the settings and log out of the InterFormNG2 web interface.

Below the settings, you will see some hints for properties that need to be defined in the file application-default.properties in the InterFormNG2 installation folder.

 

Open the file “application-default.properties” in a text editor and add the following:

 

authentication.provider=AzureAD

if you chose to use built-in authorization instead of Microsoft Entra ID authorization, also add:

authorization.provider=default

In any case add the following values from the InterFormNG2 app registration:

 

authentication.provider.resourceId=<Azure Application (client) ID>

authentication.provider.azureTenantId=<Azure Directory (tenant) ID>

(Note: Do not include the characters <> in the file. In the two lines above the <> characters are used in order to insert a placeholder for the actual value).

 

 

Now restart the InterFormNG2 server.

After restarting, reload the web front-end in the browser. You should now see a login screen with only a login button. Using the login button will initiate the Microsoft login flow. If you are already logged in on your Microsoft account, then it will normally complete immediately. Once complete, a redirect will send you back to InterFormNG2 on the URL that was specified as redirect URI. If the login was successful, it will quickly switch to the InterFormNG2 dashboard.

 

Note: In case of configuration errors or other issues, you can always revert back to the built-in authentication by removing the “authentication.provider” property from application-default.properties and then restarting the server.

 

Built-in authorization with Microsoft Entra ID authentication

It is possible to have a combo-solution where Microsoft Entra ID is only used for authentication while the built-in InterFormNG2 authorization is used. As mentioned above, you can choose built-in authorization by setting the following in application-default.properties:

 

authorization.provider=default

 

When using built-in authorization, all users have to be created in InterFormNG2’s user management. They have to be created with a username matching their user name on Microsoft Entra ID. The user must then be assigned tenant access and roles in InterFormNG2.

Make sure to at least create an admin user before enabling this mode.

 

Note: One advantage of built-in authorization, is that it allows users to have access to multiple tenants. This is not possible with AzureAD authorization. Note though, that a user can only have access to one tenant at the same time, even when using multiple different browsers or client machines.

In terms of performance, the combined solution is slower, as each request needs additional processing for authorization. For optimal performance, it is recommended to use AzureAD for both authentication and authorization.

 

Multi-tenant configuration for web service clients

If you are operating a multi-tenant environment, and you want to do one of the following:

 

•Use OAuth2 web-service input for workflows with a client app that does not require user login.

•Use one of the InterFormNG2 APIs with a client app that does not require user login.

•Use the InterFormNG2 remote output client.

 

Then each tenant needs to define a webservice input APIKey. This is needed because any role assigned to the  application app registration will affect all web-service clients that authenticate without a user, so using tenant roles is not an option. This is necessary regardless of whether authorization is done with AzureAD or the built-in solution.

 

Even on single-tenant environments you can choose to create an API key for the home tenant, to add an extra level of security. However, this is optional.

 

To configure an API key for a tenant, log in with a user that has tenant admin access, then select “settings” and go to the section “Webservice Input”. To create a new API Key, simply press the “generate” button. The key will be generated and copied to the clipboard. You should immediately paste it somewhere, as the next time you enter the settings screen, the value will be encrypted and unreadable.

 

In web-service client applications, you can now use the “client credentials flow” to obtain an access token from AzureAD. When sending requests to InterFormNG2, each requests need to have an HTTP header that identifies the tenant that the request should access.

The name of this HTTP header must be exactly “APIKey”.

The value of this HTTP header must be “<tenantId>:<APIkey>”, where tenantId is the id of the tenant and APIkey is the generated API key for that tenant. For example: “myCompany:bfaf58eee4784629”.

 

Using remote output client with Microsoft Entra ID authentication

When using the InterFormNG2 remote output client with an InterFormNG2 server that has AzureAD authentication enabled, the settings for the client are slightly different that when using the built-in authentication. In the configuration file “remote_output_settings.json” the following settings differ:

 

•username: Instead of a regular user name, this should be the webservice input API key defined for the tenant that you are accessing. On a single-tenant environment, where you access the “home” tenant, you can leave the username as a blank string if you did not create an API key for the home tenant.

 

•password: Use a client secret from the Microsoft Entra ID app registration.

 

Using web-service input workflows with Microsoft Entra ID authentication

 

When InterFormNG2 is configured for Microsoft Entra ID authentication, then web-service clients will also need to authenticate with Microsoft Entra ID when invoking workflows with web-service input.

 

We recommend using the client credentials flow for authentication. As described above, this means that the access token does not contain a tenant access role, so for multi-tenant environments, requests to InterFormNG2 workflows need to include the APIKey HTTP header.

 

Errors related to APIKey checks are printed to the system log, so if you experience authentication problems with webservice clients, then look in the system log for error messages that start with “Webservice Input:".

 

Security note: A secret from the app registration is required for the client credentials flow. In a multi-tenant environment, it is recommended to create a separate secret for each tenant. This way the tenant’s web service access can be revoked by simply deleting the secret.

 

The sample code below shows a simple Java example on how to authenticate with Microsoft Entra ID and invoke a workflow on InterFormNG2:

 

Example

The sample code below shows a simple Java example on how to authenticate with Microsoft Entra ID and invoke a workflow on InterFormNG2.

 

import java.io.InputStream;

import java.util.ArrayList;

import java.util.List;

 

import org.apache.http.NameValuePair;

import org.apache.http.client.entity.UrlEncodedFormEntity;

import org.apache.http.client.methods.CloseableHttpResponse;

import org.apache.http.client.methods.HttpPost;

import org.apache.http.impl.client.CloseableHttpClient;

import org.apache.http.impl.client.HttpClients;

import org.apache.http.message.BasicNameValuePair;

 

import com.fasterxml.jackson.databind.JsonNode;

import com.fasterxml.jackson.databind.ObjectMapper;

 

/**

* Simple example of calling the OAuth2 web-service in NG2 when using AzureAD authentication

*/

public class SampleWebClientAzureAD {

 

   private static final String clientId = "64576b92-1111-2222-3333-bbefb836b5d9"; // From AzureAD app registration

   private static final String secret = "_0A7Q~PFGy111222333444PRCeeFrX1"; // From AzureAD app registration

   private static final String azureTenantId = "1f7b3f3b-1111-2222-3333-9135f967a2aa"; // From AzureAD app registration

 

   public static void main(String args[]) throws Exception{

 

       callWebserice();

 

   }

 

   private static void callWebserice() throws Exception{

       final String tenantId = "myCompany"; // Tenant to access

       final String tenantApiKey = "ff0f1152aeaf45d1";

 

       String token=login();

 

       CloseableHttpClient httpClient=HttpClients.createDefault();

 

       // Invoking web-service input workflow with path "hello"

       HttpPost post=new HttpPost("http://localhost:8086/webservice/hello");

       post.addHeader("Authorization", "Bearer " + token);

       // For multi-tenant environments, APIKey header is needed to identify the tenant to access

       // For single-tenant, this header can be left out

       post.addHeader("APIKey", tenantId + ":" + tenantApiKey);

 

       List<NameValuePair> urlParameters=new ArrayList<NameValuePair>();

 

       String xml="<root>Hello world</root>";

       urlParameters.add(new BasicNameValuePair("xml", xml));

 

       post.setEntity(new UrlEncodedFormEntity(urlParameters));

 

       CloseableHttpResponse response=httpClient.execute(post);

 

       System.out.println(response.getStatusLine().getStatusCode());

   }

 

   /**

    * Obtain a token from AzureAD using the client credentials flow

    */

   private static String login() throws Exception {

 

       CloseableHttpClient httpClient=HttpClients.createDefault();

 

       HttpPost post=new HttpPost("https://login.microsoftonline.com/" + azureTenantId + "/oauth2/v2.0/token");

 

       List<NameValuePair> urlParameters=new ArrayList<NameValuePair>();

       urlParameters.add(new BasicNameValuePair("client_id", clientId));

       urlParameters.add(new BasicNameValuePair("client_secret", secret));

       urlParameters.add(new BasicNameValuePair("grant_type", "client_credentials"));

       urlParameters.add(new BasicNameValuePair("scope", clientId + "/.default"));

 

       post.setEntity(new UrlEncodedFormEntity(urlParameters));

 

       CloseableHttpResponse response=httpClient.execute(post);

 

       InputStream is=response.getEntity().getContent();

 

       ObjectMapper mapper=new ObjectMapper();

       JsonNode jsonNode=mapper.readTree(is);

       String accessToken=jsonNode.get("access_token").asText();

 

       return accessToken;

   }

 

}