K2 and upcoming changes to Exchange Online authentication

In September 2019, Microsoft announced plans to turn off Basic Authentication for Exchange Web Services (EWS) for Exchange Online, with a subsequent announcement in April 2020 that the change may happen sometime during the second half of 2021. The following  Microsoft articles have more information about the change:

This notification from Microsoft may lead to questions about your K2 environments and whether they will be affected by these changes. This article attempts to address the most common questions arising from this change in authentication support.

K2 uses Basic authentication when integrating with Exchange Online. Because Microsoft is deprecating Basic authentication for EWS, K2 is replacing Basic Authentication with OAuth authentication for Exchange integration. All current Exchange Online connections that use Basic authentication will not work once Microsoft disables support for Basic Authentication. To prepare for this change, you will need to edit integration points between K2 and Exchange Online to be OAuth-enabled.

The K2 fix packs released during April 2020 include an upgrade for the K2 Connection String Editor tool to make it OAuth compatible, and an update to Exchange Online integration to support OAuth authentication.

FAQs about the authentication change

Q: Does K2 use EWS + Basic Authentication for Exchange Online integration?
A: Yes

Q: Which K2 components are affected by the change?
A: Workflow SmartActions, Workflow Notifications, Email reminders, the Workflow Email Step and SmartForms Send Email rule action. 

Q: Which K2 versions are affected?
A: K2 Cloud, K2 Five and K2 blackpearl.

Q: Will this upcoming Microsoft change affect supported Exchange on-premises versions?
A: No. Exchange on-premises will not be affected by this change.

Q: Does K2 have a plan to address this change prior to the 2021 deadline?
A: Yes. K2 will update Exchange Online integration to utilize OAuth authentication in a series of Fix Packs released during April 2020. The Fix Packs include an updated K2 Connection String Editor tool to allow you to set up OAuth connections where necessary. 

Q: What will happen if we do not make the necessary changes/fixes in our K2 environment by the deadline?
A: If the fix is not applied before the 2021 deadline, any communication between your K2 system and Exchange Online will fail. That means the following will not work:

  • SmartActions
  • Async steps – sent by MessageBus
  • Escalations
  • Email steps – Workflow designer and inflight message sending
  • Forms with a send email rule
  • Workflow message sending
  • Can't send email errors can occur, and notifications will not work. An example of the error you may encounter:
    SourceCode.WorkFlow.Common.EWS: Autodiscover not available and mail cannot be sent. Reconfigure K2 server with valid Exchange settings.

Q: How do we address the issue if we missed the deadline for switching to OAuth?
A: Apply the solution steps described in this article, and then retry any errors in the Workflow Errors section of K2 Management.

Q: Are SmartObjects that use the Exchange Management, Exchange Administration and Exchange Metadata Service Types affected? 
A: No. These Service Types do not support Exchange Online and therefore are not affected

Q: Are the Exchange Wizards affected?
A: No. These wizards do not support Exchange Online and therefore are not affected.

Q: Are the SmartObjects using the Exchange Online Service Broker affected?
A: It depends on the Authentication Mode used for the Service Instance:   

      • Using OAuth Authentication: Not affected, OAuth Authentication will remain fully supported after this change.
      • Using Impersonate Authentication: Not affected, Impersonate Authentication is only supported for Exchange On-premises which will not be affected by this change.
      • Using Static Authentication for Exchange On-premises: Not affected, Exchange On-premises is not affected by this change.
      • Using Static Authentication for Exchange Online: Affected, Static Authentication credentials are passed using Basic Authentication which will no longer be supported. Change the service instance to use OAuth Authentication instead.

Solution

Before making the required changes to your K2 environment, download the Fix Pack that applies to your K2 version:

List of Fix Packs by version of K2:

