Google Workspace Admin Tools

A collection of tools for managing Google Workspace (formerly G Suite), with both GAM (bash) and Python (Admin SDK) implementations.

Overview

This repository contains tools for:

• Calendar management - Delete events for specific users
• Groups management - Search and manage groups
• User management - Update employee types, list users, automated syncing

Implementation Options

Each category may contain multiple implementations:

• GAM (bash) - Traditional bash scripts using GAM command-line tool
• Python - Modern Python scripts using Google Workspace Admin SDK (cloud-ready)

Important: How Employee Type Sync Works

The Python sync script (users/python/set_employee_type.py) follows this logic:

What it does:

• Scans users in /-admins OU → Sets their Type of employee to "Admin Account"
• Scans users in /-service-accounts OU → Sets their Type of employee to "Service Account"
• Only updates users whose Type doesn't match (efficient, skips already-correct users)

What it does NOT do:

• ❌ Does NOT touch users outside these OUs
• ❌ Does NOT clear/unset Type for users who leave the OUs
• ❌ Does NOT delete or modify users

Why this matters: This script is OU-aware and additive only. If you move a user OUT of /-admins or /-service-accounts, their Type of employee will remain set (won't be automatically cleared). This is intentional to prevent accidental data loss.

If you need cleanup: Create a separate script to handle users who move out of these OUs. The sync script focuses only on ensuring users IN the specified OUs have the correct Type set.

Prerequisites

1. GAM Installation

1. Install GAM (Google Apps Manager):

   # For macOS (using Homebrew)
   brew install gam
   
   # For Linux
   sudo apt-get install gam  # Debian/Ubuntu
   sudo yum install gam      # RHEL/CentOS

2. Verify GAM installation:

   gam version

3. Configure GAM with your Google Workspace admin account:

   gam oauth create

4. Test GAM access:

   gam info user

2. System Requirements

• Bash shell
• Google Workspace admin access
• Python 3.6+ (required by GAM)

Installation

1. Clone this repository:

git clone https://github.com/yourusername/google-workspace-admin-tools.git
cd google-workspace-admin-tools

2. Configure your organization settings:

   # Copy the example configuration:
   cp config/org-config.example.sh config/org-config.sh
   
   # Edit `config/org-config.sh` with your organization's settings:
   # Organization Settings
   ORG_DOMAIN="your-domain.com"
   ORG_NAME="Your Organization Name"
   ORG_UNIT_ROOT="/External Users"  # Root OU for external users
   
   # External Organization OUs
   ORG_UNIT_EXTERNALS="/External Users"  # Main external users OU
   ORG_UNIT_GENEEA="/External Users/External Org 1"  # First external organization
   ORG_UNIT_NETHOST="/External Users/External Org 2"  # Second external organization
   ORG_UNIT_REVOLGY="/External Users/External Org 3"  # Third external organization
   
   # Calendar Settings
   CALENDAR_ID="your-calendar-id@group.calendar.google.com"

Usage

Calendar Management

Delete calendar events (GAM):

./calendar/delete-events.sh --from-date YYYY-MM-DD user@email.com

Options:

• --dry-run: Show what would be deleted without actually deleting
• --from-date: Specify start date for event deletion (YYYY-MM-DD format)
• --help: Show usage information

Groups Management

Find group by email (GAM):

./groups/find-group-by-email.sh user@email.com

User Management

GAM Scripts

List users:

./users/gam/list-users.sh

Update contractor types:

./users/gam/update-contractor-type.sh

Update employee type for specific user:

./users/gam/update-employee-type.sh user@email.com "Employee Type"

Python Scripts (Cloud-Ready)

Automated employee type sync:

cd users/python
python set_employee_type.py --dry-run

See users/python/README.md for complete Python deployment guide (Cloud Functions, Cloud Run, etc.)

Directory Structure

google-workspace-admin-tools/
├── calendar/              # Calendar management tools
│   └── delete-events.sh   # Delete calendar events (GAM)
├── groups/                # Groups management tools
│   └── find-group-by-email.sh  # Search for groups (GAM)
├── users/                 # User management tools
│   ├── gam/               # GAM (bash) implementations
│   │   ├── list-users.sh
│   │   ├── update-contractor-type.sh
│   │   └── update-employee-type.sh
│   └── python/            # Python (Admin SDK) implementations
│       ├── set_employee_type.py  # Main script
│       ├── keboola_component_sync_employee_types.py  # Keboola wrapper
│       ├── requirements.txt
│       ├── README.md      # Deployment guide
│       └── service-account.json.example
├── config/                # Configuration files
│   ├── gam-config.sh
│   └── org-config.sh.template
├── LICENSE
└── README.md

Why Two Implementations?

• GAM scripts - Quick, traditional approach. Great for local/manual tasks
• Python scripts - Cloud-native, automated. Deploy to Cloud Functions, Cloud Run, etc.

For AI Coding Assistants

This README serves as the primary documentation for AI agents (Claude, Gemini, etc.) working on this codebase.

Key Architecture Principles:

1. Organization by function - Tools are grouped by what they manage (calendar, groups, users)
2. Multiple implementations - GAM (bash) for manual/local, Python for cloud/automation
3. OU-driven logic - Python sync only sets Types for users IN specified OUs, never clears
4. Configuration-driven - All paths and settings in config/ directory
5. Service account authentication - Python uses domain-wide delegation for API access

When extending this repository:

• Add new categories as top-level directories (e.g., drives/, devices/)
• Provide both GAM and Python implementations where applicable
• Document OU-based logic clearly if scripts are OU-aware
• Never auto-remove or clear data - make scripts additive only
• Always support dry-run mode for testing

When creating Keboola components:

• Create a single wrapper file: keboola_component_{script_name}.py
• Use keboola.component.CommonInterface for configuration
• Read parameters from ci.configuration.parameters
• Service account handling: Accept as encrypted parameter #service_account_json (can be string OR object), write to temp file
• Handle both string and dict formats: Keboola may pass JSON as parsed object or raw string
• Never expect service account files in /data/in/files/ - code is deployed from public GitHub!
• Set environment variables for the main script
• Write state file with ci.write_state_file() for monitoring
• Handle errors with proper exit codes (0=success, 1=config error, 2=runtime error)
• Clean up temporary files in finally block
• Document parameters in the main README with table format (including #service_account_json)
• Keep wrapper simple - just configuration and execution bridge
• Add requirements.txt to repo root - Keboola only reads from root for git source

Using Keboola MCP to manage components:

• Use mcp__keboola__get_jobs to check job status and errors
• Use mcp__keboola__run_job to trigger component execution
• Use mcp__keboola__get_configs to list and inspect configurations
• Use mcp__keboola__update_config to modify configuration parameters
• Use mcp__keboola__create_config to create new configurations
• Always check job logs after errors: mcp__keboola__get_jobs --job_ids '["JOB_ID"]'

OAuth Scopes Required for Python Scripts:

https://www.googleapis.com/auth/admin.directory.user
https://www.googleapis.com/auth/admin.directory.orgunit

Troubleshooting

GAM Issues

1. If GAM command is not found:

   # Check if GAM is in PATH
   which gam
   
   # If not found, add GAM to PATH in your shell profile
   echo 'export PATH="$PATH:/path/to/gam"' >> ~/.bashrc  # or ~/.zshrc
   source ~/.bashrc  # or source ~/.zshrc

2. If GAM authentication fails:

   # Re-authenticate GAM
   gam oauth delete
   gam oauth create

Configuration Issues

1. If scripts fail with "configuration not found":

   # Make sure you've copied and configured the org-config.sh file
   cp config/org-config.sh.template config/org-config.sh
   nano config/org-config.sh

2. If organization unit paths are incorrect:

   # List all organization units to find the correct paths
   gam print orgs

Contributing

1. Fork the repository
2. Create your feature branch
3. Commit your changes
4. Push to the branch
5. Create a new Pull Request

License

This project is licensed under the MIT License - see the LICENSE file for details.