Okta Terraform GitOps Template

🎯 This is a GitHub Template Repository - Click "Use this template" to create your own fork!

A complete GitOps solution for managing Okta Identity Governance (OIG) using Infrastructure as Code with Terraform, GitHub Actions, and Python automation.

🧭 Choose Your Path

New to this repository? Pick the guide that matches your goal:

Your Goal	Guide	Time	Complexity
"I just want to use Terraform locally"	LOCAL-USAGE.md	15 min	Beginner
"I want to back up my code in GitHub"	GITHUB-BASIC.md	20 min	Beginner
"I want full CI/CD with team collaboration"	GITHUB-GITOPS.md	45 min	Intermediate
"I need Terraform resource examples"	TERRAFORM-BASICS.md	Reference	Beginner
"I'm having an issue"	TROUBLESHOOTING.md	Reference	All levels

Recommended Learning Path

LOCAL-USAGE.md → GITHUB-BASIC.md → GITHUB-GITOPS.md
   (15 min)        (20 min)          (45 min)

Most users should start with LOCAL-USAGE.md - no GitHub, no CI/CD, just Terraform + Okta.

🚀 Full GitOps Setup

⚡ Ready for Team Collaboration?

👉 GITHUB-GITOPS.md - Set up GitHub Actions and team workflows

This guide covers:

Click "Use this template"
Add your Okta credentials as GitHub secrets
Import your Okta org into code
Automated validation on pull requests

🤖 Automated Setup Script

After using this template, run the setup script to configure repository settings automatically:

# One command to configure repository
./scripts/setup-repository.sh

What it configures:

✅ GitHub Actions permissions for PR creation
✅ Repository labels (template-sync, maintenance)
✅ Validates GitHub CLI authentication

Requires: GitHub CLI with admin access to the repository.

📚 Advanced Topics

For advanced configurations:

docs/AWS_BACKEND_SETUP.md - S3/DynamoDB state backend for team collaboration
docs/03-WORKFLOWS-GUIDE.md - Complete GitHub Actions workflow reference

📖 Documentation

🗂️ Documentation Index - Master guide to all 50+ documentation files

Can't find what you're looking for? Check the documentation index for:

Topic-based organization (Setup, Workflows, API, Terraform, Testing)
"I want to..." quick reference table
Links to all guides and references

What's Included

This template provides everything you need to manage Okta with GitOps:

✅ Multi-tenant structure - Manage multiple Okta organizations
✅ GitHub Actions workflows - Automated validation, planning, and deployment
✅ AWS S3 state backend - Team collaboration with state locking
✅ AD infrastructure automation - Deploy Windows Server Domain Controller with automated setup
✅ Python automation scripts - Resource owners, labels, and bulk operations
✅ AI-assisted generation - Quickly create demo environments
✅ Comprehensive documentation - Guides for every scenario
✅ Template environments - Production, staging, and development ready to customize

🚨 Important: Terraformer Limitations

Terraformer does NOT import OIG resources (the Terraform provider endpoints are new).

What this means:

✅ Terraformer imports: users, groups, apps, policies, etc.
❌ Terraformer cannot import: OIG reviews, catalogs, workflows, etc.
✅ Solution: Use our Python import scripts for OIG resources

See Terraformer Guide for full details.

🏗️ Environment-Based Architecture

This repository uses an environment-based structure where each directory represents one Okta organization.

🔒 Critical Rule: One Directory = One Okta Org

environments/
├── production/         # Your production Okta tenant (template)
├── staging/            # Your staging Okta tenant (template)
└── development/        # Your development Okta tenant (template)

To add your first environment:

# Example: Create your company environment
mkdir -p environments/mycompany/{terraform,imports,config}

