Using SharePoint Look Book in your GCC High Tenant (New PNP)

Contributors:

Rob Garrett - Sr. Customer Engineer, Microsoft Federal 

John Unterseher - Sr. Customer Engineer, Microsoft Federal

Martin Ballard - Sr. Customer Engineer, Microsoft Federal 

This article replaces the previous article, which used the - now legacy - version of PnP PowerShell.

What is Look Book? 

Look Book templates are a set of Microsoft-provided site designs that programmatically add custom user interface elements to SharePoint Online sites. Microsoft has published a public web site with a set of showcase templates to should satisfy most customer needs: 

https://lookbook.microsoft.com 

Each category of templates targets the functionality of various industry verticals. For example, the Organization category contains templates for customizing SharePoint sites for Crisis Communication, Organization News, Leadership Information, to name a few. 

SharePoint Look Book templates build upon the open-source Patterns and Practices site provisioning engine: 

https://docs.microsoft.com/en-us/powershell/sharepoint/sharepoint-pnp/sharepoint-pnp-cmdlets?view=sh... 

The templates themselves are a set of web assets (CSS, images, etc.) with accompanying template XML file that instructs the provisioning engine how to apply the customizations to an existing SharePoint Online site collection.  SharePoint Look Book templates follow Microsoft recommended SharePoint User Interface Design principles: 

https://spdesign.azurewebsites.net/ 

Users of Look Book templates should understand that the templates are “after-market” customizations applied to existing site collections. The base SharePoint Online offering in Office 365 does not provide these templates, nor their associated branding/customization. The templates are not available for end users to select from a central gallery as with earlier versions of SharePoint Server on-premises. 

The Look Book web site facilitates the creation of a new Communication site collection and then the application of the template customizations to that site collection. The Look Book provisioning web site achieves this process via a tenant application, which requires tenant administration consent. Administrators deploying the first Look Book templates will see a consent dialog like the following: 

Challenge – Using Look Book in GCC High

Microsoft strives to implement functionality parity between all sovereign clouds. However, since each Office 365 cloud type serves a different customer audience and requirements, functionality will differ between these cloud types. Of the US clouds – Commercial, Government Community Cloud, Government Community Cloud High, and DOD Cloud, the last two offer the least functionality to observe US Federal mandates and compliance.  

As Microsoft develops new functionality for Office 365 and Azure clouds, we typically release new functionality to commercial customers first, and then to the other GCC, GCC High, and DOD tenants later as we comply with FedRAMP and other US Government mandates. Open-source offerings add another layer of complexity since open-source code contains community contribution and is seldom developed with government clouds in mind. 

The Look Book provisioning service (https://lookbook.microsoft.com) relies on open-source Patterns and Practices code and community developed APIs that may operate differently in GCC, GCC High, and DOD clouds.  As an open-source resource, the SharePoint Look Book templates are not directly supported by Microsoft. 

At the time of this writing, the Look Book provisioning service works with the regular Government Community Cloud (GCC) but not in the High variant without modification. GCC High places restrictions on cross domain access as well as script execution. GCC High and GCC reside on two different top-level domains: sharepoint.com vs. Sharepoint.us. 

Solution – Apply Templates via PowerShell 

Recall that the Look Book provisioning service leverages Patterns and Practices APIs to both create new site collections and lay template customization atop. Specifying a GCC High tenant, the service fails during the request to provision a new site collection. Fortunately, we do not require this service to create vanilla Communication or Team site collections in GCC High tenants. Instead, we can create sites in GCC High and then run PowerShell to affect the customizations after. 

The application of Look Book templates, although existing within the Look Book provisioning service, is also available via PowerShell. Assuming a tenant administrator has pre-created an out-of-the-box Communication or Team Site, they may leverage the SharePoint PnP PowerShell Module to apply a template.

The following details the steps to provision a Look Book template via PowerShell:

1. Download the desired templates from the following location: 
   https://github.com/SharePoint/sp-dev-provisioning-templates/tree/master/tenant  
   
   
2. Open a new PowerShell console (v5.1 or Core 7.x).
   
   
3. Ensure the PnP.PowerShell module is loaded with the following:
   

   Import-Module -Name PnP.PowerShell

    

4. Run the following script ONCE per tenant to create an Azure App Registration for PnP:
   Note: Replace tenant with your tenant name and the AzureEnvironment with the associated sovereign cloud.
   

   Register-PnPAzureADApp -ApplicationName "PnP PowerShell" `
     -Tenant [TENANT].onmicrosoft.com -Interactive `
     -AzureEnvironment [USGovernment|USGovernmentHigh|USGovernmentDoD|Germany|China] `
     -SharePointDelegatePermissions AllSites.FullControl `
     -SharePointApplicationPermissions Sites.FullControl.All `
     -GraphApplicationPermissions Group.ReadWrite.All `
     -GraphDelegatePermissions Group.ReadWrite.All​

   Login with user credentials assigned Global Administrator role.
   
   
5. Make a note of the GUID returned from step 4. This is the App/Client ID of the new PnP Azure App Registration.
   
   
6. If you see the following consent dialog, review the requested permissions and click Accept. If you'd prefer different permissions, change the requested Graph and SharePoint permissions in step #4.
   
   
7. Connect to the Communication site collection:
   Note: Replace tenant with your tenant name and the AzureEnvironment with the associated sovereign cloud. Replace the ClientId with the GUID returned in step #4. The URL is to the site collection you want to apply a template.
   

   Connect-PnPOnline -Url https://[TENANT].sharepoint.[com|us|mil|de|cn]/sites/[SITE COLLECTION] `
     -Interactive -AzureEnvironment [USGovernment|USGovernmentHigh|USGovernmentDoD|Germany|China] `
     -ClientId [ClientID] -Tenant 
   "[TENANT].onmicrosoft.com"​

   Login with user credentials assigned Global Administrator role (some templates make tenant-level changes).
   
   
8. Apply one of the templates to your site collection with the following: 
   

   Invoke-PnPSiteTemplate -Path  <path to file>\<template>.pnp

9. The previous command will use the PNP file (contains XML) to instruct the PnP template API to configure the previously created site collection.

Your site collection should now be fully provisioned with the elements of the template you have chosen.  It will be necessary to repeat these steps for any additional Look Book sites you wish to provision for your organization.  Let us know what you think in the comments below.