> ## Documentation Index
> Fetch the complete documentation index at: https://docs.bytebase.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Manage Users and Groups with Terraform

This tutorial is part of the **Bytebase Terraform Provider** series:

* Part 1: [Manage Environments with Terraform](/tutorials/manage-environments-with-terraform) - Set up environments with policies
* Part 2: [Manage Databases with Terraform](/tutorials/manage-databases-with-terraform) - Register database instances
* Part 3: [Manage Projects with Terraform](/tutorials/manage-projects-with-terraform) - Organize databases into projects
* Part 4: [Manage Bytebase Settings with Terraform](/tutorials/manage-general-settings-with-terraform) - Configure workspace profile and approval policies
* Part 5: [Manage SQL Review Rules with Terraform](/tutorials/manage-sql-review-rules-with-terraform) - Define SQL review policies
* Part 6: Manage Users and Groups with Terraform 👈
* Part 7: [Manage Database Access Control with Terraform](/tutorials/manage-database-access-control-with-terraform) - Grant database permissions
* Part 8: [Manage Data Masking with Terraform](/tutorials/manage-data-masking-with-terraform) - Protect sensitive data

<Card icon="code-xml" cta="View sample code" href="https://github.com/bytebase/terraform-provider-bytebase/tree/main/tutorials">
  This tutorial series uses separate Terraform files for better organization. Files are numbered by tutorial part and sub-step (e.g., [1-1-env-setting.tf](https://github.com/bytebase/terraform-provider-bytebase/blob/main/tutorials/1-1-env-setting.tf), [1-2-env-policy-rollout.tf](https://github.com/bytebase/terraform-provider-bytebase/blob/main/tutorials/1-2-env-policy-rollout.tf) for Part 1, [2-instances.tf](https://github.com/bytebase/terraform-provider-bytebase/blob/main/tutorials/2-instances.tf) for Part 2, etc.). Terraform automatically handles dependencies between files.
</Card>

## What You'll Learn

* **Create** users, service accounts, and workload identities for team members and automation
* **Organize** users into groups for easier management
* **Understand** the difference between users, service accounts, and workload identities
* **Prepare** for setting up permissions in the next tutorial

## Prerequisites

Before starting this tutorial, ensure you have:

* Completed [Part 5: Manage SQL Review Rules with Terraform](/tutorials/manage-sql-review-rules-with-terraform)
* Bytebase running with service account configured
* Your Terraform files from the previous tutorials

## Setup

From the previous tutorials, you should have:

* Bytebase workspaces and projects configured
* Workspace settings and approval flows set up
* Service account with `Workspace Admin` role

## Understanding User Management in Bytebase

Bytebase adopts Identity and Access Management (IAM) system with:

* **Users**: Individual accounts for team members
* **Service Accounts**: Automated accounts for API/Terraform access (separate resource from users)
* **Workload Identities**: Federated identities for CI/CD systems like GitHub Actions (no secret to manage)
* **Groups**: Collections of users for easier permission management

## Configure Users, Service Accounts, and Groups

### Step 1 - Create Users, Service Account, and Workload Identity

| Resource                     | Provider documentation                                                                                                            |
| ---------------------------- | --------------------------------------------------------------------------------------------------------------------------------- |
| `bytebase_user`              | [bytebase\_user](https://registry.terraform.io/providers/bytebase/bytebase/latest/docs/resources/user)                            |
| `bytebase_service_account`   | [bytebase\_service\_account](https://registry.terraform.io/providers/bytebase/bytebase/latest/docs/resources/service_account)     |
| `bytebase_workload_identity` | [bytebase\_workload\_identity](https://registry.terraform.io/providers/bytebase/bytebase/latest/docs/resources/workload_identity) |

|             |                                                                                                          |
| ----------- | -------------------------------------------------------------------------------------------------------- |
| Sample file | [6-1-users.tf](https://github.com/bytebase/terraform-provider-bytebase/blob/main/tutorials/6-1-users.tf) |

Create `6-1-users.tf` to define your team structure:

```hcl 6-1-users.tf theme={null}
# Create users
resource "bytebase_user" "workspace_admin" {
  email = "admin@example.com"
  title = "Workspace Admin"
}

# Database administrators
resource "bytebase_user" "workspace_dba1" {
  email = "dba@example.com"
  title = "Database Administrator 1"
}

resource "bytebase_user" "workspace_dba2" {
  email = "dba2@example.com"
  title = "Database Administrator 2"
}

resource "bytebase_user" "dev1" {
  email = "dev1@example.com"
  title = "Developer 1"
}

resource "bytebase_user" "dev2" {
  email = "dev2@example.com"
  title = "Developer 2"
}

resource "bytebase_user" "dev3" {
  email = "dev3@example.com"
  title = "Developer 3"
}

resource "bytebase_user" "qa1" {
  email = "qa1@example.com"
  title = "QA Tester 1"
}

resource "bytebase_user" "qa2" {
  email = "qa2@example.com"
  title = "QA Tester 2"
}

# Service account for Terraform automation
resource "bytebase_service_account" "tf_service_account" {
  # parent defaults to the current workspace when omitted.
  service_account_id = "tf"
  title              = "Terraform Service Account"
}

# Workload identity for GitHub Actions CI/CD
resource "bytebase_workload_identity" "github_ci" {
  # parent defaults to the current workspace when omitted.
  workload_identity_id = "github-ci"
  title                = "GitHub CI"

  workload_identity_config {
    provider_type   = "GITHUB"
    subject_pattern = "repo:example/repo:ref:refs/heads/main"
  }
}
```

<Note>
  You created `tf@service.bytebase.com` manually in Part 1 to bootstrap the provider. The `bytebase_service_account` resource here adopts that existing account on first apply (you'll see a "Service account already exists" warning) — no manual import needed.
</Note>

### Step 2 - Apply User Configuration

```bash theme={null}
terraform plan
terraform apply
```

### Step 3 - Create Groups

Groups simplify permission management by allowing you to assign roles to multiple users at once.

<Tip>
  Each group has an owner who can manage group membership. Regular members inherit permissions
  assigned to the group.
</Tip>

|                    |                                                                                                            |
| ------------------ | ---------------------------------------------------------------------------------------------------------- |
| Terraform resource | [bytebase\_group](https://registry.terraform.io/providers/bytebase/bytebase/latest/docs/resources/group)   |
| Sample file        | [6-2-groups.tf](https://github.com/bytebase/terraform-provider-bytebase/blob/main/tutorials/6-2-groups.tf) |

Add the following groups to your `6-2-groups.tf` file:

```hcl 6-2-groups.tf theme={null}
# Create groups
resource "bytebase_group" "developers" {
  email       = "developers@example.com"
  title       = "Developer Team"
  description = "Group for all developers"

  members {
    member = "users/${bytebase_user.dev1.email}"
    role   = "OWNER"
  }

  members {
    member = "users/${bytebase_user.dev2.email}"
    role   = "MEMBER"
  }

  members {
    member = "users/${bytebase_user.dev3.email}"
    role   = "MEMBER"
  }
}

resource "bytebase_group" "qa" {
  email       = "qa@example.com"
  title       = "QA Team"
  description = "Group for all QA testers"

  members {
    member = "users/${bytebase_user.qa1.email}"
    role   = "OWNER"
  }

  members {
    member = "users/${bytebase_user.qa2.email}"
    role   = "MEMBER"
  }
}
```

### Step 4 - Apply Complete Configuration

```bash theme={null}
terraform plan
terraform apply
```

### Step 5 - Verify in Bytebase

1. Go to **IAM & Admin > Users & Groups** to see all users:

   <img src="https://mintcdn.com/dbx/UWWiSACs47prwfdV/content/docs/tutorials/manage-database-access-control-with-terraform/bb-users.webp?fit=max&auto=format&n=UWWiSACs47prwfdV&q=85&s=67f2ff5df1cbf2553bf7f57a8cee40be" alt="users" width="3174" height="1686" data-path="content/docs/tutorials/manage-database-access-control-with-terraform/bb-users.webp" />

2. Click the **Groups** tab to verify groups:

   * **Developer Team**: 3 members (dev1 as owner, dev2 and dev3 as members)
   * **QA Team**: 2 members (qa1 as owner, qa2 as member)

   <img src="https://mintcdn.com/dbx/UWWiSACs47prwfdV/content/docs/tutorials/manage-database-access-control-with-terraform/bb-groups.webp?fit=max&auto=format&n=UWWiSACs47prwfdV&q=85&s=c58eae2a905b50b9afedfad6c09eac88" alt="groups" width="3164" height="1322" data-path="content/docs/tutorials/manage-database-access-control-with-terraform/bb-groups.webp" />

## Key Points

* **Resource Types**: Use `bytebase_user` for team members, `bytebase_service_account` for API/automation (returns a service key you can use as a Terraform `service_key`), and `bytebase_workload_identity` for secret-less federation (e.g., GitHub Actions OIDC)
* **Group Roles**: Each group has owners (manage membership) and members (inherit permissions)
* **Organization**: Groups simplify permission management - assign roles to groups instead of individual users

<Card title="Part 7: Manage Database Access Control with Terraform" icon="arrow-right" href="/tutorials/manage-database-access-control-with-terraform" horizontal />