# Copy template files
cp environments/myorg/terraform/* environments/mycompany/terraform/
cp environments/myorg/config/* environments/mycompany/config/

# See TEMPLATE_SETUP.md for complete setup instructions

Benefits:

✅ Complete environment isolation - no cross-org pollution
✅ Each environment uses its own GitHub Environment secrets
✅ Independent Terraform state per organization
✅ Easy to add or remove tenants
✅ Clear separation of concerns

→ See Environments README for complete guide including:

Environment isolation rules (CRITICAL)
Directory structure and organization
Import workflows for each environment
Terraform usage examples
Best practices for multi-tenant management

📋 Want to use OIG features? See OIG_PREREQUISITES.md for required setup steps (Entitlement Management must be enabled manually in GUI).

📝 Terraform Starter Templates

New to Terraform or starting with a brand new Okta org? We provide ready-to-use templates!

Each environment includes starter templates to help you quickly set up resources:

🚀 QUICKSTART_DEMO.tf.example - Ready in 2 Minutes

Perfect for: Testing, learning, quick demos

Contains:

5 demo users (employees, manager, contractor)
3 groups with memberships
1 OAuth application
Complete outputs for credentials

Deploy:

cd environments/mycompany/terraform
cp QUICKSTART_DEMO.tf.example demo.tf
# Uncomment all code, change @example.com to your domain
terraform init && terraform apply

📚 RESOURCE_EXAMPLES.tf - Comprehensive Reference

Perfect for: Finding examples of any resource type

Contains:

ALL Okta Terraform resources with examples
Users, Groups, Apps, Policies, OIG, Auth Servers, Hooks
Real-world configuration patterns
Detailed comments explaining each attribute

Usage:

# Browse for examples
less environments/mycompany/terraform/RESOURCE_EXAMPLES.tf
# Copy examples to your own .tf files

📖 README.md - Template Guide

Located in each terraform/ directory with:

Explanation of all available templates
Quick start workflows for different scenarios
Best practices (file organization, naming, escaping)
Testing and troubleshooting guides

→ See terraform/README.md for complete template guide.

🖥️ Active Directory Infrastructure (Optional)

Each environment can include AWS infrastructure for Active Directory integration with Okta.

What's Included

Per-environment infrastructure (environments/{env}/infrastructure/):

Windows Server 2022 EC2 instance configured as Domain Controller
Automated AD setup - Promotes to DC, creates OUs, groups, and sample users
VPC with public/private subnets - Isolated network per environment
Security groups - All necessary AD and RDP ports pre-configured
Okta AD Agent installer - Automatically downloaded and ready to install
Okta Privileged Access - Optional RDP access integration

Quick Deploy

# Navigate to environment infrastructure
cd environments/mycompany/infrastructure

# Configure variables
cp terraform.tfvars.example terraform.tfvars
export TF_VAR_admin_password="YourPassword123!"
export TF_VAR_ad_safe_mode_password="YourSafeModePassword123!"
export TF_VAR_okta_org_url="https://dev-12345.okta.com"

# Deploy
terraform init
terraform apply

# Wait 15-20 minutes for automated setup, then connect via RDP

What Gets Configured Automatically

After terraform apply, the Domain Controller will automatically:

✅ Rename computer to {NETBIOS}-DC01
✅ Install AD-Domain-Services role
✅ Promote to Domain Controller
✅ Create OU structure (IT, HR, Finance, Sales, etc.)
✅ Create security groups (department teams, admin groups)
✅ Create sample users with realistic names (default password: Welcome123!)
✅ Download Okta AD Agent installer to C:\Terraform\

Total setup time: ~15-20 minutes

Next Steps After Deployment

Connect via RDP using public IP from outputs
Verify AD setup - Open "Active Directory Users and Computers"
Install Okta AD Agent - Run C:\Terraform\OktaADAgentSetup.exe
Configure Okta AD integration in Admin Console
Test synchronization from AD to Okta

Cost Estimate

~$35-40/month for t3.medium instance with 50GB storage (stop when not in use to save costs)

→ See Infrastructure README for complete guide including:

Detailed architecture
Security best practices
Customization options
Troubleshooting guide
Okta Privileged Access setup

🎯 Okta Identity Governance Features

The Okta Terraform Provider (v6.4.0+ required) includes comprehensive support for Okta Identity Governance:

Terraform Provider Resources

okta_reviews - Access review campaigns for periodic certification
okta_principal_entitlements - Define what principals have access to
okta_request_conditions - Conditions for access requests
okta_request_sequences - Approval workflows with multiple stages
okta_request_settings - Global access request configuration
okta_catalog_entry_default - Configure app catalog entries
okta_catalog_entry_user_access_request_fields - Custom request fields
okta_entitlement_bundle - Group entitlements into bundles

Python API Management

These features require Python scripts (not yet in Terraform provider):

Resource Owners - Assign owners to apps, groups, and bundles
Governance Labels - Categorize resources for governance
Risk Rules (SOD Policies) - Define separation of duties policies for access certification
Admin Labeling - Automatically label admin entitlements
Bulk Operations - Manage resources at scale with rate limiting

🏗️ GitOps Workflow

This template implements a complete GitOps workflow:

For Terraform Resources

Feature Branch → Pull Request → Terraform Plan →
Code Review → Merge → Manual Apply Trigger →
Approval Gate → Terraform Apply → Okta Updated

For Labels and Owners (Python API)

Feature Branch → Pull Request → Syntax Validation →
Code Review → Merge → Auto Dry-Run →
Review Changes → Manual Apply → Okta Updated

Key Features:

✅ All changes go through pull requests
✅ Automated validation and planning
✅ Peer review before deployment
✅ Manual approval gates for production
✅ Complete audit trail in Git
✅ Drift detection via scheduled imports

See docs/GITOPS_WORKFLOW.md for detailed workflow documentation.

📦 Repository Components

GitHub Actions Workflows

Import and Sync:

import-all-resources.yml - Import all OIG resources from Okta
sync-labels.yml - Sync governance labels from Okta
export-oig.yml - Export OIG configurations to JSON

Terraform Operations:

terraform-plan.yml - Run plan on PRs (with AWS OIDC)
terraform-apply-with-approval.yml - Apply with manual approval

API Management:

apply-owners.yml - Apply resource owner assignments
apply-labels.yml - Deploy governance labels
apply-risk-rules.yml - Apply risk rules (SOD policies)
apply-admin-labels.yml - Auto-label admin entitlements
import-risk-rules.yml - Import risk rules from Okta

Validation:

validate-pr.yml - YAML syntax, security scanning
validate-label-mappings.yml - Label configuration validation

Python Scripts

Located in scripts/:

Import and Sync:

import_oig_resources.py - Import OIG resources from Okta API
sync_owner_mappings.py - Sync resource owners from Okta
sync_label_mappings.py - Sync governance labels from Okta
import_risk_rules.py - Import risk rules (SOD policies) from Okta

Apply:

apply_resource_owners.py - Apply owners to resources
apply_admin_labels.py - Auto-label admin entitlements
apply_labels_from_config.py - Deploy labels from config file
apply_risk_rules.py - Apply risk rules to Okta

AWS Backend Infrastructure

Located in aws-backend/:

S3 bucket for Terraform state
DynamoDB table for state locking
IAM roles for GitHub Actions OIDC
Complete setup guide

Benefits:

✅ Team collaboration without state conflicts
✅ State history and versioning for rollback
✅ Encryption at rest and in transit
✅ No long-lived AWS credentials in GitHub

See docs/AWS_BACKEND_SETUP.md for setup instructions.

AI-Assisted Code Generation

Located in ai-assisted/:

Quickly generate Terraform code for demos using AI:

Tier 1: Manual - Copy context and prompts to your AI assistant Tier 2: Automated - CLI tool with Gemini/GPT/Claude integration

# Example: Generate demo environment
cd ai-assisted
python generate.py --prompt "Create 5 marketing users and Salesforce app" \
  --provider gemini --output ../environments/mycompany/terraform/demo.tf

See ai-assisted/README.md for complete guide.

📋 Prerequisites

Required Software

Terraform >= 1.9.0
Python >= 3.9
Git (for version control)
GitHub CLI (optional, for workflow management)

Required Services

Okta Organization with Identity Governance enabled
GitHub Account with Actions enabled
AWS Account (for S3/DynamoDB state backend - optional but recommended)

Okta API Permissions

Your API token needs these scopes:

okta.groups.manage
okta.users.manage
okta.apps.manage
okta.governance.accessRequests.manage
okta.governance.accessReviews.manage
okta.governance.catalogs.manage

🔧 Initial Setup

1. Use This Template

Click the "Use this template" button at the top of this page, or:

gh repo create my-okta-gitops --template joevanhorn/okta-terraform-demo-template
cd my-okta-gitops

2. Set Up AWS Backend (Recommended)

cd aws-backend
terraform init
terraform apply

# Save the output - you'll need it for GitHub secrets
terraform output github_actions_role_arn

3. Configure GitHub Environment

Go to Settings → Environments and create your first environment:

Environment Name: MyCompany (matches your directory name)

Required Secrets:

OKTA_API_TOKEN - Okta API token with governance scopes
OKTA_ORG_NAME - Your Okta org name (e.g., dev-12345678)
OKTA_BASE_URL - Base URL (e.g., okta.com or oktapreview.com)

Repository Secret (for AWS):

AWS_ROLE_ARN - From terraform output above

4. Create Your First Environment

# Create directory structure
mkdir -p environments/mycompany/{terraform,imports,config}

# Copy template files
cp environments/myorg/terraform/provider.tf environments/mycompany/terraform/
cp environments/myorg/terraform/variables.tf environments/mycompany/terraform/
cp environments/myorg/config/*.json environments/mycompany/config/

# Update provider.tf with your backend key
# Change: key = "Okta-GitOps/production/terraform.tfstate"
# To:     key = "Okta-GitOps/mycompany/terraform.tfstate"

5. Import Resources from Okta

# Import all OIG resources from your Okta tenant
gh workflow run import-all-resources.yml \
  -f tenant_environment=MyCompany \
  -f update_terraform=true \
  -f commit_changes=true

6. Initialize and Apply

cd environments/mycompany/terraform
terraform init
terraform plan
terraform apply

🎉 You're now managing Okta with GitOps!

For detailed setup instructions, see TEMPLATE_SETUP.md.

🔄 Keeping Your Repository Updated

This template receives regular updates including new features, bug fixes, improved workflows, and enhanced documentation.

Automatic Updates (Recommended)

Use the built-in sync workflow:

One-time setup:

a. Create labels:
```
# Create labels for automated PRs
gh label create template-sync --description "Automated template sync pull request" --color "0366d6"
gh label create maintenance --description "Repository maintenance" --color "fbca04"
```
Or create via GitHub web UI: Issues → Labels → New label

b. Enable workflow PR permissions:
- Go to Settings → Actions → General
- Under "Workflow permissions": Select "Read and write permissions"
- Check: "Allow GitHub Actions to create and approve pull requests"
- Click "Save"
Enable the workflow:
- Go to Actions tab in your repository
- Find "Sync Template Updates" workflow
- Click "Enable workflow" if needed
Run manually anytime:
```
gh workflow run sync-template.yml
```
Or click "Run workflow" in the Actions tab
Review the PR:
- Workflow creates a PR with template updates
- Review changes in the PR
- Merge when ready

The workflow runs automatically:

🕐 Weekly on Sundays at 2 AM UTC
🔘 Manually via workflow dispatch
📦 Creates PR with all template updates
🔍 Shows exactly what changed

Manual Sync (Alternative)

If you prefer manual control:

# One-time setup: Add template as remote
git remote add template https://github.com/joevanhorn/okta-terraform-demo-template.git

# Sync updates anytime:
git fetch template
git checkout -b sync-template-updates
git merge template/main --allow-unrelated-histories
git push origin sync-template-updates

# Create PR via GitHub web UI or:
gh pr create --title "Sync template updates" --body "Updates from template repository"

Stay Notified

Watch this repository for updates:

Click "Watch" button (top right)
Select "Custom"
Enable "Releases"
Click "Apply"

You'll be notified when new features are released!

Recent Updates

v2.0.0 (2025-11-12):

✨ Added Gemini Gem support (Tier 3 AI-assisted generation)
📝 GitHub web UI integration guide
🔄 Automatic template sync workflow

See CHANGELOG.md for full history.

📚 Documentation

Comprehensive guides are available in the docs/ directory:

Getting Started

TEMPLATE_SETUP.md - Complete setup guide for new users
OIG_PREREQUISITES.md - Required Okta configuration
DIRECTORY_GUIDE.md - Repository structure explained

Workflows and Operations

docs/GITOPS_WORKFLOW.md - GitOps patterns and best practices
docs/WORKFLOWS.md - GitHub Actions workflow reference
docs/API_MANAGEMENT.md - Python scripts guide (1190+ lines)
docs/AWS_BACKEND_SETUP.md - S3 state backend setup

Troubleshooting and Reference

docs/LESSONS_LEARNED.md - Common issues and solutions
docs/TERRAFORMER_OIG_FAQ.md - Terraformer limitations
docs/TROUBLESHOOTING_ENTITLEMENT_BUNDLES.md - Bundle-specific issues

Demo Building

DEMO_GUIDE.md - Build demos with templates, AI, or manually (30-60 min)
TERRAFORM-BASICS.md - Terraform resource reference and examples

AI-Assisted Development

ai-assisted/README.md - AI code generation guide

🤝 Common Tasks

Import Resources from Okta

gh workflow run import-all-resources.yml \
  -f tenant_environment=MyCompany \
  -f update_terraform=true

Plan Terraform Changes

cd environments/mycompany/terraform
terraform plan

Apply Changes with Approval

# Trigger manual apply workflow (requires approval)
gh workflow run terraform-apply-with-approval.yml \
  -f environment=mycompany

Manage Resource Owners

# Sync from Okta
python3 scripts/sync_owner_mappings.py \
  --output environments/mycompany/config/owner_mappings.json

# Apply to Okta
gh workflow run apply-owners.yml \
  -f environment=mycompany \
  -f dry_run=false

Manage Governance Labels

# Sync from Okta
python3 scripts/sync_label_mappings.py \
  --output environments/mycompany/config/label_mappings.json

# Apply to Okta
gh workflow run apply-labels-from-config.yml \
  -f environment=mycompany \
  -f dry_run=false

Auto-Label Admin Entitlements

gh workflow run apply-admin-labels.yml \
  -f environment=mycompany \
  -f dry_run=false

🔍 Working Example

Want to see this template in action with a real, configured environment?

👉 okta-terraform-complete-demo

This working repository demonstrates:

Fully configured MyOrg demo environment
31 entitlement bundles
200 access review campaigns
Complete governance label setup
Resource owner assignments
Real-world workflow examples

🧩 Architecture Patterns

Three-Layer Resource Management

Understanding what goes where is critical:

Layer 1: Terraform Provider (Full CRUD)

Standard Okta resources: users, groups, apps, policies
OIG resources: entitlement bundles, access reviews, approval sequences
Managed in environments/{env}/terraform/*.tf files

Layer 2: Python API Scripts (Read/Write)

Resource Owners (not in Terraform provider yet)
Governance Labels (not in Terraform provider yet)
Managed in environments/{env}/config/*.json files

Layer 3: Manual Management (Okta Admin UI)

Entitlement assignments (which users/groups have bundles)
Access review decisions and approvals
Certain advanced OIG configurations

State Management

Each environment maintains independent state:

s3://your-bucket/
└── Okta-GitOps/
    ├── mycompany/terraform.tfstate
    ├── production/terraform.tfstate
    ├── staging/terraform.tfstate
    └── development/terraform.tfstate

Key Features:

State locking via DynamoDB
AES256 encryption at rest
Versioning enabled for rollback
GitHub Actions authentication via AWS OIDC (no long-lived credentials)

🛡️ Security Best Practices

Secrets Management

✅ Use GitHub Environments for Okta credentials
✅ Use AWS OIDC for state backend (no long-lived AWS keys)
✅ Rotate API tokens regularly (every 90 days)
✅ Use least-privilege scopes
✅ Never commit secrets to Git

Change Management

✅ All changes via pull requests
✅ Required approvals for production
✅ Automated validation on PRs
✅ Manual approval gates for applies
✅ Complete audit trail in Git

State Protection

✅ State stored in encrypted S3
✅ DynamoDB locking prevents conflicts
✅ State versioning for rollback
✅ Never commit state files to Git

📊 Project Status

This template is actively maintained and used in production environments.

Current Capabilities

✅ Full OIG resource management via Terraform
✅ Resource owners and labels via Python API
✅ Multi-tenant environment support
✅ GitHub Actions automation
✅ AWS S3/DynamoDB state backend
✅ AI-assisted code generation
✅ Comprehensive documentation
✅ Working examples and demos

Known Limitations

⚠️ Terraformer doesn't support OIG resources (use Python import scripts)
⚠️ Principal assignments must be managed in Okta UI
⚠️ Some OIG features still in development (check provider docs)

🤝 Contributing

Found a bug or have a suggestion? Please:

Check existing issues
Create a new issue with details
Or submit a pull request!

📄 License

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

🙏 Acknowledgments

Built with:

📞 Support

Documentation: See docs/ directory
Issues: GitHub Issues
Discussions: GitHub Discussions
Working Example: okta-terraform-complete-demo

Ready to get started? → TEMPLATE_SETUP.md

Name		Name	Last commit message	Last commit date
Latest commit History 91 Commits
.github		.github
ai-assisted		ai-assisted
aws-backend		aws-backend
docs		docs
environments		environments
examples/oag-demo-app		examples/oag-demo-app
scripts		scripts
testing		testing
upcoming-releases		upcoming-releases
webhook-handler		webhook-handler
.gitignore		.gitignore
CHANGELOG.md		CHANGELOG.md
CLAUDE.md		CLAUDE.md
DEMO_GUIDE.md		DEMO_GUIDE.md
GITHUB-BASIC.md		GITHUB-BASIC.md
GITHUB-GITOPS.md		GITHUB-GITOPS.md
LICENSE		LICENSE
LOCAL-USAGE.md		LOCAL-USAGE.md
OIG_PREREQUISITES.md		OIG_PREREQUISITES.md
README.md		README.md
SECURITY.md		SECURITY.md
TERRAFORM-BASICS.md		TERRAFORM-BASICS.md
TROUBLESHOOTING.md		TROUBLESHOOTING.md
requirements.txt		requirements.txt

License

joevanhorn/okta-terraform-demo-template

Folders and files

Latest commit

History

Repository files navigation

Okta Terraform GitOps Template

🧭 Choose Your Path

Recommended Learning Path

🚀 Full GitOps Setup

⚡ Ready for Team Collaboration?

🤖 Automated Setup Script

📚 Advanced Topics

📖 Documentation

What's Included

🚨 Important: Terraformer Limitations

🏗️ Environment-Based Architecture

📝 Terraform Starter Templates

🚀 QUICKSTART_DEMO.tf.example - Ready in 2 Minutes

📚 RESOURCE_EXAMPLES.tf - Comprehensive Reference

📖 README.md - Template Guide

🖥️ Active Directory Infrastructure (Optional)

What's Included

Quick Deploy

What Gets Configured Automatically

Next Steps After Deployment

Cost Estimate

🎯 Okta Identity Governance Features

Terraform Provider Resources

Python API Management

🏗️ GitOps Workflow

For Terraform Resources

For Labels and Owners (Python API)

📦 Repository Components

GitHub Actions Workflows

Python Scripts

AWS Backend Infrastructure

AI-Assisted Code Generation

📋 Prerequisites

Required Software

Required Services

Okta API Permissions

🔧 Initial Setup

1. Use This Template

2. Set Up AWS Backend (Recommended)

3. Configure GitHub Environment

4. Create Your First Environment

5. Import Resources from Okta

6. Initialize and Apply

🔄 Keeping Your Repository Updated

Automatic Updates (Recommended)

Manual Sync (Alternative)

Stay Notified

Recent Updates

📚 Documentation

Getting Started

Workflows and Operations

Troubleshooting and Reference

Demo Building

AI-Assisted Development

🤝 Common Tasks

Import Resources from Okta

Plan Terraform Changes

Apply Changes with Approval

Manage Resource Owners

Manage Governance Labels

Auto-Label Admin Entitlements

🔍 Working Example

🧩 Architecture Patterns

Three-Layer Resource Management

State Management

🛡️ Security Best Practices

Secrets Management

Change Management

State Protection

📊 Project Status

Current Capabilities

Known Limitations

🤝 Contributing

📄 License

Packages