Skip to main content

Configure AAD and K2 Services for Inbound OAuth

KB002784

PRODUCT
K2 Cloud
K2 Five
BASED ON
K2 Cloud (all)
TAGS
Integration
Identity Integration

This article is only relevant to the following cumulative updates:

If you have installed one of these cumulative updates, and intend to upgrade your system to either K2 Five (5.4) or (5.5), you must only use one of these product builds:

Using any other product builds will render your K2 installation unusable.

The screenshots and instructions for third-party software are accurate at the time of publication. Third-party vendors may have changed or updated aspects of their systems (such as user interfaces, functionality, and security). As a result, this content may be outdated.
K2 Cloud uses Open ID Connect (OIDC) to authenticate and authorize users. If you were using OAuth in K2 Cloud, or need to use OAuth in a new application that uses the K2 APIs, you'll need to configure Postman and/or your code to use new client IDs and redirect URIs/Auth URLs. See the article How to retrieve client IDs and Redirect URIs for use in OAuth against K2 APIs for more detail.

This article explains how to configure your K2 environment to use inbound OAuth tokens for online apps to retrieve workflow and SmartObject data from K2. It is recommended that you use OAuth instead of basic authentication when calling the K2 Workflow REST or SmartObject Data APIs from online apps (such as Microsoft Flow or your own custom app) because OAuth is more flexible, more secure, and automatically works with Multi-Factor Authentication (MFA).

Before you begin, review the terms "Inbound OAuth" and "Outbound OAuth" to determine what configuration is required for your needs. These terms refer to the direction that OAuth tokens are flowing, and the direction is described from the perspective of the K2 server.

  • Inbound OAuth: this means 'incoming' integration where third-party systems need to interact with K2 APIs. Examples include custom applications that need to start workflows, retrieve and complete workflow tasks, or execute SmartObject methods via K2 APIs. In this scenario, the bearer token is verified and used by K2 to authorize the incoming request. These incoming tokens are not cached by K2. This article describes how to set up and use inbound OAuth.
  • Outbound OAuth: this means 'outgoing' integration where K2 needs to interact with other systems through SmartObjects, and the underlying Service Instance for the SmartObject is configured to use OAuth authentication.  In this scenario, K2 acts on behalf of an AAD user using Refresh Tokens, issued by AAD (or some other identity provider) and cached by K2. Examples include when K2 needs to interact with a third-party service such as SharePoint, Exchange, and CRM and pass through the OAuth credentials of a connected user. For more information about outbound OAuth token flow, see Outbound Authorization and OAuth in K2.

Configuring your environment to use inbound OAuth involves the following steps:

  1. If AAD is not already configured as a user manager in your K2 environment, set that up first. If you are a K2 Cloud customer, you already have AAD configured and you do not need to perform this step. Step 1: Using AAD as a User Manager in K2
  2. Add the K2 API permission scope to your AAD app or apps that need to connect to K2. If you're a K2 Cloud customer, you already have apps in your AAD tenant, but you must still configure your AAD apps with the K2 API permission scope. Step 2: Add the K2 API permission scope to your AAD apps
  3. If the Bearer Token OAuth resource is not already configured in K2 for your AAD app, use Step 3: Configure the Bearer Token OAuth resource in K2 to configure it.
  4. Enable the APIs. Step 4: Enable the relevant K2 API
  5. Integrate a third-party app such as Microsoft Flow with K2, or write code that uses OAuth to authenticate with the K2 Workflow REST API or the SmartObject OData service. Step 5: Using OAuth

Configuration Steps

Use these steps to set up an incoming OAuth token flow.

Step 1: Using AAD as a User Manager in K2

This step is only necessary for K2 Five customers. If you have integrated your K2 Five environment with SharePoint Online using the K2 for SharePoint app, this configuration is done for you automatically. If you do not use SharePoint Online, you must manually configure K2 to integrate with Azure Active Directory. See Manually Configure K2 for Azure Active Directory (AAD) topic in the Installation and Configuration Guide for instructions on configuring AAD as a user manager in K2.

Step 2: Add the K2 API permission scope to your AAD apps

Add the K2 API permission scope to your Azure AD apps. If you configured AAD integration manually, add this permission to your custom AAD app.

If you use K2 Cloud, or configured AAD automatically by using the K2 for SharePoint Online registration wizard, K2 Apps are automatically added to your Azure tenant, as shown here. These K2 Apps are read-only and cannot be edited, so you cannot add the K2 API permission scope to them. In this case, you must create a new Azure app and add the K2 API permissions to it.
existingk2apps3.png
  1. Open the AAD app that you're using to retrieve a token for the K2 API resource and click API permissions.
  2. Click Add a permission
  3. Click APIs my organization uses and search for K2 API:
  4. Select the K2 API from the list. Note that you may see K2 API App or other K2-related permission scopes in this list. Select only the K2 API permission scope.
  5. Under the Select permissions section, select Access K2 API.
  6. Click Add permissions.
  7. You see the K2 API listed in the list of permission scopes.
  8. Click the Grant admin consent for etenant] button so that your users will not be prompted to consent for the K2 API app.
  9. Add a Client Secret to identify this resource when you configure your client. In your AAD tenant, click Certificates & secrets under the Manage menu for your app. Then click New client secret under the Client secrets section. Type a Description for the key and select an expiry time. Click Add to generate a Key Value. The Key Value is your Client Secret - copy it for when you configure your client.
    You cannot retrieve this value once you leave the blade so make sure you copy and store it now.
  10. Repeat these steps for any additional AAD apps that need to call K2 services.

