Skip to content

Commit 52ec231

Browse files
KT-DoanKT-Doan
authored
Merge pull request #42 from ory/docs/improve-examples
docs: fix broken examples and improve documentation coverage
2 parents b5008a5 + 4941eca commit 52ec231

File tree

21 files changed

+452
-34
lines changed

21 files changed

+452
-34
lines changed

‎docs/resources/action.md‎

Lines changed: 16 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -57,6 +57,22 @@ resource "ory_action" "sync_verified" {
5757
url = "https://api.example.com/webhooks/user-verified"
5858
method = "POST"
5959
}
60+
61+
# Post-registration enrichment (parse response to modify identity)
62+
resource "ory_action" "enrich_identity" {
63+
flow = "registration"
64+
timing = "after"
65+
auth_method = "password"
66+
url = "https://api.example.com/webhooks/enrich"
67+
method = "POST"
68+
response_parse = true # Parse the webhook response to update identity traits
69+
body = <<-JSONNET
70+
function(ctx) {
71+
identity_id: ctx.identity.id,
72+
email: ctx.identity.traits.email
73+
}
74+
JSONNET
75+
}
6076
```
6177

6278
## Authentication Methods

‎docs/resources/email_template.md‎

Lines changed: 25 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -148,6 +148,31 @@ resource "ory_email_template" "login_code" {
148148
This code expires in 15 minutes.
149149
TEXT
150150
}
151+
152+
# Registration code email
153+
resource "ory_email_template" "registration_code" {
154+
template_type = "registration_code_valid"
155+
subject = "Complete your registration"
156+
157+
body_html = <<-HTML
158+
<!DOCTYPE html>
159+
<html>
160+
<body>
161+
<h1>Welcome!</h1>
162+
<p>Your registration code is: <strong>{{ .RegistrationCode }}</strong></p>
163+
<p>Enter this code to complete your account setup.</p>
164+
</body>
165+
</html>
166+
HTML
167+
168+
body_plaintext = <<-TEXT
169+
Welcome!
170+
171+
Your registration code is: {{ .RegistrationCode }}
172+
173+
Enter this code to complete your account setup.
174+
TEXT
175+
}
151176
```
152177

153178
## Import

‎docs/resources/identity_schema.md‎

