Skip to content

README.md

Latest commit

 

History

History
263 lines (203 loc) · 6.02 KB

README.md

File metadata and controls

263 lines (203 loc) · 6.02 KB

WorkOS Terraform Provider

Terraform provider for managing WorkOS resources including organizations, users, organization memberships, roles, and permissions.

Requirements

Installation

From Terraform Registry (Recommended)

terraform {
  required_providers {
    workos = {
      source  = "osodevops/workos"
      version = "~> 1.0"
    }
  }
}

provider "workos" {
  api_key = var.workos_api_key
}

Local Development

# Clone the repository
git clone https://github.com/osodevops/terraform-provider-workos.git
cd terraform-provider-workos

# Build the provider
make build

# Install locally
make install

Usage

Provider Configuration

provider "workos" {
  api_key   = var.workos_api_key   # Or set WORKOS_API_KEY env var
  client_id = var.workos_client_id # Or set WORKOS_CLIENT_ID env var (optional)
  base_url  = "https://api.workos.com" # Optional, defaults to production API
}

Managing Organizations

resource "workos_organization" "example" {
  name        = "Acme Corporation"
  external_id = "acme-corp-123"
  domains     = ["acme.com", "acmecorp.com"]

  metadata = {
    tier   = "enterprise"
    region = "us-east-1"
  }
}

Managing Users

resource "workos_user" "admin" {
  email          = "admin@example.com"
  first_name     = "Admin"
  last_name      = "User"
  external_id    = "admin-001"
  email_verified = true

  metadata = {
    department = "Engineering"
    title      = "Platform Lead"
  }
}

resource "workos_organization_membership" "admin" {
  user_id         = workos_user.admin.id
  organization_id = workos_organization.example.id
  role_slug       = "admin"
}

Managing Roles

resource "workos_organization_role" "billing_admin" {
  organization_id = workos_organization.example.id
  slug            = "org-billing-admin"
  name            = "Billing Admin"
  description     = "Can manage billing and invoices"
}

resource "workos_organization_role" "viewer" {
  organization_id = workos_organization.example.id
  slug            = "org-viewer"
  name            = "Viewer"
}

Managing Permissions

resource "workos_permission" "billing_read" {
  slug        = "billing:read"
  name        = "Read Billing"
  description = "Allows reading billing data"
}

resource "workos_permission" "billing_write" {
  slug        = "billing:write"
  name        = "Write Billing"
  description = "Allows modifying billing data"
}

Assigning Permissions to Organization Roles

resource "workos_organization_role_permission" "billing_admin_read" {
  organization_id = workos_organization.example.id
  role_slug       = workos_organization_role.billing_admin.slug
  permission      = workos_permission.billing_read.slug
}

resource "workos_organization_role_permission" "billing_admin_write" {
  organization_id = workos_organization.example.id
  role_slug       = workos_organization_role.billing_admin.slug
  permission      = workos_permission.billing_write.slug
}

Data Sources

# Look up organization by ID
data "workos_organization" "by_id" {
  id = "org_01HXYZ..."
}

# Look up organization by domain
data "workos_organization" "by_domain" {
  domain = "acme.com"
}

# Look up organization by external ID
data "workos_organization" "by_external_id" {
  external_id = "acme-corp-123"
}

# Look up user by email
data "workos_user" "john" {
  email = "john@example.com"
}

# Look up user by external ID
data "workos_user" "by_ext" {
  external_id = "admin-001"
}

# Look up organization role by slug
data "workos_organization_role" "billing" {
  organization_id = workos_organization.example.id
  slug            = "org-billing-admin"
}

# Look up permission by slug
data "workos_permission" "billing_read" {
  slug = "billing:read"
}

Resources

Resource Description
workos_organization Manages WorkOS organizations
workos_user Manages AuthKit users
workos_organization_membership Manages user-organization memberships
workos_organization_role Manages organization authorization roles
workos_permission Manages environment-level permissions
workos_organization_role_permission Assigns a permission to an organization role

Data Sources

Data Source Description
workos_organization Retrieves organization by ID, domain, or external ID
workos_connection Retrieves SSO connection by ID or org/type (read-only)
workos_directory Retrieves directory by ID or organization (read-only)
workos_directory_user Retrieves directory-synced user
workos_directory_group Retrieves directory-synced group
workos_user Retrieves AuthKit user by ID, email, or external ID
workos_organization_role Retrieves organization role by slug or ID
workos_permission Retrieves permission by slug

Development

Building

make build

Testing

# Unit tests
make test

# Acceptance tests (requires WorkOS API credentials)
export WORKOS_API_KEY="sk_test_..."
export WORKOS_CLIENT_ID="client_..."
make testacc

Generating Documentation

make docs

Linting

make lint

Contributing

  1. Fork the repository
  2. Create a feature branch (git checkout -b feature/my-feature)
  3. Commit your changes (git commit -am 'Add new feature')
  4. Push to the branch (git push origin feature/my-feature)
  5. Open a Pull Request

Commit Message Format

feat(resource): add new attribute support
fix(organization): handle domain validation
docs(readme): update installation instructions
test(connection): add acceptance tests

License

MPL-2.0 - See LICENSE for details.

Support