Solution Steps: K2 Five 5.1, 5.2 and 5.3

  1. Apply the appropriate Fix Pack for your K2 environment.
  2. Enable and/or configure the Exchange Online Feature in your K2 environment to use OAuth authentication, as described in the User Guide. Ensure that the email address you use when switching to OAuth is the tenant admin's email address.
  3. Use the K2 Connection String Editor tool to configure the EWS connection strings. Expand the section below for details.

    Applying the Fix Pack updates the K2 connection string editor to support connection stings that use OAuth instead of Basic authentication. Follow these steps to configure connection strings for Exchange destination and connection:

    1. Open the connection string editor at [K2 installation path]\Host Server\Bin\ConnectionStringEditor.exe.
    2. Remove SMTP connection entries by selecting them each and clicking the Remove Connection String button.
    3. Add a connection string for Exchange Web Services and another for Exchange Web Service Destination
    4. Enter the following values for the connection properties. The ConnectionString property in the Data section builds automatically as you enter the values.
      Property Value
      Behavior
      Poll Interval Leave blank
      Connection
      Autodiscover True
      Delegate Leave blank
      OAuth Resource The OAuth Resource property value is the OAuth Resource Name for your Exchange Online integration. For example: ExchangeApp
      OAuth Resource Audience The OAuth Resource Audience property is the URL for Exchange online: https://outlook.office365.com
      Password * Leave blank
      URL The EWS URL: https://outlook.office365.com/EWS/Exchange.asmx
      User ID Your tenant admin email address, for example: admin@M365x123456.onmicrosoft.com
      Data
      ConnectionString Automatically generated based on the values you enter.
         
      * If the Exchange connection and destination password property is empty, K2 tries to retrieve the OAuth token using the OAuth Resource and OAuth Resource Audience property values. These property values are the same as those in your K2 OAuth resource for Exchange Online. If there is any value in the password field, K2 reverts to Basic authentication when connecting to EWS.
    5. Restart the K2 Server service after editing your EWS connections.
  4. Verify the changes in K2 Management and the K2HostServer.exe.config file. Expand the section below for details.
    1. Use K2 Management Site to verify that your Azure tenant admin email address is set for the From Address in the Environment Library variables and in the Workflow Server > String Table variable. You access these properties in K2 Management as shown below:

    2. Use the K2 Management Site to verify that the Exchange Online Feature is configured to use OAuth authentication.
    3. In the K2HostServer.exe.config file located at located at [K2 installation path]\Host Server\Bin\K2HostServer.exe.config, check that the system self tag is correct. It must be the AAD security label and the Azure tenant admin email address.
    4. Still within the K2HostServer.exe.config file, search for the sendmailfrom property and check that the value is the Azure admin email address.
    5. Still within the K2HostServer.exe.config file and if you are using SmartActions, check these properties: enableListeners="true" and "SmartActions\EWS" as in the image.