Step 3: Configure the Bearer Token OAuth resource in K2

The K2 API permission scope uses the URL https://api.k2.com/ which is, in turn, linked to the Bearer Token OAuth resource audience as shown here. This link allows K2 to read the incoming token and grant access to the API.
Image
If your environment does not have the Bearer Token OAuth resource type with the https://api.k2.com audience token, create it manually by doing the following.

  1. Click on New resource and enter a name, for example K2 API.
  2. Select Bearer Token as the resource type in the drop-down box.
  3. Enter the Authorization Endpoint, this is the OAuth 2.0 authorization endpoint (v1) value for your app in AAD. For example: https://login.microsoftonline.com/{Tenant_ID}/oauth2/authorize
    You can get the endpoints for your custom AAD app by clicking Overview and selecting Endpoints like in this image.
  4. Enter the Token Endpoint, this is the OAuth 2.0 token endpoint (v1) for your app in AAD. For example: https://login.microsoftonline.com/{Tenant_ID}/oauth2/token
  5. Leave the Refresh Token Endpoint field empty.
  6. Enter the Metadata Endpoint. This is the OpenID Connect metadata document endpoint for your app in AAD. As K2 uses v1 of the endpoint, ensure you delete the v2.0/ section when you copy and paste the endpoint. For example: https://login.microsoftonline.com/{Teanant_ID}/.well-known/openid-configuration
  7. Leave the Use Host Server Authorization Endpoint checkbox unchecked and click OK.
  8. Select your new resource and select audience in the Resource Parameters section and click New.
  9. Select audience in the Parameter Name drop-down and enter https://api.k2.com/ as the Token Value and click OK to finish.
  10. Reset IIS by performing an iisreset from a command prompt. 

Step 4: Enable the relevant K2 API

If you have not already done so, use the K2 Management Site to enable the API you want to integrate with. See the K2 Five Product Documentation or K2 Cloud Product Documentation for more on enabling the Workflow and SmartObject REST APIs. Once you have enabled the relevant APIs, you should set up AAD consent.

To enable the Workflow REST API:
  1. Open the K2 Management site
  2. Go to Integration > APIs > Workflow REST
  3. Click the Workflow API slider to turn on the service as shown here:
    Image
To enable the SmartObject OData API:
  1. Open the K2 Management site
  2. Go to Integration > APIs > SmartObject OData
  3. Click the SmartObject OData API slider to turn on the service as shown here, and configure the service to expose the SmartObjects you want to interact with:Image
To set up AAD consent:
If you configured AAD manually, you need to manually grant Admin consent by editing the {YourTenantID} value in the following URL with your details, then browsing to the URL.
https://login.microsoftonline.com/{YourTenantID}/oauth2/authorize?client_id=57928c92-7074-45f8-b89e-fe2556ac187f&response_type=code&redirect_uri=https://help.nintex.com/en-US/HELP_DOC/AADpages/AADSuccess.html&resource=https://api.k2.com&prompt=admin_consent​
If you did not configure AAD manually, continue with the steps below.
  1. Open the K2 Management site
  2. Go to Integration > APIs
  3. Click on the SETUP AAD CONSENT button to run through the wizard to grant consent for the APIs to access AAD. You be an AAD Tenant Admin to grant consent.
    Image

Step 5: Using OAuth

Once your AAD apps include permission to access the K2 API and your K2 environment is configured to validate OAuth tokens, you can integrate with online applications like Microsoft Flow or write code to interact with the K2 services. See the following links for more information:

If you're using Postman to test your configuration, you must add ?resource=https://api.k2.com/ to the end of your Auth URL in the Get New Access Token dialog as shown here:
Image

Once you get the token, use it to make a GET call to the workflows endpoint as shown here. This retrieves a list of the workflows deployed to your K2 server and is a good test to see if the K2 server is handling the incoming OAuth token properly. For more information about using Postman, see How To: Use Postman to Test the Workflow REST API using OAuth.
Image

Hi @GrahamGoode,

 

Great knowledge article! Thanks for sharing it.

 

I have few questions though:

 

  1. Does inbound flow works for K2 5.3 on-prem?
  2. How does third-party app invoke K2 workflow REST API (which resides in a private network) via AAD auth?
  3. I would like to invoke K2 Workflow from MS PowerApps without using a gateway or setting up firewall rules to allow inbound traffic. Does this flow allow to achieve this?

Regards

NK

May I know how to create a new Azure app for K2 Cloud?

 

In the note of Step2, it is described that "If you use K2 Cloud, or configured AAD automatically by using the K2 for SharePoint Online registration wizard, K2 Apps are automatically added to your Azure tenant, as shown here. These K2 Apps are read-only and cannot be edited, so you cannot add the K2 API permission scope to them".

 

In the article below, the steps to configure K2 for AAD is described but it was for K2 Five, and I am not sure if it can be applied for K2 Cloud as well because it mentioned the steps in windows server.

So I would like to confirm how to create AAD app for K2 Cloud manually.
Manually Configure K2 for Azure Active Directory (AAD) (nintex.com)

Reply


View our Community Site Map

Nintex Community Sitemap
Terms & ConditionsCookie settings