Integrating K2 with Exchange Online using OAuth with lesser permissions

K2 uses Exchange Web Services (EWS) and Azure app-only OAuth authentication for Exchange Online integration. The recommended way of configuring this integration is to use the Exchange Feature in K2 Management which requires the full_access_as_app application permission, and this permission requires the Azure Global Administrator role. Global Admin Consent is a requirement from Azure, and with this method there is no lesser permission to be set for an app-only implementation.

To be able to use lesser permissions, you need to manually set up an app in Azure with the EWS.AccessAsUser.All delegation permission and configure the corresponding OAuth resource in K2.

Use the information in this article to manually set up an app in Azure with the required minimum permissions, and configure K2 integration. The final section of this article is a demonstration of the steps needed to test the integration.

This article requires knowledge of Azure, SQL, and K2 OAuth configuration.

Prerequisites

  • The minimum TLS settings required for K2 to send mail. See the K2 and TLS 1.2 Support article for information.

  • Ensure your local Active Directory (AD) K2 Service account (this is the user account that runs the K2 Server) email address is the same as the K2 Service account email address in Microsoft 365 (Office 365/AAD). If you already have Azure Active Directory (AAD) configured, you can skip this.

    Other than the K2 Service Account, this article uses a recipient, Jane Doe, with the email address: janed@{your domain name}.onmicrosoft.com in the testing section. To use this recipient and follow the testing section exactly, make sure you have this email address in local AD and in AAD, otherwise use one of your own user accounts.
  • Exchange impersonation: the From Address account in K2 that sends the email (in the case of this article it is k2serviceonline@{your domain name}.onmicrosoft.com) requires impersonation rights.
    If you have the latest K2 Five cumulative update / fixpack for your version, you don't need to set up impersonation.

    To apply impersonation rights to the account, do the following.
    • Open Windows PowerShell ISE and paste this script into the coding area. Then edit your tenant admin email address (the XXXXXXX section below) and execute the script.
      Copy

      Impersonation PowerShell script

      Install-Module ExchangeOnlineManagement; # Accept prompts
      Import-Module ExchangeOnlineManagement; # Accept prompts
      Connect-ExchangeOnline -UserPrincipalName admin@XXXXXXX.onmicrosoft.com; # Will be redirected to login
      New-ManagementRoleAssignment -Name 'Demo App Impersonation' -Role:ApplicationImpersonation -User:k2serviceonline@XXXXXXX.onmicrosoft.com 

Create an app in Azure with the needed permissions scope that will allow K2 integration with Exchange Online using OAuth authentication.

Log in to Azure on https://portal.azure.com. Then perform the following steps.

  1. Click Azure Active Directory.
  2. Click the App registrations item on the blade and then click New registration. The Register an application blade opens.
  3. Give your app a Name (this is the user-facing display name for this application).
  4. Select who can use this application or access this API in the Supported account types.
  5. Specify a Redirect URI by selecting Web in the and then entering your Redirect URI.
    • Get your Redirect URI by navigating to your K2 Management site, expand Environment Library and look for your Web Service URL SSL value. For example:
      https://{WebServiceURLSSLValue}/identity/token/oauth/2.
  6. Click the Register button at the bottom to create your app.

For example:

Details needed for the K2 configuration

  1. Copy the following values to use in the K2 configuration steps later in this article.
    • Application (client) ID
    • Directory (tenant) ID
    • Redirect URI
  2. Once your app has been created, click Endpoints.

    Copy the following values:
    • OAuth 2.0 authorization endpoint (v1)
    • OAuth 2.0 token endpoint (v1)
    • Federation metadata document

Configure Permissions

  1. In the left pane, click API permissions. The following default permission is shown:
  2. Click on the ellipsis on the right of the permission and click on Remove All permissions
  3. Add a new permission
    1. Click Add a permission.
    2. On the right-hand side click APIs my organization uses and search for Office 365 Exchange Online.
    3. Select the API that was returned and click on Delegated permissions.
    4. Navigate down to EWS and click the checkbox for EWS.AccessAsUser.All, then click the Add permissions at the bottom of that pane.

For example:

Create a client secret

  1. In the left-hand blade click Certificates & secrets.
  2. Under Client secrets (0), click New client secret.
  3. Enter a Description and a value for Expires. Then click Add.
  4. Copy the newly created client secret for use later.
  1. Navigate to your K2 Management site.
  2. In the menu on the left, expand Authentication > OAuth.
  3. Click Resources.
  4. On the right-hand side, click New under Resources.
  5. Enter the values you copied earlier for each of the fields like in this example:
  6. Copy your Resource Name to use later.
  7. Click your newly created resource to select it and edit the Resource Parameters like in this example. Use the values you copied earlier:

Create a new instance of the Exchange Online service type and configure it to authenticate using the OAuth resource you created earlier.

For this step you must open your browser as the K2 Service Account (the account that runs the K2 server). To do so in Microsoft Edge:

  1. Hold down the Shift key.
  2. Right-click the Microsoft Edge icon.
  3. Then click the Run as different user option.
  4. Log in with the local K2 Service Account credentials.
  1. Navigate to your K2 Management site.
  2. In the menu on the left, expand Integration.
  3. Click Service Types.
  4. On the right-hand side, find and select the Exchange Online service type.
  5. Click New Instance.
  6. Enter a Display Name and select the OAuth Resource you created earlier. Make sure the other fields are the same as in this image.
  7. Optional: To cache the OAuth token for the service account for using SmartObjects in workflow steps, check the box in the Extra section, like in this image.
  8. Under the Service Keys section, enter the following values:
    • EwsUrl: https://outlook.office365.com/EWS/Exchange.asmx
    • On Behalf Of Email: Your Microsoft 365 K2 Service Account email address
  9. Click OK to register the Service Instance.
  10. The following OAuth error will pop-up, click OK.
  11. When you're prompted, sign-in to your tenant using your Microsoft 365 K2 Service Account credentials.
  12. When prompted for permissions, click Accept.

    The result:
  13. Click on your K2 Management tab to return to the registration dialog and click OK again. When prompted with the Service Instance Created dialog, click OK to close it.

