Integrating K2 Five and Azure Government Cloud Computing High Security(GCC)

Follow the instructions in the Microsoft article Install Azure PowerShell on Windows with MSI to install or update the Azure PowerShell module. At the time of writing, the latest version of the module is 8.2.0.

After installation, run PowerShell and connect to your tenant with the following command:

Follow the prompts and log in using the Azure Government tenant Global Admin credentials.

Now we add K2 for Office 365 and Exchange Online for K2 in preparation for installing and configuring K2 in later steps.

Add the K2 for Office 365 and grant the requested permissions.

1. Open a browser and navigate to the following URL. Change the [tenant] placeholder to your tenant name:

https://login.microsoftonline.us/[tenant].onmicrosoft.com/adminconsent?client_id=ca5cc53d-936b-4e82-ba6c-6b013c961933

2. When prompted, log in with the Global Admin credentials.
3. Accept the Permissions requested.
   
4. Click OK on the trust site.
5. Navigate to the Azure Government site:
   https://portal.azure.us
6. Select the Azure Active Directory tile and then in the Manage section, select Enterprise Application. You should see that the K2 for Office 365 app has been added and permissions granted.
   

Next, create Application ID, client secret, and apply security certificate

7. Copy the Application ID for the K2 for Office 365 app from the Enterprise applications page.
8. Replace the [Application ID] placeholder in the first of the following three commands with what you copied in the step above. Then paste these three lines into PowerShell and run them.

Copy

Create App ID and Client Secret

1
2
3
$app = Get-AzADServicePrincipal -ApplicationId [Application ID]
$spcreds = New-AzADSpCredential -ObjectId $app.Id -StartDate (Get-Date) -EndDate ((Get-Date).AddYears(2))
$app.Id

9. PowerShell returns the K2 for Office 365 Application ID (a GUID).
10. Now create the Client Secret by running the following command in PowerShell:
    $spcreds.SecretText
    PowerShell returns the Client Secret for the K2 for Office 365 app. Copy the Client Secret and save it for later.
11. Run the following PowerShell command to add the security certificate and certify for K2 for Office 365.

Copy

Create the certificate

$cert = 'MIIEuDCCAqCgAwIBAgIQNMwnmSR8Y59HI0wwDDqiGDANBgkqhkiG9w0BAQUFADAYMRYwFAYDVQQDEw1LMiBVbml0IFRlc3RzMB4XDTIxMDkyOTExMjAyNVoXDTIyMDkzMDEyMjAyNVowGDEWMBQGA1UEAxMNSzIgVW5pdCBUZXN0czCCAiIwDQYJKoZIhvcNAQEBBQADggIPADCCAgoCggIBAKjamEJqG0nZBIgVpQ5gjyaQrCpFK9ermCbi0V9fMI+ZgwArDn8YxwUi6CBNCh4o3HFaO8FYD2OrbkkbMa15xx7wG9SrK2w39uRT4f1HOC82Kzv8wfl8kAZJh+eXfBqG07m5z2/fGL7RJTnmbsOIBIGFUcBao1dz/pLyrye4SLuK5YP9CUhWjhR0Pqu4eaK/gcEsk9vjW49ObyZhgi7matR3Dg3TfeE9IIV7zOSFexE/FxPDOldvddC+i+jglUCk/kwMgB2u+EAi4GEp3nvYTOvXGr4ZHsZZQfukzooMeQWC4DItfDl/tmZmZpzxHDawVF7Jg/egXCELfaMnlEprXSLFWMDk1xcchLpnR9fvThmW2T5FyXYAwXHk7J1pK7ldgYFAG9xPtr4i1p4T21AZcg6ghcRd/JFCBPffDhvD1t+Byp7sAvbxcehQBvuoN/yGjsYyMUI8/o861bWNrUl8QWySDGDGZOcsphBF8YOwG4x4jZibKD1zUnoJkkKSWDhjSwMandCb/4tpjFOKwu4to6b2EYKpk3JenIVtnCauqcNzgu6so4lhWeP8j13YnXIr4io7rqgn7Uwce7lCObZWY7b9FMbOGlYeDDZ9COSNsi6BY06/SrjE9ffnNHp/FM4mvayl5sekBzd815xVOic2VR+X/Mi6BOr0KmmBEJhIfQhtAgMBAAEwDQYJKoZIhvcNAQEFBQADggIBAJITlIUvVWA5IAtJ5buiE68Cr5ZHeRWzCzAEI6fgLuA+fnEiNvLiDkNbB2lIK57Q0UkOxyVuFj+D3oWBxjMPTM2twaz/vYmnA5IHJBbCu7NJpB/6DWXvleYRt4kzLx+QNGFf34qIEf8Q781l4IioLdSTMrAdVuuoFk9kOalOn99OS95LiS8/52U5binler5Bja2DltkYs5ezJTq9DYRvZjNi90fmTFxC/gSKbBl18qb7NIbYhreO1io9OkvhgtfP89FaYR8d7JxlzptUPu8yMCqOF427x5dW8ttqfhvwJcrfVZzyomRk7y9HMtesWcQ9eM/kJ8iwsfC7nDUuzgVjQHzPNLuZJGiNB6YDbCWSIaBlNYoIuzkZzAu7u8MaKOcFjD5RYEk5LgIQlDr0Q9tMuJ4q6QVJv7eimTFaJdetToA350PUJYw0aJsDGW+LwHHJsWtPnXcUIdtbEdIyr37Y8kCWimgS5tIe6yKatLETuQyV7mr24E9FsDJUe9Rv/XMVf9IsPXgwHFxekcuANl3cqUjH7XS4lZXfMdeD+fd9ifbOsJNg8rqNEk7x3zzxI+nHJnsosJ9K7uxTK3++ASs5FnhNFvye7JyKhWGgfiWHVE34ZF878vDtSLZTuegQMugbUFuYxrWx0bT+HL1PAx36x4Fixkx7W7YSU+88/D8wgS6M' 
$cer = [X509Certificate]::new([convert]::FromBase64String($cert))
$credential = New-Object -TypeName "Microsoft.Azure.PowerShell.Cmdlets.Resources.MSGraph.Models.ApiV10.MicrosoftGraphKeyCredential" -Property @{'Key'=($cer.GetRawCertData());  'Usage'='Verify';   'Type'='AsymmetricX509Cert'}
$spcreds = New-AzADSpCredential -ObjectId $app.Id -KeyCredentials $credential

