Skip to content

Commit efaea8b

Browse files
jgeron-suhsdjgeron-suhsd
committed
feat(docs): add Chrome Policy API implementation guide
feat(docs): add Chrome Policy functions for organizational units and groups feat(docs): implement Get-GSPolicySchema function feat(docs): implement Resolve-GSPolicy function feat(docs): implement Set-GSPolicyOrgUnit function feat(docs): implement Set-GSPolicyGroup function feat(docs): implement Remove-GSPolicyGroup function feat(docs): implement Set-GSPolicyOrgUnitInherit function
1 parent eef3c71 commit efaea8b

File tree

8 files changed

+1074
-0
lines changed

8 files changed

+1074
-0
lines changed

‎Chrome-Policy-Implementation-Guide.md‎

Lines changed: 234 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,234 @@
1+
# Adding Chrome Policy Functions to PSGSuite
2+
3+
This document explains how to implement Chrome Policy API functions in PSGSuite and serves as a guide for adding new Google API services to the module.
4+
5+
## Overview
6+
7+
PSGSuite is a PowerShell module that wraps Google's .NET SDKs, enabling administrators to manage Google Workspace (formerly G Suite) services through PowerShell. The module uses Google's official .NET client libraries (NuGet packages) and provides PowerShell functions that follow consistent patterns.
8+
9+
## Architecture Understanding
10+
11+
### Core Components
12+
13+
1. **Google .NET SDKs**: PSGSuite loads Google API client libraries as .NET assemblies (DLLs)
14+
2. **New-GoogleService**: Creates authenticated service objects for API calls
15+
3. **Function Structure**: Consistent PowerShell function patterns across all APIs
16+
4. **Configuration**: Centralized authentication and customer configuration
17+
18+
### How PSGSuite Integrates with .NET APIs
19+
20+
1. **Assembly Loading**: The `Import-GoogleSDK` private function loads Google API DLLs from the `lib` directory
21+
2. **Service Creation**: `New-GoogleService` creates authenticated service objects with proper scopes
22+
3. **API Calls**: Functions use the service objects to make API requests following Google's .NET SDK patterns
23+
24+
## Adding Chrome Policy API Support
25+
26+
### Step 1: Research the API
27+
28+
**Chrome Policy API Details:**
29+
- **Service Endpoint**: `https://chromepolicy.googleapis.com`
30+
- **NuGet Package**: `Google.Apis.ChromePolicy.v1` (current: v1.69.0.3776)
31+
- **Service Type**: `Google.Apis.ChromePolicy.v1.ChromePolicyService`
32+
- **Scopes**:
33+
- `https://www.googleapis.com/auth/chrome.management.policy` (read/write)
34+
- `https://www.googleapis.com/auth/chrome.management.policy.readonly` (read-only)
35+
36+
### Step 2: Update Dependencies
37+
38+
Add the Chrome Policy SDK to the NuGet dependencies:
39+
40+
```json
41+
{
42+
"Name": "Google.Apis.ChromePolicy.v1.dll",
43+
"BaseName": "Google.Apis.ChromePolicy.v1",
44+
"Target": "Latest",
45+
"LatestVersion": "1.69.0.3776"
46+
}
47+
```
48+
49+
### Step 3: Create Directory Structure
50+
51+
Create the function directory following PSGSuite patterns:
52+
```
53+
PSGSuite/Public/Chrome Policy/
54+
```
55+
56+
### Step 4: Implement Functions
57+
58+
#### Function Naming Convention
59+
- Use PSGSuite prefix: `Get-GS`, `Set-GS`, `New-GS`, `Remove-GS`
60+
- Use descriptive names: `Get-GSPolicySchema`, `Resolve-GSPolicy`
61+
62+
#### Standard Function Structure
63+
64+
```powershell
65+
function Get-GSExample {
66+
<#
67+
.SYNOPSIS
68+
Brief description
69+
70+
.DESCRIPTION
71+
Detailed description
72+
73+
.PARAMETER ParamName
74+
Parameter description
75+
76+
.EXAMPLE
77+
Example usage
78+
#>
79+
[OutputType('Google.Apis.ChromePolicy.v1.Data.ResponseType')]
80+
[CmdletBinding(DefaultParameterSetName = "List")]
81+
Param(
82+
# Parameters
83+
)
84+
Begin {
85+
# Service creation
86+
$serviceParams = @{
87+
Scope = 'https://www.googleapis.com/auth/chrome.management.policy.readonly'
88+
ServiceType = 'Google.Apis.ChromePolicy.v1.ChromePolicyService'
89+
}
90+
$service = New-GoogleService @serviceParams
91+
92+
# Customer ID handling
93+
$customerId = if ($Script:PSGSuite.CustomerID) {
94+
$Script:PSGSuite.CustomerID
95+
}
96+
else {
97+
"my_customer"
98+
}
99+
}
100+
Process {
101+
# API logic with error handling
102+
try {
103+
# API calls
104+
}
105+
catch {
106+
if ($ErrorActionPreference -eq 'Stop') {
107+
$PSCmdlet.ThrowTerminatingError($_)
108+
}
109+
else {
110+
Write-Error $_
111+
}
112+
}
113+
}
114+
}
115+
```
116+
117+
#### Key Patterns
118+
119+
1. **Authentication**: Always use `New-GoogleService` with appropriate scopes
120+
2. **Customer ID**: Use `$Script:PSGSuite.CustomerID` or "my_customer"
121+
3. **Error Handling**: Consistent try/catch with ErrorActionPreference handling
122+
4. **Pagination**: Implement pagination for list operations
123+
5. **Verbose Output**: Use `Write-Verbose` for operation feedback
124+
6. **Output Types**: Specify `[OutputType()]` with Google API data types
125+
126+
### Step 5: Implemented Chrome Policy Functions
127+
128+
The following functions were created following PSGSuite patterns:
129+
130+
1. **`Get-GSPolicySchema`**: Lists or gets specific policy schemas
131+
- Supports filtering by namespace
132+
- Implements pagination
133+
- Two parameter sets: List and Get
134+
135+
2. **`Resolve-GSPolicy`**: Gets resolved policy values for org units or groups
136+
- Supports both organizational units and groups
137+
- Implements pagination for large result sets
138+
139+
3. **`Set-GSPolicyOrgUnit`**: Modifies policies for organizational units
140+
- Supports single policy or batch modifications
141+
- Handles JSON serialization for policy values
142+
143+
4. **`Set-GSPolicyGroup`**: Modifies policies for groups
144+
- Same pattern as org unit function
145+
- Supports batch operations
146+
147+
5. **`Set-GSPolicyOrgUnitInherit`**: Sets policies to inherit from parent
148+
- Supports single or multiple schema inheritance
149+
150+
6. **`Remove-GSPolicyGroup`**: Deletes policies from groups
151+
- Supports single or multiple policy deletion
152+
153+
### Step 6: Authentication and Scopes
154+
155+
Chrome Policy API requires specific OAuth scopes:
156+
- **Read-only**: `https://www.googleapis.com/auth/chrome.management.policy.readonly`
157+
- **Read-write**: `https://www.googleapis.com/auth/chrome.management.policy`
158+
159+
Ensure your Google Cloud project has:
160+
1. Chrome Policy API enabled
161+
2. Appropriate OAuth consent screen configuration
162+
3. Service account or OAuth credentials configured
163+
164+
### Step 7: Testing and Usage
165+
166+
Basic usage examples:
167+
168+
```powershell
169+
# List all policy schemas
170+
Get-GSPolicySchema
171+
172+
# Get schemas for user apps
173+
Get-GSPolicySchema -Filter "chrome.users.apps"
174+
175+
# Get resolved policies for an org unit
176+
Resolve-GSPolicy -PolicySchemaFilter "chrome.users.URLAllowlist" -OrgUnitId "03ph8a2z1qtgfqh"
177+
178+
# Set a policy for an org unit
179+
$policyValue = @{
180+
"value" = @{
181+
"allowedUrls" = @("https://example.com")
182+
}
183+
}
184+
Set-GSPolicyOrgUnit -OrgUnitId "03ph8a2z1qtgfqh" -PolicySchema "chrome.users.URLAllowlist" -PolicyValue $policyValue
185+
```
186+
187+
## General Guidelines for Adding New APIs
188+
189+
### Research Phase
190+
1. Check Google's API documentation
191+
2. Verify .NET SDK availability on NuGet
192+
3. Identify required scopes and authentication methods
193+
4. Understand API endpoints and data structures
194+
195+
### Implementation Phase
196+
1. Add NuGet package to dependencies
197+
2. Create appropriate directory structure
198+
3. Implement functions following PSGSuite patterns
199+
4. Use consistent naming conventions
200+
5. Implement proper error handling and pagination
201+
202+
### Best Practices
203+
1. **Consistency**: Follow existing PSGSuite patterns
204+
2. **Documentation**: Include comprehensive help text
205+
3. **Error Handling**: Use consistent error handling patterns
206+
4. **Scoping**: Use minimal required permissions
207+
5. **Testing**: Test with real API calls when possible
208+
209+
### Common Patterns
210+
- Use `$Script:PSGSuite.CustomerID` for customer identification
211+
- Implement pagination for list operations
212+
- Use `ConvertTo-Json` for complex object serialization
213+
- Support both single and batch operations where applicable
214+
- Use parameter sets to handle different operation modes
215+
216+
## Troubleshooting
217+
218+
### Common Issues
219+
1. **Assembly Loading**: Ensure DLL is in the lib directory and loaded properly
220+
2. **Authentication**: Verify scopes and credentials are properly configured
221+
3. **API Limits**: Implement proper pagination and rate limiting
222+
4. **Data Types**: Use correct Google API data types for parameters and returns
223+
224+
### Debug Steps
225+
1. Check verbose output with `-Verbose`
226+
2. Verify service object creation
227+
3. Test API calls with minimal parameters
228+
4. Check Google Cloud Console for API quotas and errors
229+
230+
## Conclusion
231+
232+
Adding Chrome Policy functions to PSGSuite follows the established patterns used throughout the module. The key is understanding how PSGSuite wraps Google's .NET SDKs and following consistent patterns for authentication, error handling, and API interaction.
233+
234+
This approach can be applied to any Google API that has a corresponding .NET SDK package available on NuGet.

