homelab/terraform/authentik/README.md

# Authentik Terraform Configuration

Root Terraform configuration for managing Authentik SSO — applications (OAuth2/OIDC, Proxy, SAML), groups, outposts, flows, certificates, and property mappings.

State is stored in Terraform Cloud (organization `ultradesu`, workspace `Authentik`).

## Structure

```
.
├── main.tf                      # Resources: groups, outposts, policy bindings, module calls
├── variables.tf                 # Input variable definitions
├── outputs.tf                   # Outputs (app details, groups, flows, wiki data)
├── providers.tf                 # Authentik provider (goauthentik/authentik 2025.12.1)
├── state.tf                     # Terraform Cloud backend
├── terraform.tfvars             # General settings: authentik_url, outposts, flows, tags
├── oauth2-apps.auto.tfvars      # OAuth2/OIDC application definitions
├── proxy-apps.auto.tfvars       # Proxy application definitions
├── groups.auto.tfvars           # Group definitions
└── modules/
    ├── oauth-provider/          # OAuth2/OIDC provider + application
    ├── proxy-provider/          # Proxy provider + application
    └── saml-provider/           # SAML provider + application
```

## Usage

```bash
# Set the API token
export TF_VAR_authentik_token="..."

terraform init
terraform plan
terraform apply
```

All `*.auto.tfvars` files are loaded automatically — no `-var-file` flags needed.

## Adding applications

OAuth2/OIDC — add to `oauth2-apps.auto.tfvars`:

```hcl
oauth_applications = {
  "my-app" = {
    name          = "My App"
    slug          = "my-app"
    group         = "Tools"
    redirect_uris = ["https://my-app.example.com/callback"]
    create_group  = true
    access_groups = ["admins"]
  }
}
```

Proxy — add to `proxy-apps.auto.tfvars`:

```hcl
proxy_applications = {
  "my-proxy" = {
    name          = "My Proxy"
    slug          = "my-proxy"
    group         = "Tools"
    external_host = "https://my-proxy.example.com"
    internal_host = "http://my-service.namespace.svc:80"
    outpost       = "kubernetes-outpost"
    create_group  = true
    access_groups = ["admins"]
  }
}
```

## CI/CD

Managed via Gitea Actions (`.gitea/workflows/authentik-apps.yaml`). Runs `terraform apply` on push to `main` when files in `terraform/authentik/` change. Also generates a wiki page with the applications list.

## Requirements

- Terraform >= 1.0
- goauthentik/authentik provider 2025.12.1
- Authentik API token with admin permissions