Troubleshooting Office Cloud Policy Service (OCPS)

The Office cloud policy service (OCPS) is a cloud-based service that enables you to apply policy settings for Office 365 ProPlus on a user’s device.  The policy settings roam to whichever device the user signs into and uses Office 365 ProPlus.  As end users become increasingly mobile, IT Pros need a single approach to secure Office 365 ProPlus for traditional on-premises domain devices, Azure AD registered devices, Azure AD Joined, and Hybrid Azure AD joined devices.  OCPS applies to all scenarios above without the need to download and replicate any content such as Administrative Template files (ADMX/ADML) on-premises.  The goal of this blog is to provide some transparency of how the service works to help IT Pros during their validation phase and to encourage transition from classic domain-based policy to OCPS service for Office 365 ProPlus.

Requirements of OCPS

1. At least Version 1808 (August 2018) of Office 365 ProPlus
2. User accounts created in or synchronized to Azure Active Directory (AAD). The user must be signed into Office 365 ProPlus with an AAD based account.
3. Security groups created in or synchronized to Azure Active Directory (AAD), with the appropriate users added to those groups.
4. To create a policy configuration, you must be assigned one of the following roles in Azure Active Directory (AAD): Global Administrator, Security Administrator, or Office Apps Admin.
5. Connectivity to addresses below. Microsoft recommends proxy bypass\whitelist for these URLs
*.manage.microsoft.com, *.officeconfig.msocdn.com, config.office.com over 443

Steps to perform proof of concept and validation
1. Create a test user, ours will be “Kasper Graf”, [email protected].
2. Create security group “OCPS Service Validation” and add user to group within Active Directory Users and Computers.
3. Allow AAD Connect to synchronize user and group to Azure AD. (lunch break :) or force synchronization via commands below)

(optional) From AAD Connect Server and elevated PowerShell, run the following commands:
PS C:\WINDOWS\system32>import-module adsync
PS C:\WINDOWS\system32>Set-ADSyncScheduler -NextSyncCyclePolicyType Delta
PS C:\WINDOWS\system32>Start-ADSyncSyncCycle

Browse Azure AD portal and explore Users – All Users, select Kasper Graf and then Groups. Verify that group “OCPS Service Validation” has been assigned and source says, “Windows Server AD”. This confirms user and group were synced into Azure AD successfully and we can proceed to next steps.
4.  Create your first OCPS policy and select “Create” button:

5. Complete input fields, when selecting assigned security group input “OCPS” and service should filter results to “OCPS Service Validation” group.  Next, define a policy.  For the demo, I chose policy "VBA Macro Notification Settings", "Enabled" where VBA Macro Notification Settings are set to "Disable all with notification".   Once selections have been made “Create” or “Save”.

6. From Policy Management, we can now see our policy exists.

So, we’ve got a policy, we’ve assigned it to a security group containing our test user, our next step is to validate. My test machine happens to be classic on-premises domain joined machine. My user, Kasper Graf, is signed in with his normal Active Directory credentials which is displayed in upper right hand corner of Word.

Traditional Group Policy uses Client-Side Extensions in Windows to apply policy every 90 minutes.  IT Pros can force policy by using command line “gpupdate /force” and inspect\verify registry as well as application behavior prior to broad deployment.  OCPS checks for policy upon initial Office application launch, calls into cloud service endpoints listed above, determines policy applicability based on group membership and priority assignment and registry keys are populated. 

Specifically, there are two locations of interest in registry.

1. HKEY_CURRENT_USER\Software\Microsoft\Office\16.0\Common\CloudPolicy\
This will contain information about FetchInterval, 90 minutes is default, as well as record of Last Fetch Time and Last Payload Hash.

2. HKEY_CURRENT_USER\Software\Policies\Microsoft\Cloud. This key will contain path to registry keys representing the policy assignment. For example, ours will be HKEY_CURRENT_USER\Software\Policies\Microsoft\Cloud\Office\16.0\word\security
Vbawarnings = 2 (DWORD)

IT Pros can achieve the same behavior of gpupdate by simply deleting the key HKEY_CURRENT_USER\Software\Microsoft\Office\16.0\Common\CloudPolicy, close Office application and relaunch to fetch policy.  I typically use tools like Process Monitor to help trust\verify operations of this type with filters such as “Path” contains “CloudPolicy” or where Operation is “RegSetValue” etc.  Opening a Word document containing a Macro displaying warning with notification as expected.