12. Refresh the browser on the Azure portal - Enterprise applications and you will see that the K2 for Office 365 app now has a certificate.
    

Add the Exchange Online for K2 and grant the requested permissions.

1. Open a browser and navigate to the following URL. Change the [tenant] placeholder to your tenant name:

https://login.microsoftonline.us/[tenant].onmicrosoft.com/adminconsent?client_id=3f1562d9-2baa-43be-ae20-b15d94b07194

2. When prompted, log in with the Global Admin credentials.
3. Accept the Permissions requested.
   
4. Click OK on the trust site.
5. Navigate to the Azure Government site:
   
   https://portal.azure.us
6. Select the Azure Active Directory tile and then in the Manage section, select Enterprise Application. You should see that the Exchange Online for K2 app has been added and permissions granted.
   

Next, create Application ID, client secret, and apply security certificate

7. Copy the Application ID for the Exchange Online for K2 app from the Enterprise applications page.
8. Replace the [Application ID] placeholder in the first of the following three commands with what you copied in the step above. Then paste these three lines into PowerShell and run them.
   
   
9. Copy

   Create App ID and Client Secret

   1
   2
   3
   $app = Get-AzADServicePrincipal -ApplicationId [Application ID]
   $spcreds = New-AzADSpCredential -ObjectId $app.Id -StartDate (Get-Date) -EndDate ((Get-Date).AddYears(2))
   $app.Id

10. PowerShell returns the Exchange Online for K2 Application ID (a GUID).
11. Now create the Client Secret by running the following command in PowerShell:
    $spcreds.SecretText
    PowerShell returns the Client Secret for the Exchange Online for K2 app. Copy the Client Secret and save it for later.
12. Run the following PowerShell command to add the security certificate and certify for Exchange Online for K2 .

Copy

Create the certificate

