KB003398

You can configure K2 to expose the K2 Workflow REST API through an Azure AD application proxy, and this article explains how to implement this configuration.

The configuration enables access to an ­on-premise instance of the K2 Workflow REST API where all users are present in Active Directory (AD) and have also had their identities synced to Azure AD (AAD). This allows the AAD app proxy connector service to generate a Kerberos token for an Active Directory user, using a corresponding UPN from their AAD account. The AAD app proxy connector service generates Kerberos tickets and passes them to the K2 REST workflow API. The diagram below shows a high-level overview of the configuration:

1. Part 1: Activate the K2 REST API
2. Part 2: Change authentication settings for the REST API virtual directory
3. Part 3: Configure the AAD App Proxy connector
4. Part 4: Create Kerberos SPNs and configure delegation
5. Part 5: Create and Configure an Azure Enterprise App
6. Part 6: Testing the configuration

Part 1: Activate the K2 REST API

1. Log into K2 as Administrator and navigate to the K2 Management site – such as https://k2.denallix.com/management/
2. Expand the Integration > APIs  > Workflow REST node
3. Enable the Workflow REST API with the toggle next to Workflow API
4. Select V1 in the API version drop-down and copy the Base URL for the REST API endpoint. For example https://k2.denallix.com/api/workflow/v1
5. If the internal URL is different from the external URL used to access the API through the AAD app proxy, you need to add the external URL to the Cross-Origin Resource Sharing (CORS) list of allowed domains.
6. Click Apply Changes to continue. The configuration should look like this:
   
7. Copy the Swagger URL and open it in a new browser window to confirm you can access it. The swagger URL link is similar to https://k2.denallix.com/api/workflow/v1/swagger. The browser output should look like this:
   

Part 2: Change authentication settings for the REST API virtual directory

The K2 REST API needs to accept Kerberos tickets from the AAD app proxy connector service. Use this section to change the configuration of the K2 REST API virtual directories to accept these. You must do this even if your K2 installation was set to use Kerberos during installation.

1. Open IIS and expand your K2 website.
2. Select the API node and double-click Authentication under the IIS section.
   
3. Enable Anonymous Authentication and Windows Authentication, as shown below:
   
4. Within the API node, select the Workflow node and double-click Authentication under the IIS section. Enable Anonymous Authentication and Windows Authentication.
5. With the Workflow node still selected, right-click the Windows Authentication item in the list and select Providers. Add the Negotiate provider and set the sequence to be Negotiate and then NTLM, as shown below:
   
6. Within the Workflow node, select the V1 node and double-click Authentication under the IIS section. Enable Anonymous Authentication and Windows Authentication.
7. With the V1 node still selected, right-click the Windows Authentication item in the list and select Providers. Add the Negotiate provider and set the sequence to be Negotiate and then NTLM.
8. With the V1 node still selected, open the Advanced Settings (on the far right of the window) and note the application pool in use. For example, K2_net4. 
9. Click Application Pools and note the account used by the application pool from the previous step.
   
10. If you are using the Preview version of the REST endpoint in your organization, repeat steps 5 and 6 for the Preview endpoint. (Note that most applications and code should preferably use the V1 endpoint)
11. Open command prompt or PowerShell as an administrator and perform an IISRESET to complete the IIS configuration.

Part 3: Configure the AAD App Proxy connector

The Azure AD application proxy uses a connector service running on an internal server to establish an outbound connection to Azure, and inbound connections to the internal K2 REST broker. Follow these steps to install and configure the AAD app proxy connector.

1. Navigate to https://portal.azure.com and sign in as a tenant administrator.
2. Select Azure Active Directory from the left vertical link list.
3. Select Application proxy from the link list displayed in the next blade.
4. If required, create a new connector group to contain the new connector.
5. Click on Download connector service to download the connector installer.
6. Connect to the internal server that you intend to use to host the app proxy connector service. Then run the downloaded connector service installer.
7. When prompted to sign in to Azure, do so with a user that has permissions to create connectors.
8. After refreshing the Application proxy page in the Azure portal, you should now see the internal server FQN listed. If the connector is not listed in the correct group, change the assigned connector group by clicking on the connector in the list.

Part 4: Create Kerberos SPNs and configure delegation

You need a Kerberos configuration to allow the AAD app proxy to impersonate the logged-in user through to the K2 Workflow REST API web application. The connector service uses the AAD UPN to create a corresponding AD Kerberos ticket to pass to the K2 server. Follow these steps to create the required SPNs and configure delegation between the services.

1. Log onto a server with an account that has permissions in AD to run the SetSPN command. Start either a command prompt or PowerShell as administrator and execute this command:
   setspn -s HTTP/[host]:[port] [domainaccountname]
   • Substitute [APISiteName] with the DNS name of your API site – for example k2.denallix.com
   • Substitute [domain][accountName] with the service account for the API virtual directory application pool noted above in the Change authentication settings for the REST API virtual directory section.
   An example of the SPN command is:
   setspn -s HTTP/k2.denallix.com DenallixK2Service
2. Log on to a domain controller or a server with access to Active Directory Users and Computers and open it.
3. Configure delegation for the computer hosting the AAD app proxy connector service:
   1. Search for the computer that is hosting the AAD app proxy connector service and open its properties.
   2. Select the Delegation tab.
   3. Select Trust this computer for delegation to specified services only and User any authentication protocol.
   4. Click Add, click Users or Computers and search for the service account used for the SPN in step 1 above. Select it and click OK.
   5. The delegation tab of the properties page for the computer that is hosting the AAD app proxy connector service should look like this:
      
