Changing from Delegated Permissions to Application Permissions for manually-configured AAD integration

KB002999

If you used the topic Manually Configure K2 for Azure Active Directory (AAD) in the K2 Five Product Documentation to configure your K2 environment with AAD, you would have set up delegated permissions. Using delegated permissions causes the OAuth token for the K2 server to expire every 90 days. You can use the procedure explained in the "OAuth token requires authorization" error article to renew the OAuth token, or you can reconfigure your K2 environment to use an application token flow (also called AppOnly), where the token for the K2 server effectively never expires. However, this approach requires that you reconfigure one of the delegated permissions to use application permissions, and this article describes how to perform this configuration procedure. 

See these links for more information on delegated versus application permissions:

• Microsoft identity platform developer glossary
• Permissions and consent in the Microsoft identity platform endpoint

Steps to change from delegated to application permissions

If you're manually integrating K2 with AAD for the first time, follow the procedure in the Manually Configure K2 for Azure Active Directory (AAD) topic of the K2 Five Installation and Configuration Guide (ICG). This KB article is for people who set up AAD integration using delegated permissions, and who now want to change from delegated permissions to application permissions. Changing from delegated to application permissions follows the same basic steps as in the Installation Guide, but with the differences described in this article.

AAD configuration steps

Perform these steps in your AAD tenant (you need to be an admin on the AAD tenant to do this):

1. Update your Azure AD apps permissions.
   • Edit your AAD app's permissions as described in step 2 of the Manually Configure K2 for Azure Active Directory (AAD) help topic. Make sure the permissions in the table below are checked in AAD.

     Permission name	Type	Description	Admin consent required
     Directory.Read.All	Application	Read directory data	Yes
     Directory.Read.All	Delegated	Read directory data	Yes
     User.Read	Delegated	Sign in and read user profile	No

2. Grant admin consent for the app with the new permissions as described in step 2 of the Manually Configure K2 for Azure Active Directory (AAD) help topic.
3. Update your Manifest so that it doesn’t include trailing slashes for the URIs as described in step 2 of the Manually Configure K2 for Azure Active Directory (AAD) help topic. This is optional but recommended.
   1. If you choose to follow step 3, update the web.config file of the various K2 sites by editing the value for wsFederation > Realms to not include the trailing slash. In the web.config file for your various K2 sites, search for the realm and delete the trailing slash as shown in this image:
      
      Also, in the K2 Management site, edit the realm in K2 Management > Authentication > Claims > Realms and remove the trailing slash as shown in this image:
      

K2 configuration steps

Perform the following configuration on your K2 environment (you need to be a K2 admin to do this):

1. Create a new OAuth resource based on the Microsoft Online AppOnly resource with values based on step 3 of the Manually Configure K2 for Azure Active Directory (AAD) help topic.
2. Run the SQL script to update your AAD label with the new OAuth resource details. Note: do not run the script in the Help topic as it will overwrite your AAD label. You must run the script in this step with the GUID from your existing AAD label to update the label.
   • Edit the SQL script before you run it. Enter the GUID for the AAD label from your K2 database as the value for @SecurityLabelID. To find the GUID do the following:
     1. Open Microsoft SQL Server Management Studio and browse to the HostServer.SecurityLabel table in the K2 database.
     2. Right-click the HostServer.SecurityLabel table and select the top 1000 rows to return the details of the security labels in your environment.
     3. Copy the SecurityLabelID GUID for the AAD label:
        
     4. Enter the GUID for the AAD label from your k2 database as the value for @SecurityLabelID in the SQL script below.
        The line should look similar to this:
        DECLARE @SecurityLabelID UNIQUEIDENTIFIER = 'E7B2D94D-3884-49E9-9363-2935339974F6';
        Remember to put the GUID in single quotes.
     5. Finish editing the script, replacing the AADLabelGUID and OAuthResourceName placeholders, and run it to update your AAD label.
        USEBK2]
        DECLARE @SecurityLabelName NVARCHAR(20) = 'AAD';
        DECLARE @SecurityLabelID UNIQUEIDENTIFIER = '{AADLabelGUID}'; -- This is your AAD label GUID from the DB
        DECLARE @client_ID NVARCHAR(100) = '57928c92-7074-45f8-b89e-fe2556ac187f'; -- This is your Azure application ID
        DECLARE @DefaultLabel BIT = 0;
        DECLARE @ResourceName NVARCHAR(100) = '{OAuthResourceName}'; -- This is the name of your newly-created Azure Resource
        DECLARE @OAuthResourceID NVARCHAR(100) = (
        SELECT
        bResourceID]
        FROM
        bK2]. Authorization].zOAuthResource]
        WHERE
        bResourceType] = 'Microsoft Online AppOnly'
        AND >Name] = @ResourceName
        );
         DECLARE @AuthInit XML = '<AuthInit>
          <OAuthResourceID>' + @OAuthResourceID + '</OAuthResourceID>
          <OAuthResourceAudience>https://api.k2.com</OAuthResourceAudience>
          <ClientID>' + @Client_ID + '</ClientID>
          </AuthInit>' 
        DECLARE @RoleInit XML = '<RoleInit>
          <OAuthResourceID>' + @OAuthResourceID + '</OAuthResourceID>
          <OAuthResourceAudience>https://graph.microsoft.com</OAuthResourceAudience>
          </RoleInit>'
        DECLARE @ProviderID UNIQUEIDENTIFIER = (
        SELECT
        FROM
        DHostServer].OSecurityProvider]
        WHERE
        ]ProviderClassName] = 'SourceCode.Security.Providers.AzureActiveDirectory.SecurityProvider'
        );
        DELETE FROM
        >SecurityLabels]
        WHERE
        ]SecurityLabelName] = @SecurityLabelName;
        INSERT INTO mSecurityLabels]
        VALUES
        (
        @SecurityLabelID, @SecurityLabelName,
        @ProviderID, @AuthInit, @ProviderID,
        @RoleInit, @DefaultLabel
        );
         
     6. After executing the script, manually trigger admin consent for the K2 for AAD Login app by browsing to this link after replacing {YourTenantID} and following prompts on screen:
        
        https://login.microsoftonline.com/{YourTenantID}/oauth2/authorize?client_id=57928c92-7074-45f8-b89e-fe2556ac187f&response_type=code&redirect_uri=https://www.k2.com&resource=https://api.k2.com&prompt=admin_consent
     7. Restart the K2 service.
         
3. Delete all existing AAD tokens.
   1. Browse to Authentication > OAuth > Tokens in the K2 Management site.
   2. Select and delete tokens related to Microsoft Online / AAD

After performing these steps, your AAD integration is switched from using delegated permissions to application permissions. Your OAuth token for the K2 server no longer expires every 90 days.