$cert = 'MIIEuDCCAqCgAwIBAgIQNMwnmSR8Y59HI0wwDDqiGDANBgkqhkiG9w0BAQUFADAYMRYwFAYDVQQDEw1LMiBVbml0IFRlc3RzMB4XDTIxMDkyOTExMjAyNVoXDTIyMDkzMDEyMjAyNVowGDEWMBQGA1UEAxMNSzIgVW5pdCBUZXN0czCCAiIwDQYJKoZIhvcNAQEBBQADggIPADCCAgoCggIBAKjamEJqG0nZBIgVpQ5gjyaQrCpFK9ermCbi0V9fMI+ZgwArDn8YxwUi6CBNCh4o3HFaO8FYD2OrbkkbMa15xx7wG9SrK2w39uRT4f1HOC82Kzv8wfl8kAZJh+eXfBqG07m5z2/fGL7RJTnmbsOIBIGFUcBao1dz/pLyrye4SLuK5YP9CUhWjhR0Pqu4eaK/gcEsk9vjW49ObyZhgi7matR3Dg3TfeE9IIV7zOSFexE/FxPDOldvddC+i+jglUCk/kwMgB2u+EAi4GEp3nvYTOvXGr4ZHsZZQfukzooMeQWC4DItfDl/tmZmZpzxHDawVF7Jg/egXCELfaMnlEprXSLFWMDk1xcchLpnR9fvThmW2T5FyXYAwXHk7J1pK7ldgYFAG9xPtr4i1p4T21AZcg6ghcRd/JFCBPffDhvD1t+Byp7sAvbxcehQBvuoN/yGjsYyMUI8/o861bWNrUl8QWySDGDGZOcsphBF8YOwG4x4jZibKD1zUnoJkkKSWDhjSwMandCb/4tpjFOKwu4to6b2EYKpk3JenIVtnCauqcNzgu6so4lhWeP8j13YnXIr4io7rqgn7Uwce7lCObZWY7b9FMbOGlYeDDZ9COSNsi6BY06/SrjE9ffnNHp/FM4mvayl5sekBzd815xVOic2VR+X/Mi6BOr0KmmBEJhIfQhtAgMBAAEwDQYJKoZIhvcNAQEFBQADggIBAJITlIUvVWA5IAtJ5buiE68Cr5ZHeRWzCzAEI6fgLuA+fnEiNvLiDkNbB2lIK57Q0UkOxyVuFj+D3oWBxjMPTM2twaz/vYmnA5IHJBbCu7NJpB/6DWXvleYRt4kzLx+QNGFf34qIEf8Q781l4IioLdSTMrAdVuuoFk9kOalOn99OS95LiS8/52U5binler5Bja2DltkYs5ezJTq9DYRvZjNi90fmTFxC/gSKbBl18qb7NIbYhreO1io9OkvhgtfP89FaYR8d7JxlzptUPu8yMCqOF427x5dW8ttqfhvwJcrfVZzyomRk7y9HMtesWcQ9eM/kJ8iwsfC7nDUuzgVjQHzPNLuZJGiNB6YDbCWSIaBlNYoIuzkZzAu7u8MaKOcFjD5RYEk5LgIQlDr0Q9tMuJ4q6QVJv7eimTFaJdetToA350PUJYw0aJsDGW+LwHHJsWtPnXcUIdtbEdIyr37Y8kCWimgS5tIe6yKatLETuQyV7mr24E9FsDJUe9Rv/XMVf9IsPXgwHFxekcuANl3cqUjH7XS4lZXfMdeD+fd9ifbOsJNg8rqNEk7x3zzxI+nHJnsosJ9K7uxTK3++ASs5FnhNFvye7JyKhWGgfiWHVE34ZF878vDtSLZTuegQMugbUFuYxrWx0bT+HL1PAx36x4Fixkx7W7YSU+88/D8wgS6M'
$cer = [X509Certificate]::new([convert]::FromBase64String($cert))
$credential = New-Object -TypeName "Microsoft.Azure.PowerShell.Cmdlets.Resources.MSGraph.Models.ApiV10.MicrosoftGraphKeyCredential" -Property @{'Key'=($cer.GetRawCertData());  'Usage'='Verify';   'Type'='AsymmetricX509Cert'}
$spcreds = New-AzADSpCredential -ObjectId $app.Id -KeyCredentials $credential

13. Refresh the browser on the Azure portal - Enterprise applications and you will see that the K2 for Office 365 app now has a certificate.
    

In this step you configure a SharePoint add-in and register it with Microsoft Azure Access Control Service (ACS) which issues an access token to the add-in that allows the add-in access to the resources in the SharePoint tenancy. For more information see the Microsoft article Three authorization systems for SharePoint Add-ins.

1. Create a new ACS principal using your tenant's appregnew.aspx page.
   1. Navigate to the appregnew.aspx page in your tenant. Replace the [tenant] placeholder in this URL with your tenant name.
   https://[tenant]-admin.sharepoint.us/_layouts/15/appregnew.aspx
   2. Click the Generate button for both the Client ID and Client Secret fields.
   3. Enter app title, domain, and redirect URI, then click Create.
      
   4. Copy the Client ID and Client Secret for use later.
      
2. Set permissions.
   1. Navigate to the appinv.aspx page in your tenant. Replace the [tenant] placeholder in this URL with your tenant name.
   https://[tenant]-admin.sharepoint.us/_layouts/15/appinv.aspx
   2. Paste the Client ID from step 1d above into the App Id field and click Lookup. The other values from step 1 will be filled in.
   3. Copy and paste the following XML into the Permission Request XML text area.
   Copy

   Permission Request XML

   <AppPermissionRequests AllowAppOnlyPolicy="true">
     <AppPermissionRequest Scope="http://sharepoint/content/sitecollection" Right="Manage" />
   </AppPermissionRequests>

   
   
   4. Click Create and then click Trust It on the Do you trust <app title>? page.
      