Solution Steps: K2 Five 5.0 and K2 blackpearl 4.7

  1. Apply the appropriate Fix Pack for your K2 environment.
  2. Manually configure an app in AAD that grants the needed permissions to pass the OAuth token. Expand the section below for details.

    In K2 blackpearl 4.7 and K2 Five (5.0) you must manually configure an app in Azure to grant admin consent and create an OAuth token for authentication when using EWS and Exchange Online. Use these steps to register an app in AAD that grants the needed permissions to pass the OAuth token. (Once the app is registered, you will set up an OAuth resource in K2 to request authorization tokens from Azure.)

    1. Find and record your Directory ID/Tenant ID.
      1. Log in to https://portal.azure.com/ and navigate to your Active Directory Domain.
      2. Click Azure Active Directory.
      3. Click Properties and copy the Directory ID for later use.
    2. Click the App registrations item on the blade and then click New registration.
    3. The Register an application blade opens.
      • Give your app a Name (this is the user-facing display name for this application).
      • Select who can use this application or access this API in the Supported account types.
      • Specify a Redirect URI for your K2 environment. For example, https://k2.denallix.com/Runtime/. This is the URL used to sign into forms.
      Click the Register button at the bottom to create your app. See the modifying the manifest file section for information on adding your other K2 sites (Designer, for example) to the app so that you can log-in to those sites with an AAD identity.

      Your app is now in the list of apps when you select App registrations. Select your new app to continue.
    4. Copy the Application ID for later use.
    5. Edit your app's branding details by clicking Branding under the Manage menu:
      1. You can edit your app's user-facing display name.
      2. You can also upload a logo.
      3. In the Home page URL box, enter the URL where users can sign in and use your application, for example https://k2.denallix.com/Runtime/
      4. You can leave the Terms of service URL and Privacy statement URL empty.
      5. Click Save to continue.
    6. Edit your app's Redirect URIs by clicking Authentication under the Manage menu. Redirect URIs are the URIs that Azure accepts as destinations when returning authentication responses (tokens) after successfully authenticating users. Redirect URIs are also known as Reply URLs.
      Enter your K2 runtime site URL and the token endpoint reply URL to the list:
      • Token endpoint reply URL - https://{K2SiteURL}/identity/token/oauth/2
      Your list of Reply URLs should look similar to the following image but with your K2 details. Click Save to continue.

      You can leave the Logout URL field empty. Click Save to continue.
    7. Export the K2 OAuth High Trust certificate from the Personal branch of your K2 server and upload it to your AAD tenant. Also copy the certificate thumbprint for later use.
      1. Open the Manage Computer Certificates MMC on your K2 server and export the K2 OAuth High Trust certificate found in the Personal > Certificates branch. Do this by right clicking the certificate and selecting All Tasks > Export.
      2. Use the default options:
        - No, do not export the private key
        - DER encoded binary X.509 (.CER)
      3. Browse to a folder to save the key and type a file name, for example K2 OAuth High Trust.cer.

        Click Next to continue.
      4. Check your setting in the last page then click Finish to export the certificate.
      5. In Azure Portal, click Certificates & secrets under the Manage menu for your app.
      6. Click Upload certificate and select the certificate you exported and click Add.
        The Certificates section is updated with your key.
      7. Copy the Thumbprint as you will need it in later steps.
    8. Find and copy your Client Secret for later steps.
      1. In your AAD tenant, click Certificates & secrets under the Manage menu for your app. Then click New client secret under the Client secrets section.
      2. 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 later steps.

      You cannot retrieve this value once you leave the blade so make sure you copy and store it now.
    9. Set permissions for the app using the following steps:
      1. In your AAD tenant, click API permissions under the Manage menu for your app then click Add a permission.
      2. Click Microsoft APIs and then select Exchange from the Supported Legacy APIs section.

        Check the following permissions in the Application Permissions and the Delegated Permissions sections:
        Application Permissions Delegated Permissions
        Full_access_as_app (Use Exchange Web Services with full access to all mailboxes) EWS.AccessAsUser.All (Access mailboxes as the signed-in user via Exchange Web Services)
          User.Read (Read user profiles)
      3. Grant admin consent on behalf of all users in the directory by clicking the Grant admin consent for <directory name> button and then the Yes button on the query.

        You see admin consent is granted for the new permissions.
    10. Update the manifest file to log in to other K2 sites.
      1. In your AAD tenant, click Manifest under the Manage menu for your app.
      2. Enter URIs for each of your sites similar to the following example:

        Microsoft made a change in AAD that invalidates the manifest file if URIs contain trailing forward slashes, but K2 requires the trailing slash in identifier URIs. As a workaround, leave the slash out of the manifest file when you configure it in the Azure user interface. After you save the manifest file, edit and run the following PowerShell script that will add the trailing slashes. Remember to edit the Azure app name value to match the name of the app you created in Azure, and change the sample IdentifierURIs and ReplyURLs values to your K2 environment’s values. When you run the script and get prompted for credentials, be sure to log in as an Azure Tenant Admin
        # Start of script

        $AzureAppName = ""; # App Display Name in https://portal.azure.com

        Function Connect-Azure
        {
            $AzureAD = Get-Module AzureAD;
            If(!$AzureAD)
            {
                Import-Module AzureAD -WarningAction SilentlyContinue;
                Install-Module AzureAD -SkipPublisherCheck -Force -Confirm:$false -WarningAction SilentlyContinue;
            }

                 Connect-AzureAD;
        }

        Function Configure-App
        {
            $AzureApp = Get-AzureADApplication -Filter "DisplayName eq '$($AzureAppName)'";
            If($AzureApp)
            {
                Set-AzureADApplication -ObjectId $AzureApp.ObjectId `
                                       -IdentifierUris "https://k2.denallix.com/Designer/", "https://k2.denallix.com/Runtime/" `
                                       -ReplyUrls "https://k2.denallix.com/Designer/", "https://k2.denallix.com/Runtime/", "https://k2.denallix.com/identity/token/oauth/2";
            }
        }

        Connect-Azure;
        Configure-App;

        #End of Script
      3. Click Save to continue.
    11. In your AAD tenant, click Overview for your app and then click Endpoints.

      Copy and save the URLs for later use. You need the following items:
      • Federation metadata document URL
      • OAuth 2.0 token endpoint URL
      • OAuth 2.0 authorization endpoint URL
      • WS-Federation sign-on endpoint
      The GUID portion of these URLs is your Tenant ID.

    This ends your AAD app configuration. You should have the following items for configuring K2:

    • Application ID / Client ID. You can get it from the Overview blade. Used as Authorization, Token and Refresh value of client_id OAuth resource property in K2.
    • Client secret. Used in all values of client_secret OAuth resource property in K2.
    • Federation metadata document URL. Copy it from Overview > Endpoints page.
    • OAuth 2.0 authorization endpoint. Copy it from Overview> Endpoints page. Used when adding a New OAuth Resource in K2.
    • OAuth 2.0 token endpoint URL. Copy it from Overview> Endpoints page. Used when adding New OAuth Resource in K2.
    • Directory ID / Tenant ID. GUID part which can be found in above-mentioned endpoint URLs, or on the Overview blade. Used as token value of resource_id OAuth resource property in K2.
    • Thumbprint. Copied from the uploaded certificate on the Certificates & secrets blade.
  3. Register an OAuth resource in K2. Expand the section below for details.

    After you've configured an app in AAD, set up an OAuth resource in K2 to request authorization tokens from AAD. Remember that your Tenant ID is the GUID portion of your copied URLs.

    1. Open the K2 Management site and on the dashboard click the View OAuth Settings link, or expand the Authentication > OAuth > Resources nodes, and then do the following:
      1. Under Resources click New.
      2. Enter a Resource Name.
      3. Select Microsoft Online AppOnly for the Resource Type. For information on creating resource types see the topic Resource Types in the User Guide.
      4. Enter the Authorization Endpoint, without the query string parameters, from the AAD App you created earlier (Example: https://login.microsoftonline.com/{YourTenantID}/oauth2/authorize).
      5. Enter the Token Endpoint, without the query string parameters, from the AAD App you created earlier (Example: https://login.microsoftonline.com/{YourTenantID}/oauth2/token).
      6. Leave the Use Host Server Authorization Endpoint check box unchecked and click OK.
    2. Select the resource from the Resources list and you'll see the Resource Parameters section update. Follow these steps using the Resource Parameters section:
      1. Select client_id from the Resource Parameters list and click Edit. Enter the Application ID from the AAD app you created in Step 2 for the Authorization Value, the Token Value and the Refresh Value and click OK.
      2. Select redirect_uri from the Resource Parameters list and click Edit. Enter https://{YourK2Server}/identity/token/oauth/2 for the Authorization Value and the Token Value and click OK (replace {YourK2Server} with the server name or host header value to your K2 site).
      3. Select api_version from the Resource Parameters list and click Edit. Enter 1.0 for the Authorization Value, the Token Value and the Refresh Value and click OK.
      4. Select scope from the Resource Parameters list and click Edit. Enter reader for the Authorization Value and click OK.
      5. Select response_type from the Resource Parameters list and click Edit. Enter code for the Authorization Value and click OK.
      6. Select resource from the Resource Parameters list and click Edit. Enter https://outlook.office365.com for the Authorization Value, the Token Value and the Refresh Value and click OK.
      7. Select client_secret from the Resource Parameters list and click Edit. Enter the Client Secret from the AAD app you created in Step 2 for the Authorization Value, the Token Value and the Refresh Value and click OK.
      8. Select entity_id from the Resource Parameters list and click Edit. Enter your Tenant ID (the GUID in your endpoints) in the Token Value and click OK.
  4. Use the K2 Connection String Editor tool to configure the EWS connection string. Expand the section below for details.

    Applying the Fix Pack updates the K2 connection string editor to support connection stings that use OAuth instead of Basic authentication. Follow these steps to configure connection strings for Exchange destination and connection:

    1. Open the connection string editor at [K2 installation path]\Host Server\Bin\ConnectionStringEditor.exe.
    2. Remove SMTP connection entries by selecting them each and clicking the Remove Connection String button.
    3. Add a connection string for Exchange Web Services and another for Exchange Web Service Destination
    4. Enter the following values for the connection properties. The ConnectionString property in the Data section builds automatically as you enter the values.
      Property Value
      Behavior
      Poll Interval Leave blank
      Connection
      Autodiscover True
      Delegate Leave blank
      OAuth Resource The OAuth Resource property value is the OAuth Resource Name for your Exchange Online integration. When using K2 4.7 or K2 Five 5.0, it will be the name of the app you created in Azure that grants admin consent and creates an OAuth token for authentication when using EWS. For example: ExchangeApp
      OAuth Resource Audience The OAuth Resource Audience property is the URL for Exchange online: https://outlook.office365.com
      Password * Leave blank
      URL The EWS URL: https://outlook.office365.com/EWS/Exchange.asmx
      User ID Your tenant admin email address, for example: admin@M365x123456.onmicrosoft.com
      Data
      ConnectionString Automatically generated based on the values you enter.
         
      * If the Exchange connection and destination password property is empty, K2 tries to retrieve the OAuth token using the OAuth Resource and OAuth Resource Audience property values. These property values are the same as those in your K2 OAuth resource for Exchange Online. If there is any value in the password field, K2 reverts to Basic authentication when connecting to EWS.
    5. Restart the K2 Server service after editing your EWS connections.
  5. Verify the changes in K2 Management and the K2HostServer.exe.config file. Expand the section below for details.
    1. Use K2 Management Site to verify that your Azure tenant admin email address is set for the From Address in the Environment Library variables and in the Workflow Server > String Table variable. You access these properties in K2 Management as shown below:

    2. Use the K2 Management Site to verify that the OAuth Resource you configured as described in Register an OAuth Resource in K2 is set correctly.
    3. In the K2HostServer.exe.config file located at located at [K2 installation path]\Host Server\Bin\K2HostServer.exe.config, check that the system self tag is correct. It must be the AAD security label and the Azure tenant admin email address.
    4. Still within the K2HostServer.exe.config file, search for the sendmailfrom property and check that the value is the Azure admin email address.
    5. Still within the K2HostServer.exe.config file and if you are using SmartActions, check these properties: enableListeners="true" and "SmartActions\EWS" as in the image.