Device Trust Gateway & Approval Portal

The Device Trust Gateway is a secure bridge application designed for organizations (specifically Google Workspace and Cloud Identity customers) to enforce strict "Approved Devices Only" access policies via Context-Aware Access (CAA), while providing a seamless, low-friction self-service workflow for end-users to vet and approve their personal BYOD devices.

📋 Table of Contents

📘 Master Enterprise Deployment Guide
Architecture & Zero-Trust Overview
Google Workspace Settings & Extension Guide
Prerequisites & Billing Check
⚡ Automated Interactive Deployer (Recommended)
🔒 Endpoint Verification & BYOD Approval Lifecycle
Chromebook Fleet Seeding Tool
Manual Setup: Local Development
Manual Setup: Docker (On-Premise)
Manual Setup: Google Cloud (GCP Cloud Run)
Configuration & Admin UI
Firewall, Network Allowlist & Anti-Spoofing
🔒 Identity-Aware Proxy (IAP) Edge Gating
🛠️ Troubleshooting & AI Diagnostics with Gemini

🏛 Architecture & Zero-Trust Overview

The Gateway leverages Google Workspace Context-Aware Access (CAA) to establish a zero-trust access perimeter.

For complete documentation detailing supported Workspace editions, end-user flows, Console settings, force-installing extensions, CAA rules, and deployment options: 👉 docs/master_enterprise_deployment_guide.md — Master Enterprise Guide: Comprehensive blueprint covering portal concepts, Workspace licensing, end-user flows, complete Admin Console checklist, and deployment walkthroughs. 👉 docs/workspace_setup_and_extension_guide.md — Step-by-step Google Workspace Console settings, Extension Force-Install ID, Mobile vs. Desktop approval behavior, and Mass Baseline Revocation. 👉 docs/troubleshooting_guide.md — Troubleshooting & AI Diagnostics Guide: Real-world root-cause playbooks (chrome://policy diagnostics, Windows Git Bash path handling, DWD/Cloud Identity debugging) and copy-paste prompts for troubleshooting with Gemini. 👉 docs/caa_architecture_overview.md — Enterprise zero-trust architecture whitepaper.

Key Architectural Principles:

Dual Enforcement Modes — Disabled by Default on New Installs: Supports Session Management & Circuit Breaker for Google Workspace for Education Fundamentals (session_watch_enabled), Context-Aware Access (CAA) Integration for Education Standard/Plus (caa_enforcement_enabled), or BOTH simultaneously. On any new installation (./deploy.sh), both modes start disabled by default (enforcement_mode: "DISABLED") in safe standby mode until an administrator explicitly configures and enables them in #/admin.
Sub-10-Second Unapproved Device Termination (3-Layer Pipeline):
1. Layer 1 (< 0.5s Inline Portal Check & 8s Heartbeat): Opening the portal on an unapproved or BLOCKED device immediately triggers users.signOut + OAuth grant revocation and returns 401 SESSION_REVOKED_UNAPPROVED_DEVICE. Backend JWT authentication compares the token's iat claim against the user's last sign-out timestamp to immediately reject pre-revocation tokens.
2. Layer 2 (~2–10s Cloud Identity lastSyncTime Sub-Polling): A 1-minute Cloud Scheduler job (session-watch-login-sweep) executes 5 rapid sub-polls spaced 10 seconds apart (t=0s, 10s, 20s, 30s, 40s), inspecting Cloud Identity deviceUsers for both PENDING_APPROVAL and re-logged-in BLOCKED BYOD devices whose lastSyncTime updated after the user's last sign-out.
3. Layer 3 (Admin SDK login Audit Sweep + OAuth Token Revocation): Sweeps admin.reports_v1.activities.list(applicationName='login') and revokes both Google session cookies (users.signOut) and OAuth token grants (directory.tokens.delete).
Unified User & Admin Experience: All users—including Super Administrators—see the exact same clean device approval view on #/, with Company-Owned Devices strictly filtered to hardware the signed-in user has personally accessed (recentUsers). Admin-only operational controls (Sync Inventory Cache, Attest Current Session, Run Live Login Sweep) and enforcement telemetry reside exclusively on #/admin.
Unmanaged BYOD Hardware: Personal devices do not require intrusive Mobile Device Management (MDM) enrollment or profiles. Users sign into their managed Chrome profile with the Endpoint Verification extension, registering the device as "Unmanaged" while allowing the backend to approve (devices.deviceUsers.approve) or block (devices.deviceUsers.block) access.
Automated Lifecycle Management: A secure cron endpoint (/api/cron/cleanup) automatically revokes access for inactive BYOD devices older than X days and syncs newly enrolled Chromebooks.

🛠 Prerequisites & Billing Check

Google Cloud Project with an Active Billing Account linked. (Google Cloud Run, Cloud Build, Cloud Scheduler, and Secret Manager require billing to be enabled before APIs can be activated).
Google Workspace / Cloud Identity tenant (supports Education Fundamentals, Education Standard / Plus, and Enterprise editions).
Google Endpoint Verification Chrome Extension force-installed across target Organizational Units (OUs) to collect device signals and answer Context-Aware Access challenges (Extension ID: callobklhcbilhphinckomhgkigmfocg).
Service Account Credentials with Domain-Wide Delegation (DWD) authorized in Google Workspace Admin Console (https://admin.google.com/ac/owl/domainwidedelegation) for the following 6 required OAuth scopes:
- https://www.googleapis.com/auth/cloud-identity.devices
- https://www.googleapis.com/auth/admin.directory.user.readonly
- https://www.googleapis.com/auth/admin.directory.group.member.readonly
- https://www.googleapis.com/auth/admin.directory.device.chromeos.readonly
- https://www.googleapis.com/auth/admin.reports.audit.readonly (Required for Session Management login audit sweeps)
- https://www.googleapis.com/auth/admin.directory.user.security (Required for users.signOut & OAuth token revocation circuit breaker)
Node.js (v20+) and Python (3.11+) installed for local development. (Note: Node.js is only required if building the React frontend locally outside of Docker. The automated ./deploy.sh script and Docker builds manage Node.js 20 and Python 3.11 automatically inside container build stages).

Important

Pre-Deployment Billing Verification & Diagnostic Reporting: The automated ./deploy.sh script actively inspects your GCP project's billing status before creating cloud resources.

Actionable CLI Diagnostics: If billing verification encounters an issue, the CLI prints the exact underlying gcloud error message (such as missing roles/billing.viewer IAM permissions or disabled cloudbilling.googleapis.com API) alongside direct resolution links.
Verbose Mode (--verbose / -v): Run ./deploy.sh --verbose to stream live Cloud Build logs, Cloud Run deploy events, and comprehensive command debug traces.
Bypass Option (--skip-billing-check): If billing is managed centrally by an organization administrator and your deployment account lacks roles/billing.viewer, pass --skip-billing-check or confirm the on-screen prompt to proceed.

💰 Estimated Monthly GCP Running Cost (1,000 to 40,000 Students)

Because devicetrustportal evaluates domain login and Cloud Identity sync events in batched sweeps rather than per-student background processes, a 1,000-student district and a 40,000-student district have nearly identical GCP running costs. All Google Workspace Admin SDK and Cloud Identity API calls are 100% free (included with Google Workspace for Education):

Deployment & Enforcement Mode	Detection Speed	Est. Monthly Cost (1,000 – 40,000 Students)	Why
1. On-Premise Docker (`./deploy.sh --target 2`)	~2 – 10s	$0.00 / mo	Runs on any existing district VM (~60 MB RAM).
2. Cloud Run — CAA-Only Mode (Education Standard / Plus, `session_watch_enabled: false`)	Immediate (Edge 403)	$0.00 – $0.20 / mo	Scales to zero when idle; `< 3%` of GCP's 180k vCPU-s monthly Free Tier.
3. Cloud Run — Free-Tier 1-Minute Session Sweep (Education Fundamentals, `--sweep-cadence 1min`)	~30 – 60s	$0.00 – $0.20 / mo	1 sweep/min (~110k vCPU-s/mo) fits 100% inside GCP's 180k vCPU-s Free Tier.
4. Cloud Run — 24/7 Sub-10s Rapid Polling (Education Fundamentals / `BOTH`, default `--sweep-cadence sub10s`)	~2 – 10s	~$38.00 – $43.00 / mo	5× 10s sub-polls/min (~43s/min active window ≈ 1.88M vCPU-s/mo at `1 vCPU, 512 MiB`).

(See ARCHITECTURE_AND_SCALE.md for the full GCP service-by-service line-item breakdown).

🐣 Beginner-Friendly Quickstart: Download & Deployment Guide

This section is designed for administrators or users with zero development experience. Follow these 4 simple steps to download the code and deploy the gateway in under 10 minutes!

Step 1: Install Required Tools

You only need two free tools installed on your computer to run the automated installer:

Git (Tool to download the repository and provide the bash terminal):
- Windows: Download and run the 64-bit installer from git-scm.com/download/win. Keep all default settings (this installs Git Bash and adds Windows Explorer integration).
- Mac: Open Terminal and type xcode-select --install (click Install when prompted).
- Linux (Ubuntu/Debian): Run sudo apt update && sudo apt install -y git.
Google Cloud SDK (gcloud CLI) (Tool to connect to your Google Cloud Project):
- Windows: Download and run the Windows installer from cloud.google.com/sdk/docs/install. Check the box to "Run gcloud init" and ensure gcloud is added to your environment PATH.
- macOS / Linux: Run curl https://sdk.cloud.google.com | bash in your terminal, or download the installer from cloud.google.com/sdk/docs/install.

Step 2: Open Terminal & Authenticate

Important

Windows Users: Always use Git Bash (or WSL) to run the deployment script. Do NOT use standard Windows Command Prompt (cmd.exe) or Windows PowerShell, as ./deploy.sh requires a Bash shell environment.

Open your Terminal:
- Windows: Press the Windows Key, type Git Bash, and press Enter (or right-click anywhere on your Desktop/Downloads folder and choose "Open Git Bash here").
- Mac: Open Terminal (Applications > Utilities > Terminal).
- Linux: Open your preferred shell terminal.
Log into Google Cloud:
```
gcloud auth login
```
(Your web browser will open automatically. Sign into the Google Workspace / Google Cloud account with administrator access to your target GCP Project).

Download (or Update) the Code Repository:

# Fresh install: Clone the code repository from GitHub
git clone https://github.com/googleworkspace/devicetrustportal.git
cd devicetrustportal

# Updating an existing checkout before redeploying:
git fetch origin && git reset --hard origin/main

Step 3: Run the Automated Deployment Wizard

Run the interactive deployment wizard script inside your terminal (Git Bash on Windows / Terminal on macOS & Linux):

# Optional for macOS / Linux: Ensure the script is executable
chmod +x deploy.sh

# Run the deployment wizard (Standard Interactive Mode)
./deploy.sh

Tip

Windows Git Bash (MINGW64) Notes:

./deploy.sh automatically checks if your local branch is behind origin/main and fast-forwards to the latest commit before deploying.
./deploy.sh automatically configures MSYS2_ARG_CONV_EXCL="--set-secrets;--set-env-vars;--update-env-vars;GOOGLE_APPLICATION_CREDENTIALS" so container paths like /secrets/dwd_key.json are not converted into Windows C:/Program Files/Git/secrets/dwd_key.json paths.
Do NOT set MSYS_NO_PATHCONV=1 or MSYS2_ARG_CONV_EXCL="*" globally when running manual gcloud commands in Git Bash on Windows, as gcloud relies on MSYS path conversion to locate its internal gcloud.py script. If running manual gcloud run services update commands on Windows Git Bash, use MSYS2_ARG_CONV_EXCL="--update-env-vars;--set-env-vars;--set-secrets".

Optional Deployment Flags & Command-Line Options:

You can pass command-line flags to customize execution or troubleshoot deployment:

# Run with verbose logging for real-time container build streaming and detailed diagnostics
./deploy.sh --verbose               # or -v

# Bypass GCP billing account verification (if billing is managed centrally by an org admin)
./deploy.sh --skip-billing-check

# Pre-specify Project ID, Region, and Deployment Target
./deploy.sh --project my-gcp-project-id --region us-central1 --target 1

# View all available CLI options
./deploy.sh --help

Flag	Env Variable	Description
`-v`, `--verbose`	`VERBOSE=true`	Streams real-time container build logs, Cloud Run deploy events, and debug command output.
`--skip-billing-check`	`SKIP_BILLING_CHECK=true`	Bypasses the GCP billing verification check if you lack `roles/billing.viewer`.
`--project <PROJECT_ID>`	`GCP_PROJECT=<PROJECT_ID>`	Sets the Google Cloud Project ID directly from the CLI.
`--region <REGION>`	`GCP_REGION=<REGION>`	Sets the target GCP region (default: `us-central1`).
`--target <1\|2>`	`DEPLOY_TARGET=<1\|2>`	Pre-selects deployment target (`1`: Google Cloud Run, `2`: On-Premise Docker).
`--mode <MODE>`	`ENFORCEMENT_MODE=<MODE>`	Sets initial enforcement mode (`DISABLED` [default for new installs], `SESSION_WATCH`, `CAA`, or `BOTH`).
`--sweep-cadence <sub10s\|1min>`	`SWEEP_CADENCE=<sub10s\|1min>`	Selects Session Watch polling cadence (`sub10s` [default, ~$38–$43/mo] or `1min` [$0/mo GCP Free Tier]).
`-h`, `--help`	—	Displays the help and options menu.

Step 4: Follow the On-Screen Prompts

The deployment wizard will guide you through the setup automatically. Here is what to enter when prompted:

Select Deployment Target:
- Type 1 for Google Cloud (GCP Cloud Run + Secret Manager) and press Enter.
Enter Google Cloud Project ID:
- Enter your GCP Project ID (e.g., my-company-device-trust) and press Enter.
- Press Enter to accept the default region (us-central1).
Domain-Wide Delegation (DWD) Authorization (Google Workspace Admin Console):
- The script creates a dedicated Service Account and displays a Numeric Client ID (e.g., 1083920194817263).
- Open your browser to admin.google.com > Security > Domain-wide Delegation.
- Click Add new, paste the Numeric Client ID, and copy-paste the scope string printed in your terminal into the OAuth Scopes field. Click Authorize.
- Return to your terminal, press ENTER, and enter your Workspace Administrator email address (e.g., admin@yourdomain.com).
OAuth Google Sign-In Authorization:
- The script builds Phase 1 and prints your live Cloud Run HTTPS URL (e.g., https://device-trust-gateway-xyz-uc.a.run.app).
- Open Google Cloud Credentials Console.
- Click Create Credentials > OAuth client ID > Web application.
- Under Authorized JavaScript origins and Authorized redirect URIs, paste your live Cloud Run URL.
- Click Create, copy your Client ID, and paste it into the terminal prompt.
Configure Workspace App Access Control (Crucial for Student Access):
- In Google Workspace, student or restricted organizational units (OUs) may block third-party / custom OAuth apps by default with an error like "Access blocked: Your institution's admin needs to review this app".
- Open Google Workspace Admin Console > Security > Access and data control > API controls > App access control.
- Click Manage Third-Party App Access (or Connected apps), then click Add app > OAuth app name or Client ID.
- Paste your OAuth 2.0 Client ID generated in Step 4 and search for it.
- Select your application, select your target OUs (e.g., /Students or your top-level domain), and set access to Trusted (allows access to Google services) or Limited. Click Save.
Access Control & IAP Edge Defense:
- Recommended for Schools & Hybrid Work (Default: N): Press N (or Enter) to skip IAP Edge Defense. The portal runs in Standard Mode over public HTTPS, secured by Google Sign-In and Trust Chaining (6-digit pairing codes). This ensures students and staff at home can approve personal devices to do homework using their school Chromebook.
- Strict Corporate Mode (Option Y): Places Cloud Run behind Google Cloud IAP and an HTTPS Load Balancer, restricting portal access to campus IP subnets or company hardware. Only use this if your organization strictly requires device approvals to happen on-premises.
Configure Google Workspace Device Telemetry, Profile Reporting & Endpoint Verification:

[!IMPORTANT] No CBCM Machine Enrollment Required for Personal BYOD Laptops: Personal Windows and macOS laptops do not require Chrome Browser Cloud Management (CBCM) machine-level token enrollment (CloudReportingEnabled is ignored on unenrolled BYOD computers). Instead, personal laptops register and report telemetry in PENDING_APPROVAL status via signed-in Managed Chrome Profile settings (Profile reporting + Chrome signals sharing) combined with Universal Device approvals.
- Part A: Enable ChromeOS Device Reporting (For Company-Owned Chromebooks):
  - Open admin.google.com > Devices > Chrome > Settings > Device settings.
  - Scroll to User and device reporting and turn ON:
    1. Report device OS information
    2. Report device hardware information
    3. Report device telemetry
    4. Report device user tracking
- Part B: Enable Managed Chrome Profile Reporting & Signals Sharing (Mandatory for Windows/Mac BYOD):
  - Open admin.google.com > Devices > Chrome > Settings > Users & browsers.
  - Select your target OU (or root domain) and configure the following five user/browser policies:
    1. Profile reporting (CloudProfileReportingEnabled) → Set to Enable profile reporting.
    2. Chrome signals sharing (UserSecuritySignalsReporting & UserSecurityAuthenticatedReporting) → Set to Enable signals sharing.
    3. Enterprise Hardware Platform API (EnterpriseHardwarePlatformAPIEnabled) → Set to Allow extensions to see hardware platform information.
    4. Browser sign-in → Set to Force users to sign in to use the browser.
    5. Managed accounts sign-in restriction (ManagedAccountsSigninRestriction) → Set to Block users from signing into secondary accounts (primary_account_strict).
  - (Note on chrome://policy Precedence Warnings: Do not worry if machine-scoped precedence policies like CloudPolicyOverridesPlatformPolicy or CloudUserPolicyOverridesCloudMachinePolicy show an "Ignored because the policy is not set at the machine scope" notice on unenrolled BYOD laptops. You can leave Policy Precedence at default; Cloud user profile policies apply automatically).
- Part C: Enable Device Signals Globally (Universal Data Access):
  - Open admin.google.com > Devices > Mobile & endpoints > Settings > Universal > Data access (labeled Universal or Universal settings in the left menu).
  - Expand Device signals (or Endpoint verification) and check both:
    1. Collect device signals from Chrome browser
    2. Collect device signals using endpoint verification (or Monitor which devices access organization data)
- Part D: Enable Device Approvals (Universal Security Settings):
  - Open admin.google.com > Devices > Mobile & endpoints > Settings > Universal > Security.
  - Expand Device approvals, select Require admin approval, and enter an admin notification email address.
  - Verify that all target sub-OUs (e.g. /Students, /Staff, /Admin) inherit or explicitly enable Require admin approval.
- Part E: Force-Install Endpoint Verification Extension (Managed Chrome Profiles):
  - Open admin.google.com > Devices > Chrome > Apps & extensions > Users & browsers.
  - In the left Organizational Unit tree, select your target OU (e.g. gwfe.org, /Students, or /Staff).
  - Click Add (+) > Add Chrome app or extension by ID, and enter Extension ID:
```
callobklhcbilhphinckomhgkigmfocg
```
  - In the right-hand options panel:
    - Under Installation policy, select Force install + pin to browser toolbar.
    - Under Certificate management, turn ON both Allow access to keys (KeyPermissions) and Allow enterprise challenge (AttestationExtensionAllowlist).
    - (Platform Note: In Chromium's policy engine, KeyPermissions and AttestationExtensionAllowlist are ChromeOS-only policies (supported_on: ["chrome_os"]) for Verified Access hardware TPM attestation. They will not appear in chrome://policy on Windows or macOS laptops—this is normal. Windows and macOS BYOD devices register via the Profile Reporting and Chrome Signals Sharing policies configured in Part B).
  - Click Save.
- Part F: Testing on Personal BYOD Laptops:
  - On a personal Windows or Mac laptop, open Chrome and sign into the Chrome profile using your managed Google Workspace account (user@yourdomain.com).
  - Verify the Endpoint Verification extension (callobklhcbilhphinckomhgkigmfocg) is installed and click Sync now (or verify CloudProfileReportingEnabled and UserSecuritySignalsReporting are true at chrome://policy).
  - The device will immediately register in Cloud Identity in Pending approval (PENDING_APPROVAL) state and appear in the Device Trust Gateway Portal ready for approval.
Activate Workspace Policy (Context-Aware Access — Education Standard/Plus & Enterprise):
- Open Google Workspace Admin Console > Security > Access and data control > Context-Aware Access.
- Click Create Access Level, switch to Advanced mode, and create an Access Level named Approved Devices Only with CEL expression:
```
device.is_corp_owned_device == true || device.is_admin_approved_device == true
```
  [!NOTE] Company-Owned vs. Admin-Approved Explained:
  - device.is_corp_owned_device == true: Matches official enterprise hardware trust anchors (e.g., district Chromebooks enrolled via Directory API or Macs/PCs imported into Company-Owned Inventory). These devices access Workspace apps directly without self-service approval.
  - device.is_admin_approved_device == true: Matches personal BYOD hardware (Macs, Windows laptops, phones) where the user binding has been explicitly approved via the Device Trust Portal (managementState: APPROVED). Personal devices start blocked and regain access only after approval.
- Click Assign to apps:
  - ⚠️ Important (Target Organizational Unit Selection): In the left Organizational Unit tree, do NOT leave this policy assigned to the Root Organizational Unit (/). The Admin Console defaults to the Root OU, which will immediately apply the policy domain-wide to all users (including Super Admins and faculty) and can cause catastrophic lockouts. Instead, explicitly select your target OU (e.g., Students OU or a dedicated Test / Pilot OU).
  - App Assignment: Assign this level to the Workspace Apps of your choice (eg. Gmail, Drive…).
  - Enforcement Policy: Set policies to Block when policies / access levels are not met.
  - Desktop & Mobile Apps: Ensure policy is set to Enable for Apply to Google desktop and mobile apps (to enforce policy across native clients like Gmail mobile and Google Drive for Desktop in addition to web browsers).
Enable Enforcement in the Admin Portal (#/admin — Disabled by Default on New Installs):
- For safety, every fresh installation starts with both Session Management (session_watch_enabled: false) and Context-Aware Access Integration (caa_enforcement_enabled: false) disabled by default (⚙️ ENFORCEMENT STANDBY — CONFIGURE IN ADMIN).
- Open your live portal URL and click ⚙️ Admin Config (#/admin).
- Toggle on Session Management (Education Fundamentals), Context-Aware Access Integration (Education Standard & Plus), or Both, configure your target Organizational Units / Groups if desired, and click 💾 Save Configurations.
- Click 🔄 Sync Inventory Cache in the Admin Telemetry card to pre-warm your approved device inventory.

🎉 Done! Your portal is now fully live and securing your enterprise workspace!

Tip

💡 Misplaced your live Portal URL? If you need to retrieve your unique portal URL later for testing or bookmarking:

In Google Cloud Console: Go to Cloud Run > click device-trust-gateway. The live HTTPS service URL is displayed directly at the top of the service page.
Via Terminal (CLI): Run gcloud run services describe device-trust-gateway --region us-central1 --format='value(status.url)'
Admin Configuration UI: Append /#/admin to your portal URL (e.g. https://device-trust-gateway-xyz-uc.a.run.app/#/admin).

⚡ Automated Interactive Deployer (Recommended)

We have included a robust interactive deployment script (deploy.sh) that streamlines setup across all target environments.

To launch the deployer from your terminal, run:

./deploy.sh

CLI Flags & Options:

You can pass command-line flags or environment variables to customize the deployment workflow or diagnose issues:

# Enable verbose logging and live Cloud Build streaming
./deploy.sh --verbose   # or -v

# Bypass GCP billing account verification (useful if billing is managed centrally)
./deploy.sh --skip-billing-check

# Provide Project ID and Region directly
./deploy.sh --project my-gcp-project-id --region us-central1 --target 1

# View full CLI help
./deploy.sh --help

Flag	Env Variable	Description
`-v`, `--verbose`	`VERBOSE=true`	Enables verbose logging, debug command output, and live Cloud Build streaming.
`--skip-billing-check`	`SKIP_BILLING_CHECK=true`	Bypasses pre-flight billing verification if your account lacks billing viewer IAM rights.
`--project <ID>`	`GCP_PROJECT=<ID>`	Pre-configures Google Cloud Project ID.
`--region <REGION>`	`GCP_REGION=<REGION>`	Pre-configures Cloud Run / Scheduler target region (default: `us-central1`).
`--target <1\|2>`	`DEPLOY_TARGET=<1\|2>`	Pre-selects deployment target (`1`: Google Cloud Run, `2`: On-Premise Docker).
`--mode <MODE>`	`ENFORCEMENT_MODE=<MODE>`	Sets initial enforcement mode (`DISABLED` [default for new installs], `SESSION_WATCH`, `CAA`, or `BOTH`).
`--sweep-cadence <sub10s\|1min>`	`SWEEP_CADENCE=<sub10s\|1min>`	Selects Session Watch polling cadence (`sub10s` [default, ~$38–$43/mo] or `1min` [$0/mo GCP Free Tier]).
`-h`, `--help`	—	Displays the CLI help and options menu.

You will be presented with a simplified interactive menu:

Please select your desired deployment target:
  1) Google Cloud (GCP Cloud Run + Secret Manager)
  2) On-Premise (Docker Compose + Local .env)
  3) Exit

Three-Phase Cloud Run Deployment Workflow:

When deploying to Google Cloud, the script seamlessly solves the OAuth origin "chicken-and-egg" problem:

Phase 1 (Baseline Service): Executes an initial container build and Cloud Run deployment to establish your unique live HTTPS service URL (https://device-trust-gateway-HASH-uc.a.run.app).
Phase 2 (Interactive Setup): Displays explicit instructions prompting you to authorize this newly generated live URL as an Authorized JavaScript Origin in the Google Cloud Console, pausing to collect your resulting Client ID string.
Phase 3 (Final Revision): Re-executes Cloud Build forwarding the authorized Client ID, permanently baking it into the compiled Webpack React static bundle and deploying the final revision.

Domain-Wide Delegation (DWD) Setup Wizard:

When configuring live API execution or Chromebook fleet seeding, the script launches an interactive DWD Setup Wizard:

Automatically verifies or creates a dedicated Google Cloud Service Account (device-trust-gateway-sa).
Generates and downloads a private JSON key (dwd_key.json).
Extracts your exact Service Account Client ID.
Displays explicit instructions to authorize the Client ID and required scopes in the Google Workspace Admin Console (https://admin.google.com/ac/owl/domainwidedelegation), pausing execution until you confirm authorization.
Prompts for your Super Administrator email and exports credentials for flawless impersonation.

🔒 Endpoint Verification & BYOD Approval Lifecycle

To successfully deploy Context-Aware Access (CAA) policies that mandate device approval without enforcing intrusive Mobile Device Management (MDM) enrollment on employee personal hardware, organizations rely on the interplay between Google Endpoint Verification and the Device Trust Gateway.

+-----------------------------------------------------------------------------------+
|                           Personal BYOD Laptop / Phone                            |
|                (Employee installs Endpoint Verification extension)                |
+-----------------------------------------+-----------------------------------------+
                                          |
                                          |  1. Registers hardware in Cloud Identity
                                          v
+-----------------------------------------------------------------------------------+
|                          Google Cloud Identity Catalog                            |
|                                                                                   |
|     [ INITIAL STATE: managementState == PENDING_APPROVAL / UNMANAGED ]            |
+-----------------------------------------+-----------------------------------------+
                                          |
                                          |  2. Employee attempts Workspace login
                                          v
+-----------------------------------------------------------------------------------+
|                   Google Workspace Context-Aware Access (CAA)                     |
|                                                                                   |
| [ RULE: device.is_corp_owned_device == true || device.is_admin_approved_device == true ] |
|     [ RESULT: Blocks unapproved BYOD laptop with 403 Access Denied screen ]       |
+-----------------------------------------+-----------------------------------------+
                                          |
                                          |  3. Blocked employee visits Gateway
                                          v
+-----------------------------------------------------------------------------------+
|                       Device Trust Gateway Approval Portal                        |
|                                                                                   |
|     [ ACTION: Employee clicks ✓ Approve on their pending hardware row ]           |
|     [ BACKEND: Executes service.devices().deviceUsers().approve(...) ]            |
+-----------------------------------------+-----------------------------------------+
                                          |
                                          |  4. Instantly updates Cloud Identity
                                          v
+-----------------------------------------------------------------------------------+
|                          Google Cloud Identity Catalog                            |
|                                                                                   |
|     [ UPDATED STATE: managementState == APPROVED ]                                |
|     [ CAA RESULT: Evaluates is_admin_approved_device == true. Access Granted! ]   |
+-----------------------------------------------------------------------------------+

Step-by-Step BYOD Lifecycle Workflow:

Endpoint Verification Enrollment: Administrators force-install the lightweight Google Endpoint Verification browser extension (callobklhcbilhphinckomhgkigmfocg) via the Google Admin Console across target OUs (or users install it on personal Chrome profiles / Google Smart Lock on mobile). The extension collects hardware identifiers, OS version, and cryptographic certificates, registering the device in Cloud Identity as an unmanaged asset. By default, its device user binding initializes with managementState set to PENDING_APPROVAL or UNMANAGED.
CAA Guardrail Interception: The Workspace Administrator activates a Custom Access Level in the Workspace Admin Console (https://admin.google.com/ac/security/contextaware) enforcing:
```
device.is_corp_owned_device == true || device.is_admin_approved_device == true
```
When the employee attempts to open Gmail, Google evaluates their personal laptop. Because it is not company owned (is_corp_owned_device == false) and its Cloud Identity binding is still pending (is_admin_approved_device == false), CAA blocks them instantly at the edge with a 403 Access Denied screen.
Gateway Self-Service Approval: The employee navigates to the Gateway portal (https://device-trust-gateway-...), authenticating securely via Google Sign-In. Our backend executes a filtered query (service.devices().list(filter=f"email:{user_email}")) and surfaces their pending laptop.
Instant Policy Resolution: The employee clicks [✓ Approve]. The Gateway backend invokes Cloud Identity (service.devices().deviceUsers().approve(...)), immediately shifting the binding's managementState to APPROVED. The employee reloads Gmail, CAA evaluates device.is_admin_approved_device as true, and enterprise access is instantly restored!

🏢 Moving Devices into Company-Owned Inventory & Seeding Fleet

In Google Workspace Context-Aware Access, devices evaluating device.is_corp_owned_device == true must be registered in Company-Owned Inventory (distinct from personal BYOD devices that require device.is_admin_approved_device == true).

If you have already deployed the Gateway (or skipped seeding during the ./deploy.sh installer), you can move devices into Company-Owned Inventory at any time using the methods below:

Method 1: ChromeOS Fleet Seeding Tool (One-Line Terminal Execution)

To immediately crawl all active enterprise Chromebooks from the Directory API and anchor them in Cloud Identity as Company-Owned assets:

# Run from your local repository folder:
WORKSPACE_ADMIN_EMAIL=admin@yourdomain.com \
GOOGLE_APPLICATION_CREDENTIALS=dwd_key.json \
backend/venv/bin/python backend/scripts/seed_company_inventory.py

What it does: Automatically queries admin.directory.device.chromeos and batch-registers all managed Chromebooks into Cloud Identity under ownerType: COMPANY.

Method 2: Automated Recurring Synchronization (GCP Cloud Scheduler)

To continuously synchronize newly enrolled enterprise Chromebooks automatically on a daily schedule:

gcloud scheduler jobs create http seed-chromebook-inventory-daily \
  --schedule="0 2 * * *" \
  --uri="https://YOUR-GATEWAY-URL/api/cron/cleanup" \
  --http-method=POST \
  --headers="X-CloudScheduler=true" \
  --location=us-central1

Method 3: Company-Owned Macs, Windows PCs & Mobile (Google Admin Console CSV Upload)

For non-ChromeOS company assets (such as district-issued MacBooks, Windows desktops, or school iPads):

Open Google Admin Console > Devices > Mobile & endpoints > Company-owned inventory.
Click Import company-owned devices (the + / Import button at the top).
Select your device type (Company-owned computers for Mac/PC/Linux, or Company-owned mobile devices for iOS/Android).
Download the CSV template and populate your hardware Serial Numbers and Asset Tags.
Upload the CSV and click Import.
How it works: When users sign in with the Endpoint Verification extension installed on these company Macs/PCs, Google automatically matches the hardware serial number to the Company-Owned inventory, tagging the device as is_corp_owned_device == true!

🚀 Manual Setup: Local Development

If you prefer setting up the environment manually without the script:

1. Start the Backend (FastAPI)

Navigate to the root directory and install Python dependencies:

cd backend
python -m venv venv
source venv/bin/activate
pip install -r requirements.txt
uvicorn backend.main:app --host 127.0.0.1 --port 8080 --reload

Interactive API documentation will be available at http://127.0.0.1:8080/docs.

2. Start the Frontend (React)

In a new terminal, start the React server:

cd frontend
npm install
npm start

The frontend UI will automatically open at http://localhost:3000.

🐳 Manual Setup: Docker (On-Premise)

Create a local .env file at the root directory:

USE_SECRET_MANAGER=false
TENANT_CUSTOMER_ID=customers/my_customer
TENANT_INACTIVITY_THRESHOLD=90
TENANT_PORTAL_ADMINS=[]

Build and start the container:

docker-compose -f deploy/docker-compose.yml up --build -d

☁️ Manual Setup: Google Cloud (GCP Cloud Run)

Enable required Google Cloud APIs:

gcloud services enable run.googleapis.com secretmanager.googleapis.com cloudidentity.googleapis.com cloudbuild.googleapis.com cloudscheduler.googleapis.com pubsub.googleapis.com firestore.googleapis.com admin.googleapis.com iap.googleapis.com compute.googleapis.com accesscontextmanager.googleapis.com

Create a Secret Manager secret to hold dynamic tenant configurations:

gcloud secrets create device_trust_gateway_config --replication-policy="automatic"

Build and deploy the container to Cloud Run:

gcloud builds submit --tag gcr.io/YOUR_PROJECT_ID/device-trust-gateway deploy/
gcloud run deploy device-trust-gateway --image gcr.io/YOUR_PROJECT_ID/device-trust-gateway --platform managed --region us-central1 --set-env-vars="USE_SECRET_MANAGER=true,SECRET_NAME=device_trust_gateway_config"

⚙️ Configuration & Admin UI (`#/admin`)

Once the application is running, Workspace Administrators can dynamically configure enforcement modes, rollout scope, and inspect real-time session telemetry directly via the Admin Portal (#/admin).

1. New Installation Default (`DISABLED` Standby Mode) vs. Active Enforcement

Fresh Installations Start Disabled by Default: Every new installation via ./deploy.sh, Docker Compose, or a blank Secret Manager secret initializes with:
- session_watch_enabled: false (Session Management for Education Fundamentals)
- caa_enforcement_enabled: false (Context-Aware Access Integration for Education Standard & Plus)
- enforcement_mode: "DISABLED"
Why Standby by Default? This ensures zero unexpected session revocations or user lockouts while the administrator completes initial Domain-Wide Delegation, Chrome Profile Reporting, and Chromebook inventory seeding. While disabled, administrators see a prominent ⚙️ ENFORCEMENT STANDBY — CONFIGURE IN ADMIN badge in the top bar, and the 1-minute Cloud Scheduler sweep safely returns SKIPPED_DISABLED.
Activating Enforcement in #/admin:
1. Navigate to #/admin (or click ⚙️ Admin Config in the top navigation bar).
2. Check Session Management (Education Fundamentals) to enable the 3-layer <0.5s inline check + ~2–10s Cloud Identity lastSyncTime sub-polling + users.signOut & OAuth grant revocation pipeline.
3. Check Context-Aware Access Integration (Education Standard & Plus) to enable CAA policy remediation banners and self-service pairing code workflows.
4. (Optional) Enable Both simultaneously (enforcement_mode: "BOTH") for defense-in-depth (CAA blocks Workspace web apps at the edge while Session Management immediately terminates underlying accounts.google.com sessions and OAuth tokens on unapproved devices).
5. Click 💾 Save Configurations. Changes persist immediately to Google Cloud Secret Manager (device_trust_gateway_config) or .env.

2. Unified User/Admin View (`#/`) vs. Admin-Only Controls (`#/admin`)

Unified Main Dashboard (#/): All users—including Super Administrators—experience the exact same clean device approval interface on #/.
- Company-Owned Devices (ownerType: COMPANY): Strictly filtered to hardware the signed-in user has personally accessed (email in recentUsers). Administrators are never cluttered with domain-wide Chromebooks they haven't logged into.
- Personal BYOD Devices (ownerType: USER): Displays the user's personal laptops and phones with self-service ✓ Approve, ✕ Revoke, 🔗 Generate Pairing Code, and ⏱️ + Add Personal Device (15m Grace Pass) actions.
Admin-Only Operational Controls (#/admin):
- 🔄 Sync Inventory Cache: Pre-warms and synchronizes approved ChromeOS serials and Cloud Identity APPROVED BYOD serials into the backend SQLite/RAM cache.
- 🛡️ Attest Current Session: Manually records an attested browser heartbeat for the admin's current session.
- ⚡ Run Live Login Sweep: Triggers an immediate on-demand audit sweep (force=true) across Cloud Identity deviceUsers (PENDING_APPROVAL & BLOCKED syncs) and Admin SDK Reports API login events, displaying evaluated counts, revocations, and the Recent Session Enforcement & Verification Events feed.

🧪 Testing & Live Verification Matrix

Live Test Environment (`devicetrustportal` / `gwfe.org`) vs. New Installs

Setting / Capability	New Install Default (`./deploy.sh`)	Active Live Test Environment (`gwfe.org`)
`session_watch_enabled` (Fundamentals Session Management)	`false` (Standby until enabled in `#/admin`)	`true` (Enabled for live testing)
`caa_enforcement_enabled` (Standard/Plus CAA Integration)	`false` (Standby until enabled in `#/admin`)	`true` (Enabled for live testing)
`enforcement_mode`	`"DISABLED"`	`"BOTH"`
Cloud Scheduler (`session-watch-login-sweep`)	`* * * * *` (No-ops with `SKIPPED_DISABLED` until enabled)	*` * * * ` (Active: 5x 10s sub-polls per minute)*
Inline Portal Session Check (`GET /api/session-watch/session-status`)	Inactive until `session_watch_enabled: true`	Active (`< 0.5s` on mount + `8s` heartbeat + JWT `iat` validation)
Admin Exemption (`session_watch_exempt_admins`)	`false` (Admins can test enforcement with their own account)	`false` (Verified live with `claycodes@gwfe.org`)

Running the Automated Test Suite (85 Total Tests)

You can run the complete backend and frontend test suites locally before deploying:

# 1. Run Backend Unit & Integration Tests (75 pytest tests covering 3-layer session guard,
#    Cloud Identity PENDING_APPROVAL & re-logged-in BLOCKED sweeps, JWT iat invalidation,
#    shared Wi-Fi NAT protection, OU/Group scoping, and strict recentUsers filtering):
PYTHONPATH=. backend/venv/bin/pytest backend/tests/ -q

# 2. Run Frontend Component & Heartbeat Tests (10 Vitest tests covering unified Dashboard,
#    inline 401 session termination, 15m onboarding grace pass, and Admin Config):
npm --prefix frontend test

# 3. Verify Production Frontend Bundle Compilation:
npm --prefix frontend run build

🔐 Firewall, Network Allowlist & Anti-Spoofing

If you are deploying the Gateway on-premise (Docker Compose) inside an enterprise network, explicit firewall rules are required for both incoming user traffic and outgoing Google API communication, alongside strict reverse proxy anti-spoofing security measures.

For the complete, detailed specification covering exact ports, protocols, reverse proxy header stripping, and Uvicorn trust configurations, please refer to our dedicated enterprise guide: 👉 docs/network_requirements.md

Summary of Anti-Spoofing Security Tiers:

🛡️ Upstream Proxy Stripping: Enterprise reverse proxies (Nginx, F5, Cloudflare) must actively strip forged X-Forwarded-For headers arriving from external internet interfaces, overwriting them with authentic TCP socket client IPs.
🔒 Uvicorn Trust Gating (--forwarded-allow-ips): Configure Uvicorn to only accept forwarded IP headers if they arrive directly from the known internal IP address of your reverse proxy host.
🔑 Session Binding: Network IP trust alone cannot grant device approval. Requesting clients must also present a valid, authenticated Google Workspace OIDC Bearer token session for the target user.

🔒 Identity-Aware Proxy (IAP) Edge Gating: Standard Mode vs. Strict Gating

When deploying the Device Trust Gateway, administrators must decide how the portal itself is accessed:

1. Standard Mode (Default — Strongly Recommended for K-12, Higher Ed & Hybrid Teams)

How it works: Cloud Run is hosted over public HTTPS and secured by Google Workspace OAuth 2.0 Sign-In and Trust Chaining (6-digit pairing codes).
Why it's essential for Schools & Homework: Students at home working on a personal PC or Mac can open the portal on their school-issued Chromebook, generate a 6-digit pairing code, and approve their home computer in seconds. They are never locked out of doing evening homework or accessing Google Classroom/Drive.

2. Strict IAP Edge Defense Mode (For High-Security On-Premise-Only Corporate Networks)

How it works: Cloud Run is placed behind an External HTTP(S) Load Balancer and Google Cloud Identity-Aware Proxy (IAP), restricting ingress strictly to corporate egress IP CIDRs or company-owned hardware.
⚠️ Warning for Schools: If enabled, students attempting to access the portal from home internet will receive a 403 Forbidden error. They will not be able to approve personal devices or complete assignments until they physically connect to the school network or VPN.

For full architectural blueprints, diagrams, and Access Context Manager setup guides: 👉 docs/caa_architecture_overview.md — Comprehensive Zero-Trust & IAP Architecture Whitepaper 👉 docs/master_enterprise_deployment_guide.md — Master Enterprise Deployment Guide

🛠️ Troubleshooting & AI Diagnostics with Gemini

If personal BYOD devices are not appearing as Pending approval, if you see unexpected warnings in chrome://policy, or if gcloud encounters path issues on Windows Git Bash (MINGW64), see our dedicated guide:

👉 docs/troubleshooting_guide.md — Full Troubleshooting & AI Diagnostics Guide

Quick AI-Assisted Triage with Gemini

The portal automatically streams frontend browser events ([CLIENT_LOG]) directly into Cloud Run server logs alongside backend Cloud Identity API traces ([devices.py], [cloud_identity.py]). You can export a diagnostic bundle and ask Gemini to pinpoint the exact configuration fix:

Export Cloud Run Server + Client Telemetry Logs:

gcloud logging read \
  'resource.type="cloud_run_revision" AND resource.labels.service_name="device-trust-gateway"' \
  --project=YOUR_GCP_PROJECT_ID \
  --limit=150 \
  --format=json > cloud_run_logs.json

Export Chrome Policies from the Test Device: Open chrome://policy on the test laptop, click Reload policies, and click Export to JSON (policies.json).
Ask Gemini: Attach cloud_run_logs.json and policies.json to Gemini (along with the prompt template in docs/troubleshooting_guide.md) to automatically verify Domain-Wide Delegation scopes, WORKSPACE_ADMIN_EMAIL impersonation, Cloud Identity device states, and Chrome Profile Reporting policies (CloudProfileReportingEnabled, UserSecuritySignalsReporting, UserSecurityAuthenticatedReporting).

Name		Name	Last commit message	Last commit date
backend		backend
deploy		deploy
docs		docs
frontend		frontend
.dockerignore		.dockerignore
.envrc		.envrc
.gcloudignore		.gcloudignore
.gitignore		.gitignore
ARCHITECTURE_AND_SCALE.md		ARCHITECTURE_AND_SCALE.md
CONTRIBUTING		CONTRIBUTING
Device Trust Portal PRD.md		Device Trust Portal PRD.md
LICENSE		LICENSE
README.md		README.md
cloudbuild.yaml		cloudbuild.yaml
deploy.sh		deploy.sh
firestore.rules		firestore.rules

Latest commit

History

Folders and files

Repository files navigation