‎PSGSuite/Public/ChromePolicy/Get-GSPolicySchema.ps1‎

Lines changed: 154 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,154 @@
1+
function Get-GSPolicySchema {
2+
<#
3+
.SYNOPSIS
4+
Gets Chrome policy schemas from the Chrome Policy API
5+
6+
.DESCRIPTION
7+
Gets Chrome policy schemas that can be applied to Chrome OS devices and Chrome browsers in your organization.
8+
9+
.PARAMETER SchemaName
10+
The specific schema name to retrieve. Can be either a full path (e.g., "customers/{customer}/policySchemas/chrome.users.AutoOpenFileTypes")
11+
or just the schema name (e.g., "chrome.users.AutoOpenFileTypes"). If not provided, lists all policy schemas.
12+
13+
.PARAMETER Filter
14+
Search filter to apply to the policy schemas. Supports filtering by namespace (e.g., "chrome.users.apps").
15+
16+
.PARAMETER PageSize
17+
Maximum number of policy schemas to return in a single request. Default is 100.
18+
19+
.PARAMETER Limit
20+
Maximum number of policy schemas to return. Set to 0 to return all results.
21+
22+
.EXAMPLE
23+
Get-GSPolicySchema
24+
25+
Gets all Chrome policy schemas for the organization
26+
27+
.EXAMPLE
28+
Get-GSPolicySchema -Filter "chrome.users.apps"
29+
30+
Gets policy schemas related to user applications
31+
32+
.EXAMPLE
33+
Get-GSPolicySchema -SchemaName "chrome.users.AutoOpenFileTypes"
34+
35+
Gets a specific policy schema by name
36+
37+
.EXAMPLE
38+
Get-GSPolicySchema -SchemaName "customers/{customer}/policySchemas/chrome.users.AutoOpenFileTypes"
39+
40+
Gets a specific policy schema using the full path
41+
#>
42+
[OutputType('Google.Apis.ChromePolicy.v1.Data.GoogleChromePolicyV1PolicySchema')]
43+
[CmdletBinding(DefaultParameterSetName = "List")]
44+
Param(
45+
[Parameter(Mandatory = $false, Position = 0, ValueFromPipeline = $true, ValueFromPipelineByPropertyName = $true, ParameterSetName = "Get")]
46+
[Alias('Name', 'Policy', 'PolicySchema')]
47+
[String[]]
48+
$SchemaName,
49+
[Parameter(Mandatory = $false, ParameterSetName = "List")]
50+
[String]
51+
$Filter,
52+
[Parameter(Mandatory = $false, ParameterSetName = "List")]
53+
[ValidateRange(1, 1000)]
54+
[Alias('MaxResults')]
55+
[Int]
56+
$PageSize = 100,
57+
[Parameter(Mandatory = $false, ParameterSetName = "List")]
58+
[Alias('First')]
59+
[Int]
60+
$Limit = 0
61+
)
62+
Begin {
63+
$serviceParams = @{
64+
Scope = 'https://www.googleapis.com/auth/chrome.management.policy.readonly'
65+
ServiceType = 'Google.Apis.ChromePolicy.v1.ChromePolicyService'
66+
}
67+
$service = New-GoogleService @serviceParams
68+
$customerId = if ($Script:PSGSuite.CustomerID) {
69+
$Script:PSGSuite.CustomerID
70+
}
71+
else {
72+
"my_customer"
73+
}
74+
$parentPath = "customers/$customerId"
75+
}
76+
Process {
77+
try {
78+
switch ($PSCmdlet.ParameterSetName) {
79+
Get {
80+
foreach ($schema in $SchemaName) {
81+
try {
82+
Write-Verbose "Getting Chrome Policy Schema '$schema'"
83+
# Handle both full paths and schema names
84+
$schemaPath = if ($schema.StartsWith('customers/')) {
85+
$schema
86+
} else {
87+
"$parentPath/policySchemas/$schema"
88+
}
89+
$request = $service.Customers.PolicySchemas.Get($schemaPath)
90+
$request.Execute()
91+
}
92+
catch {
93+
if ($ErrorActionPreference -eq 'Stop') {
94+
$PSCmdlet.ThrowTerminatingError($_)
95+
}
96+
else {
97+
Write-Error $_
98+
}
99+
}
100+
}
101+
}
102+
List {
103+
$request = $service.Customers.PolicySchemas.List($parentPath)
104+
if ($Limit -gt 0 -and $PageSize -gt $Limit) {
105+
Write-Verbose ("Reducing PageSize from {0} to {1} to meet limit with first page" -f $PageSize, $Limit)
106+
$PageSize = $Limit
107+
}
108+
$request.PageSize = $PageSize
109+
110+
if ($PSBoundParameters.ContainsKey('Filter')) {
111+
Write-Verbose "Getting Chrome Policy Schemas with filter '$Filter'"
112+
$request.Filter = $Filter
113+
}
114+
else {
115+
Write-Verbose "Getting all Chrome Policy Schemas"
116+
}
117+
118+
[int]$i = 1
119+
$overLimit = $false
120+
do {
121+
$result = $request.Execute()
122+
if ($result.PolicySchemas) {
123+
$result.PolicySchemas
124+
}
125+
if ($result.NextPageToken) {
126+
$request.PageToken = $result.NextPageToken
127+
}
128+
[int]$retrieved = ($i + $result.PolicySchemas.Count) - 1
129+
Write-Verbose "Retrieved $retrieved Chrome Policy Schemas..."
130+
if ($Limit -gt 0 -and $retrieved -eq $Limit) {
131+
Write-Verbose "Limit reached: $Limit"
132+
$overLimit = $true
133+
}
134+
elseif ($Limit -gt 0 -and ($retrieved + $PageSize) -gt $Limit) {
135+
$newPS = $Limit - $retrieved
136+
Write-Verbose ("Reducing PageSize from {0} to {1} to meet limit with next page" -f $PageSize, $newPS)
137+
$request.PageSize = $newPS
138+
}
139+
[int]$i = $i + $result.PolicySchemas.Count
140+
}
141+
until ($overLimit -or !$result.NextPageToken)
142+
}
143+
}
144+
}
145+
catch {
146+
if ($ErrorActionPreference -eq 'Stop') {
147+
$PSCmdlet.ThrowTerminatingError($_)
148+
}
149+
else {
150+
Write-Error $_
151+
}
152+
}
153+
}
154+
}

0 commit comments

Comments
 (0)