4. Configure delegation for the application pool account:
   1. Search for the application pool account used in the SPN (for example, denallixk2Service), open its Properties.
   2. Select the Delegation tab.
   3. Select Trust this computer for delegation to specified services only and User any authentication protocol.
   4. Click Add, click Users or Computers and search for the computer that is hosting the AAD app proxy connector service. Select it and click OK.
   5. The delegation tab of the properties page for the app pool account should look like this:
      

Part 5: Create and Configure an Azure Enterprise App

You need an Azure enterprise app to be able to make authenticated external connections to the internal REST service. Use the following steps to configure an enterprise app to work with the new connector you created in the preceding steps.

1. Navigate to https://portal.azure.com and sign in as a tenant administrator.
2. Navigate to Azure Active Directory > Application proxy and select Configure an app.
   1. Name: enter a name for the enterprise app
   2. Internal URL: enter the URL used to access the REST service on the internal network. Using the example earlier in this article, the URL would be https://k2.denallix.com/api/workflow/v1/
   3. External URL: choose an external URL. If possible, this should be the same as the internal URL.
   4. Select Azure Active Directory for pre-authentication.
   5. Select the connector group chosen in the earlier section of this article.
   6. For Translate URLs In, set both Header and Body to Yes. It may not be necessary to have Application Body set to Yes but keep this set in the beginning and turn it off later to improve performance if needed. You should not need Translation if using the same URL for external and internal.
   7. Leave all other settings as default.
3. Click Add to create the new enterprise app.
4. Once you have created the app, click the Owners link for the app and assign your administrator user as an app owner.
5. Select the Users and groups link and add any users from AAD that need access to the REST broker.
   Make sure that you add the user testing the configuration to this list. You need to have created this user through AAD connect and the user must have a corresponding Active Directory user account.
6. Select Single sign-on in the link list for the app.
7. Select Windows Integrated Authentication.
8. Configure WIA as follows:
   1. Internal Application SPN: This will be like the SPN created earlier in this article, excluding the account name, for example:
      HTTP/k2.denallix.com
   2. Delegated Login Identity: Select On-premises SAM account name
   3. Click Save to save the single sign-on settings.
9. Navigate back to the root Azure Active Directory section in the Azure portal and select App registrations.
10. Select the app you just created.
11. Click the Authentication link.
12. Ensure there are two redirect URIs registered, the base URL for the REST service (external) and the base URL with .auth/login/aad/callback appended. The Redirect URIs list should look like this:
    
13. Click Save to save the redirect URIs.

Part 6: Testing the configuration

Basic browser-based test

1. Open a browser and navigate to the swagger page of the Workflow REST API using the external URL. For example,
   https://k2testaadap-mydomain.msappproxy.net/api/workflow/v1/swagger
2. When prompted to sign in to AAD, sign in with a user you added during step 5 of the previous section.
3. If the configuration is correct you will see a similar swagger API overview page as shown in the first section of this document.

Use Postman to perform a test call to the Workflow REST API

You need the following information to request an access token from Azure to call the AAD app proxy URL:

• Callback URL
• Auth URL and Access Token URL
• Client ID
• Client Secret

Now you can get an access token and call the K2 Workflow REST API.

Get the Callback URL

1. Log on to the Azure portal site as a tenant administrator.
2. Click on Azure Active Directory.
3. Click on App registrations.
4. Select the app created previously.
5. Select the link under Redirect URIs in the main area on the right.
6. Copy the URI created previously ending with .auth/login/aad/callback.

Get the Auth URL and Access Token URL

1. Log on to the Azure portal site as a tenant administrator.
2. Click on Azure Active Directory.
3. Click on App registrations.
4. Select the app created previously.
5. Select Endpoints at the top of the main area on the right.
6. Copy the following URLs:
   1. Auth URL: OAuth 2.0 authorization endpoint (v1)
   2. Access token URL: OAuth 2.0 token endpoint (v1)

Get the client ID

1. Log on to the Azure portal site as a tenant administrator.
2. Click on Azure Active Directory.
3. Click on App registrations.
4. Select the app created previously.
5. Copy the GUID under Application (client) ID in the main area on the right.

Create and copy the client secret

1. Log on to the Azure portal site as a tenant administrator.
2. Click on Azure Active Directory.
3. Click on App registrations.
4. Select the app created previously.
5. Click the Certificates and Secrets link in the vertical link list displayed.
6. Under Client secrets click New client secret, provide a description, select the desired expiration and click Add.
7. Copy the client secret value displayed.

Get an access token and call the K2 Workflow REST API

1. Open postman and create a new request.
2. Change the request type/verb to POST and enter the full external URL for the API resource you wish to call. In this case, we will be starting a new K2 workflow instance using postman. An example of the URL is:
   https://k2test-myexternaldomain.msappproxy.net/api/workflow/v1/workflows/8
   The URL above calls the workflows method and passes the process ID 8. Retrieve the process ID for the desired workflow using the K2 management site. Navigate to the desired workflow and note the ID in the query string.
3. Select the Authorization tab.
4. Change the Type to OAuth 2.0 and Add authentication data to Request Headers.
5. Select Get New Access Token and use the information you copied earlier to fill in the pop-up window. Your screen should look like this:
   
6. Click Request Token. When the AAD login window shows, sign in using the test user account from earlier. AAD should create a token and pass it to Postman.
7. Select the new token, scroll to the bottom and select Use Token. This should show the token on the right.
8. Click the Headers tab.
9. Add a new key called Content-Type with value application/json.
10. Click the Body tab.
11. Select the raw radio button and set the drop-down on the right to JSON. Copy the following JSON into the body section:
    {
    "folio": "Test #00001",
    "expectedDuration": 86400,
    "priority": 1
    }
12. Click Send to call the API. If all configurations are correct, you should see a 200 OK status response with a new process instance ID in the body.
13. Navigate to the process overview in the K2 Management site and confirm the new process instance with the folio information provided.