Lines changed: 2 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -64,7 +64,8 @@ Identity schemas use the `ory.sh/kratos` JSON Schema extension to configure auth
6464
```terraform
6565
# Customer identity schema with email and name
6666
resource "ory_identity_schema" "customer" {
67-
name = "customer_v1"
67+
schema_id = "customer_v1"
68+
set_default = true
6869
schema = jsonencode({
6970
"$id" = "https://example.com/customer.schema.json"
7071
"$schema" = "http://json-schema.org/draft-07/schema#"

‎docs/resources/json_web_key_set.md‎

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -47,20 +47,23 @@ Most configurations only need `use = "sig"`.
4747
# RSA signing key set
4848
resource "ory_json_web_key_set" "signing" {
4949
set_id = "token-signing-keys"
50+
key_id = "rsa-sig-1"
5051
algorithm = "RS256"
5152
use = "sig"
5253
}
5354
5455
# ECDSA signing key set (smaller, faster)
5556
resource "ory_json_web_key_set" "ecdsa_signing" {
5657
set_id = "ecdsa-signing-keys"
58+
key_id = "ec-sig-1"
5759
algorithm = "ES256"
5860
use = "sig"
5961
}
6062
6163
# Encryption key set
6264
resource "ory_json_web_key_set" "encryption" {
6365
set_id = "encryption-keys"
66+
key_id = "rsa-enc-1"
6467
algorithm = "RS256"
6568
use = "enc"
6669
}

‎docs/resources/oauth2_client.md‎

Lines changed: 40 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -22,6 +22,12 @@ resource "ory_oauth2_client" "api_service" {
2222
grant_types = ["client_credentials"]
2323
token_endpoint_auth_method = "client_secret_post"
2424
scope = "read write admin"
25+
audience = ["https://api.example.com"]
26+
access_token_strategy = "jwt"
27+
contacts = ["api-team@example.com"]
28+
29+
# Custom token lifespans for this client
30+
client_credentials_grant_access_token_lifespan = "30m"
2531
}
2632
2733
# Web application (Authorization Code flow) with OIDC logout and metadata
@@ -37,21 +43,43 @@ resource "ory_oauth2_client" "web_app" {
3743
token_endpoint_auth_method = "client_secret_basic"
3844
scope = "openid profile email offline_access"
3945
46+
# First-party app: skip consent and logout consent screens
47+
skip_consent = true
48+
skip_logout_consent = true
49+
subject_type = "pairwise"
50+
contacts = ["web-team@example.com"]
51+
4052
# Client metadata URIs
4153
client_uri = "https://app.example.com"
4254
logo_uri = "https://app.example.com/logo.png"
4355
policy_uri = "https://app.example.com/privacy"
4456
tos_uri = "https://app.example.com/terms"
4557
46-
# OIDC logout
47-
frontchannel_logout_uri = "https://app.example.com/logout/frontchannel"
48-
backchannel_logout_uri = "https://app.example.com/logout/backchannel"
58+
# OIDC logout with session notifications
59+
frontchannel_logout_uri = "https://app.example.com/logout/frontchannel"
60+
frontchannel_logout_session_required = true
61+
backchannel_logout_uri = "https://app.example.com/logout/backchannel"
62+
backchannel_logout_session_required = true
4963
5064
# Per-client CORS
5165
allowed_cors_origins = [
5266
"https://app.example.com",
5367
"https://admin.example.com"
5468
]
69+
70+
# Per-grant token lifespans
71+
authorization_code_grant_access_token_lifespan = "1h"
72+
authorization_code_grant_id_token_lifespan = "1h"
73+
authorization_code_grant_refresh_token_lifespan = "720h"
74+
refresh_token_grant_access_token_lifespan = "1h"
75+
refresh_token_grant_id_token_lifespan = "1h"
76+
refresh_token_grant_refresh_token_lifespan = "720h"
77+
78+
# Custom metadata
79+
metadata = jsonencode({
80+
department = "engineering"
81+
tier = "internal"
82+
})
5583
}
5684
5785
# Client with custom token lifespans
@@ -81,6 +109,15 @@ resource "ory_oauth2_client" "spa" {
81109
scope = "openid profile email"
82110
}
83111
112+
# Device Authorization flow (CLI tools, IoT devices)
113+
resource "ory_oauth2_client" "cli_tool" {
114+
client_name = "CLI Tool"
115+
grant_types = ["urn:ietf:params:oauth:grant-type:device_code", "refresh_token"]
116+
response_types = ["code"]
117+
token_endpoint_auth_method = "none"
118+
scope = "openid offline_access"
119+
}
120+
84121
output "api_service_client_id" {
85122
value = ory_oauth2_client.api_service.client_id
86123
}

‎docs/resources/organization.md‎

Lines changed: 22 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -18,12 +18,33 @@ Organizations represent tenants in a multi-tenant application. They can have ass
1818
## Example Usage
1919

2020
```terraform
21-
# Create an organization for multi-tenancy
21+
# Create an organization for multi-tenancy (B2B SaaS)
2222
resource "ory_organization" "acme" {
2323
label = "Acme Corporation"
2424
domains = ["acme.com", "acme.io"]
2525
}
2626
27+
# Multiple tenant organizations
28+
resource "ory_organization" "globex" {
29+
label = "Globex Corporation"
30+
domains = ["globex.com"]
31+
}
32+
33+
# Dynamic organizations from a variable map
34+
variable "tenant_orgs" {
35+
type = map(object({
36+
label = string
37+
domains = list(string)
38+
}))
39+
default = {}
40+
}
41+
42+
resource "ory_organization" "tenants" {
43+
for_each = var.tenant_orgs
44+
label = each.value.label
45+
domains = each.value.domains
46+
}
47+
2748
output "organization_id" {
2849
value = ory_organization.acme.id
2950
}

