Manually Configure K2 for Azure Active Directory (AAD)

All communication between K2 and AAD must be encrypted which is why you must SSL-enable your K2 virtual directory.

1. Open Internet Information Services (IIS) Manager.
2. Right click the K2 site and select Edit bindings.
   
3. Click Add.
4. Select https from the Type drop-down list and type a new number in the Port field (typically 443).
5. Select the certificate to use for your site. The *.denallix.com April 2016 certificate, purchased from a Certificate Authority, is used in this example.
   Self-signed and Domain Certificates do not work in this scenario where you're connecting to the cloud, you must use a certificate that AAD can validate.
   
6. Rerun the K2 Setup Manager using the Configure option to update the new HTTPS configuration in the K2 sites configuration. See Reconfigure Environment for how to do this.

You integrate with Azure Active Directory using an Application. Use these steps to create the AAD App and gather information for configuring K2.

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 application registration.
   
3. The Register an application blade opens.Click the
   • 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 example, https://k2.denallix.com/Runtime/. This is the URL used to sign in to forms.
   
   ClickRegister 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 login to those sites with an AAD identity.
   
   Your app is now in the list of apps when you select All apps. 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
   You list of Reply URLs should look similar to the following image but with your K2 server 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. Then 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 your AAD tenant, click Certificates & secrets under the Manage menu for your app.
      
   6. Click Upload certificate and select the certificate you exported in the previous steps. Then click Add.
      The Certificates section is updated with your key.
   7. Copy the Thumbprint as you will refer to it in later steps.
      
8. Find and copy your Client Secret for later use.
   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 use.
   
   
   You cannot retrieve the Key Value/Client Secret once you leave this 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 APIs my organization uses and then select Windows Azure Active Directory from the list.
      
      Check the following permissions in the Delegated Permissions section:
      

      Delegated Permissions
      Read directory data
      Sign in and read user profile

   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 will 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 has 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. After you save the file, edit and run the following PowerShell script. Remember to edit the tenant admin user, password and Azure app name and change the Denallix IdentifierURIs and ReplyURLs to your system's values.
       
       
       # Start of script
       
       $TenantAdmin = ""; # Example admin@example.onmicrosoft.com
       $TenantPassword = "";
       $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;
           }
       
           $AzurePass = ConvertTo-SecureString $TenantPassword -AsPlainText -Force
           $AzureCred = New-Object System.Management.Automation.PSCredential ($TenantAdmin, $AzurePass)
           Connect-AzureAD -Credential $AzureCred;
       }
       
       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.
    
    Federation metadata document URLOAuth 2.0 Token Endpoint URLOAuth 2.0 Authorization Endpoint URLTenant IDWS-Federation Sign-On Endpoint
    • 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. Can be copied from Overview > Endpoints page.
