Manage Casdoor with Terraform
This guide explains how to manage the objects of a Casdoor server as code with the official Casdoor Terraform provider, so that you can review, version, and apply the configuration to several environments.
Learning outcomes
- Configure the Casdoor Terraform provider.
- Create organizations, applications, users, and other objects from a Terraform configuration.
- Bring objects that already exist under Terraform.
- Understand which fields Terraform writes and which it leaves alone.
What you need
- Terraform or OpenTofu
- A running Casdoor instance
- The client ID and client secret of a Casdoor application. To manage every organization, use an application of the
built-inorganization, such asapp-built-in.
About the provider
- Terraform Registry:
casdoor/casdoor - Source code: casdoor/terraform-provider-casdoor
The provider calls the Casdoor API as an application, with the application's client ID and client secret. It supports the following resources:
| Resource | Casdoor object | Import ID |
|---|---|---|
casdoor_organization | Organization | name |
casdoor_application | Application, with its providers | name |
casdoor_user | User | organization/name |
casdoor_provider | Provider | owner/name |
casdoor_cert | Cert | owner/name |
casdoor_role | Role | organization/name |
casdoor_permission | Permission | organization/name |
casdoor_group | Group | organization/name |
The owner of a provider or a cert is admin for a global object that all organizations share, or the name of the organization that owns it.
Configure the provider
-
In the Casdoor admin console, go to Applications, open
app-built-in, and copy its Client ID and Client secret. -
Declare the provider in your Terraform configuration:
terraform {
required_providers {
casdoor = {
source = "casdoor/casdoor"
}
}
}
provider "casdoor" {
endpoint = "https://door.casdoor.com"
client_id = var.casdoor_client_id
client_secret = var.casdoor_client_secret
}To keep the secret out of the configuration, omit the settings and pass them as environment variables instead:
export CASDOOR_ENDPOINT=https://door.casdoor.com
export CASDOOR_CLIENT_ID=<client ID>
export CASDOOR_CLIENT_SECRET=<client secret>
terraform init
Create objects
-
Add resources to the configuration. The following example creates an organization, a cert, a GitHub identity provider, an application that uses both, a user, a role, and a permission:
resource "casdoor_organization" "acme" {
name = "acme"
display_name = "Acme"
password_type = "bcrypt"
country_codes = ["US"]
}
resource "casdoor_cert" "acme" {
name = "cert-acme"
crypto_algorithm = "RS256"
bit_size = 4096
expire_in_years = 20
}
resource "casdoor_provider" "github" {
name = "provider-acme-github"
category = "OAuth"
type = "GitHub"
client_id = var.github_client_id
client_secret = var.github_client_secret
}
resource "casdoor_application" "portal" {
name = "app-acme-portal"
organization = casdoor_organization.acme.name
cert = casdoor_cert.acme.name
redirect_uris = ["https://portal.acme.example.com/callback"]
providers = [
{
name = casdoor_provider.github.name
owner = "admin"
can_sign_in = true
can_sign_up = true
},
]
}
resource "casdoor_user" "alice" {
owner = casdoor_organization.acme.name
name = "alice"
email = "alice@acme.example.com"
password = var.alice_password
}
resource "casdoor_role" "admins" {
owner = casdoor_organization.acme.name
name = "admins"
users = ["acme/alice"]
}
resource "casdoor_permission" "portal_admin" {
owner = casdoor_organization.acme.name
name = "portal-admin"
roles = ["acme/admins"]
resource_type = "Application"
resources = [casdoor_application.portal.name]
actions = ["Read", "Write"]
effect = "Allow"
}
output "portal_client_id" {
value = casdoor_application.portal.client_id
} -
Preview the changes:
terraform plan -
Apply the changes:
terraform apply
Casdoor generates the client ID and client secret of the application. The resource exports them as client_id and client_secret, which is marked sensitive, so that you can pass them to the application that signs users in with Casdoor.
Import existing objects
To bring an object that was created in the admin console under Terraform, run terraform import with the import ID from the resource table:
terraform import casdoor_organization.acme acme
terraform import casdoor_application.portal app-acme-portal
terraform import casdoor_user.alice acme/alice
terraform import casdoor_provider.github admin/provider-acme-github
After an import, the first terraform apply writes the password and client_secret attributes once, because Terraform can't read their current values from Casdoor.
Understand which fields Terraform writes
- Attributes in the configuration: Terraform writes them to Casdoor.
- Fields that the configuration doesn't set: They keep the values that they have in Casdoor. This includes fields that the provider doesn't support yet. A resource can therefore manage part of an object that you also edit in the admin console.
- Attributes that you remove from the configuration: They keep their last value in Casdoor.
- Passwords and secrets: Casdoor never returns values such as the
passwordof a user or theclient_secretof a provider. Terraform doesn't detect changes that are made to them outside Terraform.
See also
- Initialize and manage data with a file: Load objects from a file when a new Casdoor server starts.
- Run Casdoor with the Kubernetes operator: Declare organizations and applications as Kubernetes resources.
- Call the Casdoor API
- Casdoor plugins