‎docs/resources/project.md‎

Lines changed: 3 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -17,16 +17,18 @@ identity service, OAuth2 server, and configuration.
1717
## Example Usage
1818

1919
```terraform
20-
# Create a production project
20+
# Create a production project in a specific region
2121
resource "ory_project" "production" {
2222
name = "My Application - Production"
2323
environment = "prod"
24+
home_region = "eu-central"
2425
}
2526
2627
# Create a staging project
2728
resource "ory_project" "staging" {
2829
name = "My Application - Staging"
2930
environment = "stage"
31+
home_region = "us-west"
3032
}
3133
3234
# Create a development project (note: no B2B Organizations support)

‎docs/resources/project_api_key.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -24,7 +24,7 @@ resource "ory_project_api_key" "backend" {
2424
# API key with expiration
2525
resource "ory_project_api_key" "temporary" {
2626
name = "Temporary Access"
27-
expires_at = "2024-12-31T23:59:59Z"
27+
expires_at = "2026-12-31T23:59:59Z"
2828
}
2929
3030
# Multiple keys for different environments

‎docs/resources/project_config.md‎

Lines changed: 52 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -53,6 +53,11 @@ resource "ory_project_config" "secure" {
5353
enable_code = true
5454
enable_passkey = true
5555
56+
# Flow Controls
57+
enable_registration = true
58+
enable_recovery = true
59+
enable_verification = true
60+
5661
# MFA
5762
enable_totp = true
5863
totp_issuer = "MyApp"
@@ -61,15 +66,62 @@ resource "ory_project_config" "secure" {
6166
webauthn_rp_id = "app.example.com"
6267
webauthn_rp_origins = ["https://app.example.com"]
6368
webauthn_passwordless = true
69+
enable_lookup_secret = true
70+
mfa_enforcement = "optional"
71+
required_aal = "aal1"
72+
73+
# URLs
74+
default_return_url = "https://app.example.com/dashboard"
75+
allowed_return_urls = [
76+
"https://app.example.com/dashboard",
77+
"https://app.example.com/settings"
78+
]
6479
6580
# Account Experience Branding
6681
account_experience_name = "MyApp"
6782
account_experience_logo_url = "https://cdn.example.com/logo.png"
83+
account_experience_favicon_url = "https://cdn.example.com/favicon.ico"
6884
account_experience_default_locale = "en"
6985
7086
# OAuth2 Token Lifespans
7187
oauth2_access_token_lifespan = "1h"
7288
oauth2_refresh_token_lifespan = "720h"
89+
90+
# Keto Namespaces (for fine-grained authorization)
91+
keto_namespaces = ["documents", "folders", "groups"]
92+
}
93+
94+
# Self-hosted UI configuration (custom login/registration pages)
95+
resource "ory_project_config" "self_hosted_ui" {
96+
login_ui_url = "https://auth.example.com/login"
97+
registration_ui_url = "https://auth.example.com/registration"
98+
recovery_ui_url = "https://auth.example.com/recovery"
99+
verification_ui_url = "https://auth.example.com/verification"
100+
settings_ui_url = "https://auth.example.com/settings"
101+
error_ui_url = "https://auth.example.com/error"
102+
103+
enable_password = true
104+
enable_registration = true
105+
enable_recovery = true
106+
enable_verification = true
107+
}
108+
109+
# SMTP configuration for custom email delivery
110+
resource "ory_project_config" "with_smtp" {
111+
smtp_connection_uri = var.smtp_connection_uri
112+
smtp_from_address = "noreply@example.com"
113+
smtp_from_name = "MyApp"
114+
smtp_headers = {
115+
"X-SES-CONFIGURATION-SET" = "my-config-set"
116+
}
117+
118+
enable_password = true
119+
}
120+
121+
variable "smtp_connection_uri" {
122+
type = string
123+
sensitive = true
124+
description = "SMTP connection URI (e.g., smtps://user:pass@smtp.example.com:465)"
73125
}
74126
```
75127

0 commit comments

Comments
 (0)