Advanced troublshooting

The OCPS client on Win32 is built into the C2R service. The C2R service runs as SYSTEM on the device and is not aware of the active user(s). When you launch one of the Win32 Office apps (like Word) the user token is passed to C2R by the app and then C2R is able to call the OCPS service with the user token and request the policies. This makes it difficult to troubleshoot as the traffic to the service is managed via this SYSTEM process.
Below is the set of steps needed to monitor the HTTPS traffic running under the SYSTEM account on the Win32 device.

Setup
Tools you need
- Fiddler (or some tool to monitor the HTTPS traffic and decrypt the HTTPS traffic)
By monitoring and decrypting the HTTPS traffic you will be able to see the content that is sent and received via the OCPS check in service.
In Fiddler there is a configuration option that allows Fiddler to decrypt HTTPS traffic by installing a trusted certificate on the target machine. Without this you cannot decrypt the content.

- The ability to run Fiddler as SYSTEM on the Win32 device
runassystem.exe is a small tool available from a third party, https://apreltech.com/.
This tool allows you to specify an EXE to launch in a new process that is run under SYSTEM.
There are other tools and methods available to accomplish this.
https://sourceforge.net/projects/runassystem/ 
https://www.winhelponline.com/blog/run-program-as-system-localsystem-account-windows/ 

Steps to troubleshoot
1. Shut down all Office apps
2. Delete the OCPS registry hives
3. Launch runassystem.exe and accept the elevation prompt.
4. Provide runassystem.exe the path and EXE of Fiddler
5. Launch Word and monitor the traffic

What you should see
You should see a call to ocps.manage.microsoft.com to retrieve the policies for the user and a call to ocps.manage.microsoft.com to send the acknowledgement that the policies were received and the health status.

Call to retrieve
The retrieval of policies includes a JSON payload that contains the policies and their values. Select the item in Fiddler and review the payload using the JSON tab.

Each configured policy is detailed in the JSON response showing the policy ID (ParentSettingId), the data type (Type) and the value name and value.

ParentSettingId
If the policy is an ADMX based policy you will see this as [admxfile][admx id]. Ex. office16;L_UseOfficeForLabeling. You can look up L_UseOfficeForLabeling in the office16.admx file.
If the policy is not an ADMX based policy you will see this as [app][policy id] as defined by the app team. Ex. cortana;C_AllowBingAnswersInCortana. There is no reference for these policies as they are only defined in the OCPS policy library.

Call to acknowledge

The call to the /ack API is passed details on the payload that was received by the client and the success status for writing to the client.

The JSON data will contain the device name, platform and Office version as well as Success or Failure and additional failure information if needed.

FAQ:
How does conflict resolution work if the same policy is set via traditional domain-based policy as well as OCPS?
OCPS takes priority if there are any conflicts with traditional domain-based policies.

Computer accounts within my organization don't have direct internet access and sit behind a proxy.  With this configuration I've noticed OCPS doesn't work even though the User does have access to all required Office 365 URLs?

We have added proxy and User Impersonation support to address this issue.  The tentative release date is 2020 September SAC-T and 2021 January SAC.

Currently policies are limited to user settings. Are there plans on adding machine settings?
Yes. This has been accepted and currently is in our backlog. We hope to have this available next year.

Group Policy provides a view of all policies on the device or for the specified user. Does OCPS support this?
Currently OCPS does not provide a list of all Office policies applied to a specific user or device. This is on our backlog and we hope to have this available next year.

Will OCPS support other platforms such as MacOS, Android and iOS?
Yes, OCPS in the future will also support additional platforms such as MacOS, Android and iOS. We will create additional blog postings per platform once features are generally available.

Are there any environments where OCPS is not available?

The Office cloud policy service isn't available to customers who have the following plans: Office 365 operated by 21Vianet, Office 365 Germany, Office 365 GCC, or Office 365 GCC High and DoD.

Change log

8/19/2020 Updated to include more prescriptive guidance for troubleshooting

This blog post is brought to you by Dave Guenthner, a Senior Premier Field Engineer and “ProPlus Ranger” at Microsoft. Feel free to share your questions and feedback in the comments below.