Skip to content

googleworkspace/devicetrustportal

BranchesTags

Repository files navigation

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

  1. 📘 Master Enterprise Deployment Guide
  2. Architecture & Zero-Trust Overview
  3. Google Workspace Settings & Extension Guide
  4. Prerequisites & Billing Check
  5. ⚡ Automated Interactive Deployer (Recommended)
  6. 🔒 Endpoint Verification & BYOD Approval Lifecycle
  7. Chromebook Fleet Seeding Tool
  8. Manual Setup: Local Development
  9. Manual Setup: Docker (On-Premise)
  10. Manual Setup: Google Cloud (GCP Cloud Run)
  11. Configuration & Admin UI
  12. Firewall, Network Allowlist & Anti-Spoofing
  13. 🔒 Identity-Aware Proxy (IAP) Edge Gating

🏛 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/caa_architecture_overview.md — Enterprise zero-trust architecture whitepaper.

Key Architectural Principles:

  • Unmanaged BYOD Hardware: Personal devices do not require intrusive Mobile Device Management (MDM) enrollment or profiles. Users install the lightweight Endpoint Verification browser extension, registering the device as "Unmanaged" while still allowing our backend to approve them (devices.deviceUsers.approve), satisfying CAA policy rules while preserving user privacy.
  • Trust Anchor: Automatically trusts company-owned inventory (e.g. ChromeOS zero-touch devices).
  • Minimalist Single Portal: Consolidates all device reporting, administrative configurations, and lifecycle approvals into a unified, highly responsive centerpiece layout.
  • Automated Lifecycle Management: A secure cron endpoint (/api/cron/cleanup) automatically revokes access for inactive BYOD devices older than X days.

🛠 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 with Context-Aware Access (CAA) enabled.
  • Service Account Credentials with Domain-Wide Delegation (DWD) authorized in Google Workspace Admin Console (https://admin.google.com/ac/owl/domainwidedelegation) for the following 7 required OAuth scopes:
    • https://www.googleapis.com/auth/cloud-identity.devices
    • https://www.googleapis.com/auth/cloud-identity
    • https://www.googleapis.com/auth/admin.directory.user.readonly
    • https://www.googleapis.com/auth/admin.directory.group.readonly
    • https://www.googleapis.com/auth/admin.directory.group.member.readonly
    • https://www.googleapis.com/auth/admin.directory.rolemanagement.readonly
    • https://www.googleapis.com/auth/admin.directory.device.chromeos.readonly
  • Node.js (v26+) and Python (3.14+) 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 26 and Python 3.14 automatically inside container build stages).

Important

Pre-Deployment Billing Verification: The automated ./deploy.sh script actively inspects your GCP project's billing status before initiating setup. If billing is missing, it will provide direct links to the Google Cloud Billing Console (https://console.cloud.google.com/billing) so you can link an account and proceed without encountering API precondition failures.

🐣 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:

  1. Git (Tool to download the repository):

    • Mac: Open Terminal and type xcode-select --install (click Install when prompted).
    • Windows: Download and run the installer from git-scm.com.
    • Linux (Ubuntu/Debian): Run sudo apt update && sudo apt install -y git.

  2. Google Cloud SDK (gcloud CLI) (Tool to connect to your Google Cloud Project):

    • Download the installer for your OS from cloud.google.com/sdk/docs/install (or run curl https://sdk.cloud.google.com | bash in macOS/Linux terminal).
    • Once installed, log into your Google Cloud account by running: 
      gcloud auth login

Step 2: Download the Code from GitHub

Open your Terminal (Mac/Linux) or Command Prompt / Git Bash (Windows) and run:

# 1. Download the code repository from GitHub
git clone https://github.com/googleworkspace/devicetrustportal.git

# 2. Change directory into the downloaded project folder
cd devicetrustportal

Step 3: Run the Automated Deployment Wizard

Run the interactive deployment wizard script:

# Make the script executable (macOS / Linux)
chmod +x deploy.sh

# Run the deployment wizard
./deploy.sh

Step 4: Follow the On-Screen Prompts

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

  1. Select Deployment Target:

    • Type 1 for Google Cloud (GCP Cloud Run + Secret Manager) and press Enter.

  2. 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).

  3. 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).

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

  5. Access Control & IAP Edge Defense:

    • Select option 1 for IP Subnet Gating AND (Company-Owned OR Admin-Approved BYOD Devices).
    • Enter your corporate Public Egress IP ranges (e.g., 203.0.113.0/24) or internal subnets if using Cloud VPN/Interconnect, or press Enter to allow any IP.

  6. Activate Workspace Policy:

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

