Manually Configure K2 for Azure Active Directory (AAD)

All communication between K2 and AAD must be encrypted which is why you need to 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 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 Tenant 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 OAuth authorization. For example, https://k2.denallix.com/identity/token/oauth/2.
   Click the Register button at the bottom to create your app.
4. Add your Identifier URIs by editing and running this script.
   
   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. 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 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.

   Microsoft now requires verified domains. You may get an error when you run the script that looks like this:

   Failed to update {your app name} application. Error detail: Values of IdentifierURis property must be verified domain of the organization or its subdomain: https://nintex.k2test.com/Runtime.....

   For more information on verified domains from Microsoft, see this article: Add your custom domain name using the Azure Active Directory portal.

   Copy

   Edit and run the following script that will add the trailing slashes

   1
   2
   3
   4
   5
   6
   7
   8
   9
   10
   11
   12
   13
   14
   15
   16
   17
   18
   19
   20
   21
   22
   23
   24
   # Start of script
                                   $AzureAppName = ""; # App Display Name in https://portal.azure.com
                                   Function Connect-Azure
                                   {
                                   $AzureAD = Get-Module AzureAD;
                                   If(!$AzureAD)
                                   {
                                   Install-Module AzureAD -SkipPublisherCheck -Force -Confirm:$false -WarningAction SilentlyContinue;
                                   Import-Module AzureAD -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/";
                                   }
                                   }
                                   Connect-Azure;
                                   Configure-App;
                       #End of Script

5. Add your additional Redirect URIs to match the Identifier URIs you added by using the script above. The list of Reply URLs should look similar to the following image but with your K2 details.
   
   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.
   
6. Your app is now in the list of apps when you select App registrations. Select your new app to continue.
   
   Copy the Application (client) ID of your new app for later use.
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, then 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 APIs my organization uses and then select Windows Azure Active Directory from the list.
      
      Check the following permissions in the Application Permissions and the Delegated Permissions sections:
      

      Application Permissions	Delegated Permissions
      Read directory data	Read directory data
      	Sign in and read user profile
      	Read all users' basic profiles
      	Access the directory as the signed-in user

   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. 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.

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 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. Do not run this script if you're upgrading your K2 server. For more information about upgrading, see KB002999 Changing from Delegated to Application Permissions for a Manually Configured AAD Integration.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
USE[K2] DECLARE @SecurityLabelName NVARCHAR(20) = 'AAD';
                        DECLARE @SecurityLabelID UNIQUEIDENTIFIER = NEWID();
                        DECLARE @Client_ID NVARCHAR(100) = '{Your Application ID GUID}';
                        -- This is your Azure Application ID
                        DECLARE @DefaultLabel BIT = 0;
                        DECLARE @ResourceName NVARCHAR(100) = '{K2 Resource Name}';
                        -- This is the name of your newly created Azure Resource
                        DECLARE @OAuthResourceID NVARCHAR(100) = (
                        SELECT 
                        [ResourceID] 
                        FROM 
                        [K2].[Authorization].[OAuthResource] 
                        WHERE 
                        [ResourceType] = 'Microsoft Online AppOnly' 
                        AND [Name] = @ResourceName
                        );
                        DECLARE @AuthInit XML = '<AuthInit>
                        <OAuthResourceID>' + @OAuthResourceID + '</OAuthResourceID>
                        <OAuthResourceAudience>https://graph.windows.net</OAuthResourceAudience>
                        <ClientID>' + @Client_ID + '</ClientID>
                        </AuthInit>' DECLARE @RoleInit XML = '<RoleInit>
                        <OAuthResourceID>' + @OAuthResourceID + '</OAuthResourceID>
                        <OAuthResourceAudience>https://graph.windows.net</OAuthResourceAudience>
                        </RoleInit>' DECLARE @ProviderID UNIQUEIDENTIFIER = (
                        SELECT 
                        [SecurityProviderID] 
                        FROM 
                        [HostServer].[SecurityProvider] 
                        WHERE 
                        [ProviderClassName] = 'SourceCode.Security.Providers.AzureActiveDirectory.SecurityProvider'
                        );
                        DELETE FROM 
                        [SecurityLabels] 
                        WHERE 
                        [SecurityLabelName] = @SecurityLabelName;
                        INSERT INTO [SecurityLabels] 
                        VALUES 
                        (
                        @SecurityLabelID, @SecurityLabelName, 
                        @ProviderID, @AuthInit, @ProviderID, 
                        @RoleInit, @DefaultLabel
                        );
                    

3. 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's delegated permissions must include Read and write directory data, see the permissions section in this topic for more information.

For more information 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 menu select Azure Active Directory.
6. In the Authentication Mode menu select OAuth.
7. In the OAuth Resource Name menu 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. If you get an OAuth error, click OK to be redirected to an AAD login page. If you get no error, skip ahead to step 12.
   
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 to 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 K2 OAuth High Trust token-signing certificate for AAD that you obtained in Step 2 above.
   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.
   
   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:
      1. Select the Realm and click Edit.
      2. In the Edit Realm dialog use the checkboxes to select the issuers for the realm.
      3. 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 your K2 Designer site, for example, https://k2.denallix.com/Designer
• You should see the following:
  
• Select the Azure Security Label you created in Step 5 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