Open the K2 Connection Editor to edit the K2 connection strings and configure for OAuth authentication.

  1. Navigate to the HostServer\Bin folder in your K2 installation folder. By default: C:\Program Files\K2\Host Server\Bin.
  2. Launch the ConnectionStringEditor.exe.
  3. Once launched, the following connections are shown on the left-hand side:
    SourceCode.MessageBus.Ews.ExchangeWebServicesConnection (Your Microsoft 365 K2 Service Account email address)
    SourceCode.MessageBus.Ews.ExchangeWebServicesDestination (Your Microsoft 365 K2 Service Account email address)
    SourceCode.MessageBus.Ews.ExchangeWebServicesDestination
    These connections will show if you have previously configured K2 to integrate with Exchange Online. Yours may be different.
  4. Click each list item and change the Connection values on the right-hand side to reflect these values:
    • Autodiscover: False.
    • OAuth Resource: Enter the name of the OAuth Resource you created earlier.
    • OAuth Resource Audience: https://outlook.office365.com.
    • User ID: Enter your Microsoft 365 K2 Service Account email address.
  5. Click the Save icon and when prompted to update database, click Yes.

For details on configuring email security, see the topic Customizing SmartActions E-mail Security on the K2 Server.

You must set the property <security spamSecurity="Off"> for this integration.

on the system self value.

The value for system self will either be your K2 service account Fully Qualified Name (FQN) from local Active Directory and look like this:
K2:DOMAIN\Username
Or if you have AAD already manually configured and your user is resolved in the [Identity.Identity] table, you FQN would look like this:
AAD:k2serviceonline@{You Domain Name}.onmicrosoft.com

Save the K2HostServer.exe.config file and restart the K2 sever.

The following three examples show methods of using Exchange Online integration with K2. Use these examples to test your manual integration.

Other than the K2 Service Account, these examples use a recipient, Jane Doe, with the email address: janed@{your domain name}.onmicrosoft.com. To use this recipient and follow the testing section exactly, make sure you have this email address in local AD and in AAD, otherwise use one of your own user accounts. Whatever user you use, their email address in your local Active Directory must be the same as their email address online in Microsoft 365.

Design time set up

Create a workflow with a Task event and a Send Email event, then deploy the workflow.

  1. Navigate to your K2 Designer.
  2. Create a new workflow called Exchange Test, in a new folder also called Exchange Test.
  3. Drag a Task event onto the canvas and configure it as follows:
    1. Set the Actions to Approve.
    2. Set the Recipients to your test user. For example, Jane Doe (janed@{your domain name}.onmicrosoft.com).
    3. Check the Customize Notification field in Task Notification, and enter a subject. For example, Exchange Task Email Test.
  4. Drag on a Send Mail event and configure it as follows (using your recipients email):
  5. Connect the events and deploy the workflow.

Runtime test

  1. Navigate to your K2 Management site.
  2. Start a new instance of your workflow.
  3. Open Outlook as your recipient (the user you are using to test).

  4. Reply to the email with Approve.
  5. If integration is successful, you will receive a confirmation.

  1. Navigate to your K2 Management site as you K2 service account.
  2. Edit your Exchange Online service instance and check the Generate SmartObjects for this Service Instance box.
  3. Navigate to your K2 Designer site as a normal user.
  4. Create a new workflow.
  5. In the workflow toolbox, browse to the Email SmartObject that was just generated. For example at: SmartObjects > Exchange Online > Exchange Online Test
  6. Drag two Email events onto the canvas.
  7. Add a variable called Return ID with a data type string.
  8. Configure the first email event as follows (using your test user):
  9. Map the return Id to the newly created variable Return ID.
  10. Configure the second email event as follows:
  11. Deploy your workflow.

Runtime test

Start a new instance of your workflow. The workflow creates and sends an email to your test user (janed@{your domain name}.onmicrosoft.com).

When a normal user executes one of the SmartObjects generated in Example 2 above, they will be redirected to login because they do not have a token:

 

Troubleshooting

  • If your workflow fails on the Send Mail event, refer to the Prerequisites at the top of this article (the K2 and TLS point).

    Once you have applied the TLS settings, you will need to Restart the K2 Server and Retry the failed workflow instance

  • If you receive an impersonation error like the following, either install the latest fixpack for your version of K2, or enable impersonation as mentioned in the Prerequisites section.
    Microsoft.Exchange.WebServices.Data.ServiceResponseException: The account does not have permission to impersonate the requested user.
  • You may receive the following error:
    SourceCode.Workflow.Shapes.EWS: Autodiscover Failure -- The Exchange server is not available, the password is incorrect, or the e-mail address K2ServiceOnline@{Your Domain Name}.onmicrosoft.com does not exist.
    If you do, Check the conditions of the error.
    • Check that you can connect to your Exchange server.
    • Check your password.
    • Check that the email address mentioned exists.