Identity Integration Architecture

How users, groups, and access flow across Tractorbeam systems.

Overview

┌───────────────────────────────────────────────────────────────────────────────────┐
│                              OKTA (Identity Provider)                             │
│                              Source of Truth for:                                 │
│                              • Users • Groups • MFA                               │
└───────────────────────────────────────────────────────────────────────────────────┘
         │                          │                          │
         │ SCIM                     │ SAML + Team Sync         │ SCIM
         ▼                          ▼                          ▼
┌─────────────────┐      ┌─────────────────────┐      ┌─────────────────┐
│ Google Workspace│      │       GitHub        │      │    Tailscale    │
│                 │      │                     │      │                 │
│ • User accounts │      │ • User auth (SSO)   │      │ • User auth     │
│ • Email/Calendar│      │ • Teams from groups │      │ • ACL tags from │
│                 │      │                     │      │   groups        │
└─────────────────┘      └─────────────────────┘      └─────────────────┘
                                    │
                                    │ OIDC
                                    ▼
                         ┌─────────────────────┐
                         │       AWS SSO       │
                         │                     │
                         │ • User auth         │
                         │ • Permission sets   │
                         │   from groups       │
                         └─────────────────────┘


┌───────────────────────────────────────────────────────────────────────────────────┐
│                        GOOGLE GROUPS (Distribution Lists)                         │
│                     Separate from identity - for email routing                    │
│                                                                                   │
│   audit@ log-archive@ security@ ops@ billing@ alerts@ engineering@               │
└───────────────────────────────────────────────────────────────────────────────────┘

Okta Groups → System Mapping

Functional Groups

Okta Group	GitHub Team	Tailscale Tag	AWS SSO Permission Set
Employees	employees	tag:employees	—
Contractors	contractors	tag:contractors	—
Engineering	engineering	tag:engineering	PowerUserAccess (workloads+infra+sandbox)
Security	security	tag:security	SecurityAudit (all accounts)
Platform-Admins	platform-admins	tag:platform-admins	AdministratorAccess (all)

Per-Account AWS Groups

Okta Group	Purpose	AWS SSO Permission Set
AWS-User-	Team access to account	PowerUserAccess
AWS-Admin-	Root email (Platform-Admins)	—
AWS-ReadOnly-	Read-only investigation	ReadOnlyAccess
AWS-Sandbox-	Sandbox access	PowerUserAccess

Project Groups

Okta Group	GitHub Team	AWS SSO
Project-	project-{name}	—

Project groups scope repo access and future K8s namespaces. They do NOT drive SSO assignments.

Google Groups

Email groups for notifications. All groups allow external posting. Aliases are defined in data/groups.json and data/accounts.json, managed by Terraform (google-workspace/).

Google Group	Purpose	Typical Members	Aliases
platform-admins@	Platform team, ops alerts	Platform team	ops@, alerts@
accounting@	Finance notifications, invoices	Finance team	billing@, finance@
support@	Customer support	Support team	help@
careers@	Job applications	HR/Recruiting	jobs@
engineering@	Engineering team comms	Engineering team
security@	Security alerts (GuardDuty, etc.)	Security team
aws-admin-tractorbeam-ai@	Mgmt account root email	Platform team	aws-tractorbeam-ai@, aws@
aws-admin-audit@	Audit account root email	Platform team	aws-audit@, audit@
aws-admin-log-archive@	Log Archive account root	Platform team	aws-log-archive@, log-archive@
aws-admin-shared-services@	Shared Services account root	Platform team	aws-shared-services@
aws-admin-production@	Production account root	Platform team	aws-production@
aws-admin-nonprod@	Nonprod account root	Platform team	aws-nonprod@
aws-admin-carlyle@	Carlyle account root	Platform team	aws-carlyle@

Terraform Module Responsibilities

okta/

• Defines Okta groups (source of truth)
• Configures Okta apps (GitHub, AWS SSO, Tailscale)
• Sets MFA policies
• Creates group rules (Platform-Admins → AWS-Admin-* and AWS-Sandbox-*)

google-workspace/

• Manages Google Groups settings (posting rules, visibility)
• Manages group email aliases (defined in data/groups.json)
• Does NOT manage users (come from Okta SCIM)
• Does NOT create groups (come from Okta SCIM Push Groups)

github/

• Organization settings and security policies
• Creates teams (from data/groups.json where github_team: true and data/projects.json)
• Team membership synced from Okta via team sync
• Repository rulesets

Team sync setup (one-time per team):

1. Terraform creates the team
2. Link to Okta group: Team Settings → Sync group → Select Okta group
3. Membership syncs automatically

aws/modules/tailscale/

• ACL policy (references Okta group tags)
• Does NOT manage users (come from Okta SCIM)

aws/

• AWS Organizations, accounts, SCPs
• References Google Groups for account emails
• AWS SSO configured via Okta

Adding a New User

1. Create user in Okta
2. Assign to appropriate groups
3. User automatically provisioned to:
   • Google Workspace (email)
   • GitHub (if assigned to app)
   • Tailscale (if assigned to app)
   • AWS SSO (if assigned to app)

Adding a New Team/Group

1. Add group to data/groups.json (set github_team, google_group flags as needed)
2. Apply Okta Terraform (cd okta && terraform apply)
3. Apply GitHub Terraform if github_team: true (cd github && terraform apply)
4. Link GitHub team to Okta group (one-time manual step per team)
5. Group automatically syncs to:
   • GitHub as a team (via SAML team sync)
   • Tailscale as ACL tag (via SCIM)
   • AWS SSO as group (via SCIM)

See Teams & Groups for detailed instructions.

Adding a New Distribution List

1. Add to data/groups.json with "google_group": true (and optional aliases)
2. Apply Google Workspace Terraform (cd google-workspace && terraform apply)
3. Reference in other configs (AWS account emails, notification targets)

AWS account root email groups are auto-generated from data/accounts.json.

Email Flow Examples

AWS Security Alert

GuardDuty finding
    └─► SNS topic
        └─► security@tractorbeam.ai (Google Group)
            └─► Members' individual Gmail

AWS Budget Alert

Budget threshold exceeded
    └─► alerts@tractorbeam.ai (Google Group)
        └─► Members' individual Gmail

GitHub Team Notification

@tractorbeam/engineering mentioned
    └─► Okta Engineering group members' GitHub notifications