Perform a standard installation of K2 (as described in the Install section of this guide), with one exception. When you configure the Exchange server, use the following Exchange Online details (replace the [tenant] placeholder with your tenant name):

In this step you will run scripts which change certain default values in files installed during the K2 system install. The changes allow integration with Azure GCC.

1. Download and run the following PowerShell script:
   gccupdate.ps1
   The script changes these resources from https://graph.microsoft.com to https://graph.microsoft.us
   
   • AADResource
   • MSOnlineResource
   • AADGraphClientBaseURL
2. Download the following config file and paste it into [K2 installation folder]\ServiceBroker. The default installation folder for K2 Five is C:\Program Files\K2.
   SourceCode.SmartObjects.Services.SharePoint15.Common.dll.config
   The config file adds a key allowing login to Azure GCC (US).
3. Download and run the following PowerShell script to edit the K2 Designer and Runtime configuration
   webupdate.ps1
   The script changes the Claims metadata base URL from https://login.microsoftonline.com to https://login.microsoftonline.us and backs up the original web.config files to web.config.bak.
4. Run the following two SQL scripts against the K2 database. The scripts make changes to parameters for Microsoft Online AppOnly and SharePoint OAuth resources.

INSERT [Authorization].[OAuthResourceTypeParameter] ([TypeParameterID], [ResourceType], [ParameterName], [ParameterDescription], [UrlEncode], [AuthorizationDefaultValue], [TokenDefaultValue], [RefreshDefaultValue], [AuthorizationRequest], [AuthorizationResponse], [TokenRequest], [TokenResponse], [RefreshRequest], [Encrypted]) VALUES (N'465ad7b0-5d14-4475-9c16-92a74fb4c3a4', N'Microsoft Online AppOnly', N'instance_aware', NULL, 0, N'true', N'true', N'true', 1, 0, 1, 0, 1, 0)
GO

INSERT [Authorization].[OAuthResourceTypeParameter] ([TypeParameterID], [ResourceType], [ParameterName], [ParameterDescription], [UrlEncode], [AuthorizationDefaultValue], [TokenDefaultValue], [RefreshDefaultValue], [AuthorizationRequest], [AuthorizationResponse], [TokenRequest], [TokenResponse], [RefreshRequest], [Encrypted]) VALUES (N'fe5219aa-baa4-4bf9-b6e1-7fbf753366d7', N'SharePoint', N'acs_base_url', NULL, 0, N'https://login.microsoftonline.us', N'https://login.microsoftonline.us', N'https://login.microsoftonline.us', 1, 0, 1, 0, 1, 0)
GO

One row per script should be affected.

1. Navigate to the K2 Management site.
2. Click Manage Features on the Dashboard.
3. Select Exchange Online and click New Instance.
4. Edit the feature values as follows:
   1. Authentication: OAuth
   2. EWS URL: https://outlook.office365.us/EWS/Exchange.asmx
   3. Domain : [tenant].onmicrosoft.com
   4. Email address: k2service@[tenant].onmicrosoft.com
      Replace the [tenant] placeholder with your tenant name.
5. Click Add .
   
6. When prompted, login with the global admin account.
7. Accept the Permissions requested.
   

8. Open a NEW tab in your browser and navigate to another K2 Management site, don't use the already open K2 Management site.
9. Expand Authentication, and OAuth. Then select Resources.
10. Select the Exchange resource to expand the Resource Parameters.
11. Notice that resource in the Resource Parameter list displays as .com instead of .us.
    
12. Edit the resource parameter and change the .com to .us for the Authorization Value, Token Value, and Refresh Value. Click OK to continue.
    
13. Select the client_secret parameter and click Edit.
14. Paste the client secret you created earlier in the Exchange section into the Token and Refresh value fields.
    
15. Click OK to save the changes.

16. Go back to the 1st K2 Management tab where the Configuring Exchange wizard is open. Click Continue.
    
17. When prompted, login with the global admin account.
18. Accept the Permissions requested
    
19. On the Configuring Exchange wizard click Continue.
    
20. Once Exchange Configuration is complete, click Done.
21. Expand Integration and select Services Instances.
22. Select Exchange Online and click Edit.
23. Make sure that the OAuth Resource Audience and EwsURL point to .us and not .com – if not, change to .us and click OK to save the changes.
    
    If you did need to edit the .com to .us, a Service Instance Updated dialog shows, click OK on it to finish.

