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 Create blade opens.
   • Give your app a Name (this is the display name used in Azure).
   • Leave the Application type as Web app / API
   • Specify a Sign-on URL. For example, https://k2.denallix.com/Runtime/. This is the URL used to sign in to forms.
   Click the Create 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. Click Settings and then Properties to continue:
   
5. Edit your app's properties:
   1. Give your app a user-friendly URI by deleting the GUID and replacing it with something else, for example, identity.
   2. You can also upload a logo.
   3. You can leave the Logout URL, Terms of service URL and Privacy statement URL empty.
   4. Set the Multi-tenanted switch to No.
   5. Click Save to continue.
   
6. Add Reply URLs.
   Go back to the Settings blade and click Reply URLs. Add one more Reply URLs 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.
   
7. Find and copy your Client Secret for later use.
   1. On the Settings blade select Keys under the API Access section.
   2. Type a Description for the key and select an expiry time in the drop-down. Click Save 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.
8. Set permissions for the app using the following steps:
   1. Go back to the Settings blade and click Required permissions.
      
   2. Select Windows Azure Active Directory and check the Read directory data and Sign in and read user profile in the Delegated Permissions section.
   3. Click Save to continue.
      
   4. Click Grant Permissions on the Required permissions blade and then click Yes to grant the permissions for all accounts in your tenancy.
      
9. Update the manifest file to log in to other K2 sites.
   1. Close any settings blades that are open and click Manifest on the app screen.
      
   2. Enter URIs for each of your sites similar to the following example:
      
   3. Click Save to continue.
10. Scroll back to the App registrations blade and 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
    • Tenant ID
    • WS-Federation Sign-On Endpoint
    The GUID portion of these URLs is your Tenant ID.
    
11. The last piece of information you need is the Certificate Thumbprint.
    When Microsoft periodically updates the Azure certificate the thumbprint changes. In K2 4.7 with the latest cumulative update, the K2 server uses the metatdataURL to automatically update the thumbprint.
    1. Open a browser and browse to the Federation Metadata Document URL you copied. It should open an XML file.
    2. Find and copy the first X509Certificate value (in the Signature container).
    3. Open a browser and browse to the online SAML fingerprint tool.
    4. Paste the copied X509Certificate value in the form and select the sha1 algorithm checkbox, then click Calculate Fingerprint.
    5. Copy the fingerprint for later use.
       

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

• Application ID / Client ID. You can get it from app properties blade in AAD. Used as Authorization, Token and Refresh value of client_id OAuth resource property in K2.
• Key. The key value which must be copied from the App Keys page at the stage of key creation. Used in all values of client_secret OAuth resource property in K2.
• Metadata URL. Can be copied from App Registrations > Endpoints page.
• OAuth 2.0 Authorization Endpoint. Can be copied from App Registration > Endpoints page. Used when adding a New OAuth Resource in K2.
• OAuth 2.0 Token Endpoint URL. Can be copied from App Registration > 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 in AAD Properties. Used as token value of resource_id OAuth resource property in K2.

• Fingerprint Value. Can be generated with SAML fingerprint tool from the <X509Certificate> value of your app federation metadata document XML file.

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