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:
- 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
- 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
- Enable the APIs. Step 3: Enable the relevant K2 API
- 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 4: Using OAuth
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.
- Open the AAD app that you're using to retrieve a token for the K2 API resource and click Required permissions.
- Click Add
- Click Select an API and search for K2 API:
- Select the K2 API from the list and click Select. Note that you may see K2 API App or other K2-related permission scopes in this list. Select only the K2 API permission scope.
- Click Select permissions and select Access K2 API.
- Click Select.
- Click Done and you see the K2 API listed in the list of permission scopes.
- Click the Grant Permissions button in the toolbar so that your users will not be prompted to consent for the K2 API app.
- Repeat these steps for any additional AAD apps that need to call K2 services
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 linkage is what makes it possible for K2 to read the incoming token and grant access to the API.
Step 3: 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:
- Open the K2 Management site
- Go to Integration > APIs > Workflow REST
- Click the Workflow API slider to turn on the service as shown here:
To enable the SmartObject OData API:
- Open the K2 Management site
- Go to Integration > APIs > SmartObject OData
- 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:
To set up AAD consent:
- Open the K2 Management site
- Go to Integration > APIs
- 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.
Step 4: 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:
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.