Integrating the product 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 the product 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 = 'MIIDvzCCAqegAwIBAgIUA5gwHTJs7pYk1RjIo83Sw+ct3TAwDQYJKoZIhvcNAQELBQAwbzELMAkGA1UEBhMCVVMxCzAJBgNVBAgMAldBMREwDwYDVQQHDAhCZWxsZXZ1ZTELMAkGA1UECgwCSzIxFDASBgNVBAsMC0RldmVsb3BtZW50MR0wGwYDVQQDDBRLMlRydXN0LlByb2QuU2lnbmluZzAeFw0yNDA3MjkxNTA3MzJaFw0zNDA3MjcxNTA3MzJaMG8xCzAJBgNVBAYTAlVTMQswCQYDVQQIDAJXQTERMA8GA1UEBwwIQmVsbGV2dWUxCzAJBgNVBAoMAksyMRQwEgYDVQQLDAtEZXZlbG9wbWVudDEdMBsGA1UEAwwUSzJUcnVzdC5Qcm9kLlNpZ25pbmcwggEiMA0GCSqGSIb3DQEBAQUAA4IBDwAwggEKAoIBAQCoG99bL1arYEsviP0wvd3I5kpSxkM/Ou4v8WO8GR+uzzUrsw/xsK9wAJ5NnNKijOQJ2uAPlHQrXKQJ70n9JGgxK9gzoWvQ5RiCqrxRaSpzicgC4arpkyABxoZmqHul+K6WKOlGQA5zPj3twLqopzogPl6foIrVpwX5EYFoNpWhsqqhUrFh8c2ico69MMFSyw5+zHHFmbaQerzi0n3BRF7Jrnv5FOnx06aEZ4cT5NlHYFsm4wot16XLPpruXFKtI82zTugAip115fIt+63TqLx2fgfhWWHr9WC4zZVnaT5Qs3KsZw/nR/RAxfm0H1k/HIs43gNa9f63FyFk23EY3Nx5AgMBAAGjUzBRMB0GA1UdDgQWBBRA1TNxCyeb9Ros/mZq/sKh/SxZdzAfBgNVHSMEGDAWgBRA1TNxCyeb9Ros/mZq/sKh/SxZdzAPBgNVHRMBAf8EBTADAQH/MA0GCSqGSIb3DQEBCwUAA4IBAQCfMy0kU05gbsh6M+SuR1MRvrvjC0+S2w/DVuDlwAsVN8pZFfWZo9y7m4QbHrh9FkVeVwXkYLd6kRCltHlESYnGGZtBx712OGma/BniDqGBspjSphkRA2smG6SBOyEPXdvY5Ss+14usdws0gmpN9Um8r5kc4wDfvr0s6I9O8odPHMhtqi6GVavY6ozIwyW+XsFmQ1yb2TKdBXIJFGjKIwMztaVv1h5REBKrD+mL5dWJtFzrM6LewXwUYTUIyMJnVeFsG/pN0/6BpPTcEY6+nwJWEXeHLkII3Jzn7fwcvO0upprJhBzOcKzN5WeDek1htW6caAEsrpgD7sJGRJk6lOee' 
$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=94df5a56-cc88-4652-9c6a-3ce5450777fe

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 = 'MIIDvzCCAqegAwIBAgIUA5gwHTJs7pYk1RjIo83Sw+ct3TAwDQYJKoZIhvcNAQELBQAwbzELMAkGA1UEBhMCVVMxCzAJBgNVBAgMAldBMREwDwYDVQQHDAhCZWxsZXZ1ZTELMAkGA1UECgwCSzIxFDASBgNVBAsMC0RldmVsb3BtZW50MR0wGwYDVQQDDBRLMlRydXN0LlByb2QuU2lnbmluZzAeFw0yNDA3MjkxNTA3MzJaFw0zNDA3MjcxNTA3MzJaMG8xCzAJBgNVBAYTAlVTMQswCQYDVQQIDAJXQTERMA8GA1UEBwwIQmVsbGV2dWUxCzAJBgNVBAoMAksyMRQwEgYDVQQLDAtEZXZlbG9wbWVudDEdMBsGA1UEAwwUSzJUcnVzdC5Qcm9kLlNpZ25pbmcwggEiMA0GCSqGSIb3DQEBAQUAA4IBDwAwggEKAoIBAQCoG99bL1arYEsviP0wvd3I5kpSxkM/Ou4v8WO8GR+uzzUrsw/xsK9wAJ5NnNKijOQJ2uAPlHQrXKQJ70n9JGgxK9gzoWvQ5RiCqrxRaSpzicgC4arpkyABxoZmqHul+K6WKOlGQA5zPj3twLqopzogPl6foIrVpwX5EYFoNpWhsqqhUrFh8c2ico69MMFSyw5+zHHFmbaQerzi0n3BRF7Jrnv5FOnx06aEZ4cT5NlHYFsm4wot16XLPpruXFKtI82zTugAip115fIt+63TqLx2fgfhWWHr9WC4zZVnaT5Qs3KsZw/nR/RAxfm0H1k/HIs43gNa9f63FyFk23EY3Nx5AgMBAAGjUzBRMB0GA1UdDgQWBBRA1TNxCyeb9Ros/mZq/sKh/SxZdzAfBgNVHSMEGDAWgBRA1TNxCyeb9Ros/mZq/sKh/SxZdzAPBgNVHRMBAf8EBTADAQH/MA0GCSqGSIb3DQEBCwUAA4IBAQCfMy0kU05gbsh6M+SuR1MRvrvjC0+S2w/DVuDlwAsVN8pZFfWZo9y7m4QbHrh9FkVeVwXkYLd6kRCltHlESYnGGZtBx712OGma/BniDqGBspjSphkRA2smG6SBOyEPXdvY5Ss+14usdws0gmpN9Um8r5kc4wDfvr0s6I9O8odPHMhtqi6GVavY6ozIwyW+XsFmQ1yb2TKdBXIJFGjKIwMztaVv1h5REBKrD+mL5dWJtFzrM6LewXwUYTUIyMJnVeFsG/pN0/6BpPTcEY6+nwJWEXeHLkII3Jzn7fwcvO0upprJhBzOcKzN5WeDek1htW6caAEsrpgD7sJGRJk6lOee'
$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 Exchange Online for K2 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 the product(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 product system install. The changes allow integration with Azure GCC.

1. Contact Customer Support to obtain the following scripts/file
   gccupdate.ps1
   webupdate.ps1
   SourceCode.SmartObjects.Services.SharePoint15.Common.dll.config
   
   The gccupdate.ps1 script changes these resources from https://graph.microsoft.com to https://graph.microsoft.us
   
   • AADResource
   • MSOnlineResource
   • AADGraphClientBaseURL
2. Paste the SourceCode.SmartObjects.Services.SharePoint15.Common.dll.config file into [K2 installation folder]\ServiceBroker. The default installation folder for the product is C:\Program Files\K2.
   
   The config file adds a key allowing login to Azure GCC (US).
3. Run the webupdate.ps1 script to edit the K2 Designer and Runtime configuration
   
   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 product 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 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 Management site, don't use the already open 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 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 Nintex K2 for SharePoint app to your SharePoint.US tenant. You will encounter errors and correct the issues by adding some settings to the products OAuth configuration.

Follow the instructions in the topic on installing the Nintex 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 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 Management site (refresh if it was already open).
7. When asked what account you would like to log in with, select 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 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 product 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 Nintex K2 SharePoint site:
   Set-SPOSite https://phnintex.sharepoint.us/sites/[site] -DenyAddAndCustomizePages 0
5. Start the Activation wizard in the Nintex 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.