⚡ 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

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:

  1. 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).
  2. 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.
  3. 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:

  1. Automatically verifies or creates a dedicated Google Cloud Service Account (device-trust-gateway-sa).
  2. Generates and downloads a private JSON key (dwd_key.json).
  3. Extracts your exact Service Account Client ID.
  4. 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.
  5. 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 == true || device.is_admin_approved == 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 == true. Access Granted! ]          |
+-----------------------------------------------------------------------------------+

Step-by-Step BYOD Lifecycle Workflow:

  1. Endpoint Verification Enrollment: Employees install the lightweight Google Endpoint Verification browser extension (or Google Smart Lock app 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.
  2. 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 == true || device.is_admin_approved == true
    When the employee attempts to open Gmail, Google evaluates their personal laptop. Because it is not company owned (is_corp_owned == false) and its Cloud Identity binding is still pending (is_admin_approved == false), CAA blocks them instantly at the edge with a 403 Access Denied screen.
  3. 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.
  4. 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 as true, and enterprise access is instantly restored!

💻 Chromebook Fleet Seeding Tool

For organizations with tens of thousands or hundreds of thousands of active ChromeOS devices, we provide an automated inventory seeding tool (seed_company_inventory.py) and real-time webhook endpoints (/api/webhook/chrome-enrollment).

This tool is seamlessly integrated into ./deploy.sh and supports four execution frequencies:

  1. One-Time Execution: Runs the crawl immediately from your terminal, paginating through the Directory API and executing batch registration requests against Cloud Identity.
  2. Daily Recurring Schedule: Configures a Google Cloud Scheduler cron job to run daily at 2:00 AM.
  3. Weekly Recurring Schedule: Configures a Google Cloud Scheduler cron job to run every Sunday at 3:00 AM.
  4. Event-Driven Real-Time Webhook (Pub/Sub Push) + Weekly Safety Net: Establishes a real-time Google Cloud Pub/Sub push subscription listening for Google Workspace Reports API enrollment events (ENTERPRISE_ENROLLMENT), anchoring newly enrolled Chromebooks instantly while maintaining a weekly recurring sync as a reliable safety net.

🚀 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)

  1. 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=[]
  1. Build and start the container:
docker-compose -f deploy/docker-compose.yml up --build -d

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

  1. 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 admin.googleapis.com iap.googleapis.com compute.googleapis.com accesscontextmanager.googleapis.com
  1. Create a Secret Manager secret to hold dynamic tenant configurations:
gcloud secrets create device_trust_gateway_config --replication-policy="automatic"
  1. 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

Once the application is running, Workspace Administrators can dynamically update tenant configurations directly via the UI.

  1. Access the portal and navigate to Admin Configurations (or visit #/admin).
  2. Ensure your active user profile has Workspace Super Admin privileges or is listed in the portal_admins delegation list.
  3. Update settings such as Inactivity Threshold (Days) and Authorized Portal Administrators.
  4. Click Save Configurations. Changes will instantly persist to Secret Manager (GCP mode) or your local .env file (on-premise mode).

🔐 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

To ensure the Gateway portal itself can only be reached from company-owned hardware or trusted corporate IP ranges, organizations can place Cloud Run behind an External HTTP(S) Load Balancer and enable Identity-Aware Proxy (IAP).

For the complete, step-by-step IAP architecture and Access Context Manager configuration blueprint, please refer to our dedicated zero-trust guide: 👉 docs/caa_architecture_overview.md

About

No description, website, or topics provided.

Resources

Readme

License

Apache-2.0 license

Contributing

Contributing

Security policy

Security policy
Activity
Custom properties

Stars

3 stars

Watchers

0 watching

Forks

0 forks
Report repository

Releases

No releases published

Packages

 
 
 

Contributors

Languages