• OAuth 2.0 authorization endpoint. Can be copied from Overview> Endpoints page. Used when adding a New OAuth Resource in K2.
• OAuth 2.0 token endpoint URL. Can be copied 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.

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 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 in Step 2 (Example: https://login.microsoftonline.com/{YourTenantID}/oauth2/authorize).
   5. Enter the Token Endpoint, without the query string parameters, from the AAD App you created in Step 2 (Example: https://login.microsoftonline.com/{YourTenantID}/oauth2/token).
   6. Enter the Federation Metadata Document endpoint you copied in Step 2 (Example: https://login.microsoftonline.com/{YourTenantID}/federationmetadata/2007-06/federationmetadata.xml)
   7. 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://graph.windows.net 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.
      

K2 provides a security provider for AAD. Execute the script below to configure a label for the security provider that uses the OAuth resource you created.

1. Open SQL Manager and connect to the SQL server of the K2 database.
2. Execute the following script after updating it for your environment.
   Executing this script overwrites the existing AAD label.

5. Restart the K2 service.

Creating the Service Instance is an optional step that you need to take if you are planning on using the Azure Active Directory wizards in a workflow to manage AAD properties. Additionally, your custom app delegated permissions must include Read and write directory data, see the permissions section in this topic for more information.

For more information on K2 Service Instances, see the Service Instance topic in the K2 Five User Guide.

1. Open the K2 Management site and select the Integration node.
2. Select Service Instances and click Add.
3. In the Display Name box, enter Azure Active Directory.
4. Enter a description such as Manual Azure Active Directory configuration (optional).
5. In the Service Type dropdown select Azure Active Directory.
6. In the Authentication Mode dropdown select OAuth.
7. In the OAuth Resource Name dropdown select Azure Active Directory (this is the resource you created earlier).
8. In the OAuth Resource Audience box, enter https://graph.windows.net
   
9. Click OK. You will get an OAuth error, click OK to be redirected to an AAD login page.
   
10. Sign in as your tenant admin. The Read Directory Data delegated permission requires this permission level. If you are using the AAD wizards, you must have granted the app Read and Write Directory Data delegated permission. If you did not do this, go back and do it now before proceeding.
    
11. You should now get the authorization successful message.
    
12. Navigate back to your service instance configuration and click OK to create the instance.
13. Click OK again and note your new service instance in the list.
14. Select it and click Generate SmartObjects.
    
15. Check Select All and then click OK the generate SmartObjects.
    
16. Once the SmartObjects are generated, click the Integration node on the left and search for Azure in the SmartObjects pane on the right. Select the User SmartObject and click Execute.
    
17. The final step is to populate your K2 identity table with AAD identities. Select the Get List method on the Execute SmartObject Method window and click Execute.
    

Follow these steps to configure AAD claims in K2.

• Add a new Issuer
• Add the Issuer Claim
• Map the realm you want to associate with the AAD claims

1. New Issuer.
   You need a Claim Issuer in K2 to map the Security Token Service (STS) signing certificate with the security tokens.
   1. Open K2 Management and expand the Authentication > Claims > Issuers node.
   2. Click New.
   3. Enter a Name and Description for the AAD Issuer.
   4. Enter the Token Issuer Endpoint for AAD in the Issuer text box. (Example: https://sts.windows.net/{YourTenantID}/). Make sure to add a trailing slash in the Issuer URL.
   5. Enter the Login URL for AAD in the URI text box. This is the WS-Federation Sign-On Endpoint from Step 2 (Example: https://login.microsoftonline.com/{YourTenantID}/wsfed).
   6. Enter the thumbprint of the token-signing certificate for AAD that you obtained in Step 2 above. As there are other X509Certificate values in the Federated Metadata XML file, there will be more than one Thumbprint. If the first one causes an issue, try the others before contacting support.
   7. Check the Use for Login check box and click OK to add the AAD issuer.
      
2. Add the Issuer Claim (Claims mappings).
   Claims mappings are used to identify the incoming claims and map them to the appropriate K2 security label. See the K2 Five User Guide for general information about claim mapping
   1. Open the K2 Management Site and expand Authentication > Claims > Claims.
   2. Click New on the Security Label view.
   3. Select the security provider you configured in Step 6 from the Security Label drop down.
   4. Select the issuer you configured earlier from the Issuer drop down.
   5. Check the Claim Type info box.
   6. Leave the Name Identity Issuer text box empty.
   7. Enter the User Token Identifier: i:0#.f|membership. This is the identifier that SharePoint uses to identify users.
   8. Enter the Group Token Identifier: c:0-.f|rolemanager. This is the identifier that SharePoint uses to identify groups.
   9. For the Identity Provider > Original Issuer text box enter the Original Issuer value for AAD (Example: https://sts.windows.net/{YourTenantID}/).
   10. For the Identity Provider > Claim Type text box enter http://schemas.microsoft.com/identity/claims/tenantid.
   11. For the Identity Provider > Claim Value text box enter your Tenant ID for AAD
   12. For the Identity > Original Issuer text box enter the Original Issuer value for AAD (Example: https://sts.windows.net/{YourTenantID}/).
   13. For the Identity > Claim Type text box enter the Claim Type value for AAD (Example: http://schemas.xmlsoap.org/ws/2005/05/identity/claims/name).
   14. Leave the Identity > Claim Value text box empty as this claim is different for each user that logs in.
   15. Click OK to add the mapping.
       
   For more information about the encoding for the user and group identifiers see https://social.technet.microsoft.com/wiki/contents/articles/13921.sharepoint-20102013-claims-encoding.aspx
3. Map the Realm you want to associate with the authentication.
   The realm is the unique value that associates the K2 site with the claims authentication options. Audience URIs are the actual URLs that you use to access the K2 site. You can specify extra Audience URIs for a single Realm. For example, if you use https://k2.denallix.com/Runtime and http://dlx:82/Runtime to access the same underlying site, you need both URLs registered as Audience URIs.
   
   Realms must exactly match your identifier URIs (Reply URLs) that you added to the Azure app's manifest.
   
   Link each realm to your AAD issuer by following these steps:
   1. Open the K2 Management Site and expand Authentication > Claims > Realms.
   2. The list of Realms should be preconfigured with your Runtime, Designer, and View Flow realms and Audience URIs. For each realm for which you need to enable AAD authentication, follow these steps:
   3. Select the Realm and click Edit.
   4. In the Edit Realm dialog use the checkbox list control to select the issuers for the realm.
   5. Click OK.
      

If AAD is the only Linked Issuer configured for your Realm in the previous step, you should be redirected to the Azure Active Directory log in page. If there is more than one Linked Issuer configured you will see a page with a drop down that lets you select the Linked Issuer that you want to use. Authentication that you have previously been using to access your sites are likely cached by your browser. If this is the case, clear your browser cache.

Do the following to test:

• Clear your browser cache
• Close your browser
• Reopen your browser and navigate to https://k2.denallix.com/Designer/
• You should see the following:
  
• Select Azure Active Directory from the drop down
• The Microsoft Sign in page opens. Log in with an Azure identity other than your tenant administrator (for testing purposes)
  
• Verify your login