In this step you will add the K2 for SharePoint app to your SharePoint.US tenant. You will encounter errors and correct the issues by adding some settings to K2's OAuth configuration.

Follow the instructions in the topic on installing the K2 Five for SharePoint app but during the Registration wizard you will encounter an Azure Access Control Service (ACS) error. The steps below explain how to correct this and complete the installation.

1. When the Registration wizard starts and you configure the link to the K2 server, follow the prompts to sign in with your Azure Government tenant global admin credentials.
2. Accept the Permissions request and the let K2Trust site configuration finish.
3. The Registration wizard will start running but an SP error will come up. This is due to the ACS issue.
   
4. Click OK to continue.
5. Click Finish to finalize the Registration wizard.
6. Navigate to the K2 Management site (refresh if it was already open).
7. When asked what account you would like to log in with, select K2 Windows STS.
   
8. Expand the Authentication node and the OAuth node.
9. Click on Resources. Other than the previously added Exchange resource, you will see three new resources: MSOA, AADMGMT, and SP.
10. MSOA Resource configuration
    1. Check that the Authorization and Token endpoints start with https://trust.k2.com/. If they do not, edit them and replace the domain. For example:
       https://trust.k2.com/331zzc78-2f87-43ce-bzzz-d45zzb2b0cf9/authorize/oauth/2/request
       
    2. Select the client_secret resource parameter and click Edit.
    3. Paste the Client Secret you copied when you added the K2 for Office 365 app to the Azure GCC tenant into the Token and Refresh value fields. Then click OK to save and continue.
       
    4. Click New to create a new resource parameter.
    5. Select instance_aware from the drop-down.
    6. Enter true as the Authorization, Token, and Refresh values. Then click OK to save and continue.
       
11. AADMGMT Resource configuration
    1. Check that the Authorization and Token endpoints start with https://trust.k2.com/. If they do not, edit them and replace the domain. For example:
       https://trust.k2.com/331zzc78-2f87-43ce-bzzz-d45zzb2b0cf9/authorize/oauth/2/request
       
    2. Click New to add a new parameter and select client_secret from the drop-down.
    3. Paste the Client Secret you copied when you added the K2 for Office 365 app to the Azure GCC tenant into the Token and Refresh value fields. Then click OK to save and continue.
       
    4. Click New to create a new resource parameter.
    5. Select instance_aware from the drop-down.
    6. Enter true as the Authorization, Token, and Refresh values. Then click OK to save and continue.
       
12. SP Resource configuration
    1. Check that the Token endpoint starts with https://trust.k2.com/. If it does not, edit it and replace the domain. For example:
       https://trust.k2.com/331zzc78-2f87-43ce-bzzz-d45zzb2b0cf9/authorize/oauth/2/request
       
    2. Click New to add a new parameter and select client_secret from the drop-down.
    3. Paste the Client Secret you copied when you configured SharePoint on the Azure GCC tenant into the Token and Refresh value fields. Then click OK to save and continue.
       
    4. Click New to add another new parameter and select acs_base_url from the drop-down.
    5. Enter https://login.microsoftonline.us as the Authorization, Token, and Refresh values. Then click OK to save and continue.
       
    6. You need to change the client_id, but do not do it in the K2 Management site. Instead, navigate to the SourceCode.SmartObjects.Services.SharePoint.Integration.dll.config file in the [K2 installation folder]\ServiceBroker folder.
    7. Open the file in Notepad and find SharePointClientId.
    8. Replace the value with the following:
       c7d9edce-16c7-43b3-a00b-ad4db2810983
       
       Save the file to finish.

Enable uploading K2 pages to SharePoint (for activating new sites)

Before you can run the Activation wizard, you must run a couple commands in the SharePoint Online Management Shell to connect to your SharePoint tenant and allow adding pages.

1. Navigate to SharePoint Online Management Shell.
   
2. Run the following command, replacing the [tenant] placeholder with your tenant name:
   Connect-SPOService -Url https://[tenant]-admin.sharepoint.us
3. Follow the prompts and login with Azure global admin credentials.
4. Run the following command, replacing the [site] placeholder with your K2 SharePoint site:
   Set-SPOSite https://phnintex.sharepoint.us/sites/[site] -DenyAddAndCustomizePages 0
5. Start the Activation wizard in the K2 for SharePoint app, logging in when prompted.
6. During activation, a dialog will pop up informing you that a token will be created on your behalf. Wait for the Authorization Successful page and green ticks on all items in the Activation page.
7. Click OK on the Please log in pop up. Activation is now complete.