Using SharePoint Look Book in your GCC High Tenant

Contributors:

Rob Garrett - Sr. Customer Engineer, Microsoft Federal 

John Unterseher - Sr. Customer Engineer, Microsoft Federal

Martin Ballard - Sr. Customer Engineer, Microsoft Federal 

 

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=sharepoint-ps 

 

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 site collections in GCC High tenants. Instead, we can create Communication 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 Site, he/she may leverage the SharePoint PnP PowerShell Module to apply a template. The following details the steps: 

 

1. Download the desired templates from the following location: 
https://github.com/SharePoint/sp-dev-provisioning-templates/tree/master/tenant  

 

2. Open a new Windows PowerShell window (native PowerShell, not PowerShell Core 7.x or above) – as an administrator. 

 

3. Install the SharePoint PnP module with the following (requires an Internet connection):

Install-Module SharePointPnPPowerShellOnline 
 

4. If the module is already installed, you should update it to the latest version with: 

Update-Module SharePointPnPPowerShellOnline 
 

5. Ensure the module is loaded with the following: 

Import-Module SharePointPnPPowerShellOnline 
 

6. Choose existing Communication site or create a new one. 

 

7. Connect to the Communication site collection: 

Connect-PnPOnline -Url https://<TENANT NAME>.sharepoint.us/sites/<SITE COLLECTION>  -UseWebLogin

 

8. In the above statement, replace the URL to the Communication site collection in your tenant. 

 

9. The switch at the end instructs PnP to use an interactive web session to authenticate with SharePoint Online. This method requires Global Administrator to enter their username/password and pass any MFA requirements. 

 

10. Connection to SPO, via PnP, in a batch process is possible by registering an Azure AD application and using client assertion (certificate) credentials. However, this is outside the scope of this post. 

 

11. Apply one of the templates to your site collection with the following: 

Apply-PnPProvisioningTemplate -Path <path to file>\<template>.pnp

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