Enhance documentation for connection and user resources with security warnings and examples

Author: dtoxvanilla1991

docs/resources/connection.md

@@ -23,7 +23,25 @@ Manages a connection in Kinde.
 
 ### Optional
 
-- `options` (Attributes) Options for the connection. Required for OAuth2 connections. Sensitive values are stored in state and rely on state encryption for security. (see [below for nested schema](#nestedatt--options))
+- `options` (Attributes) Options for the connection. Required for OAuth2 connections.
+
+**Warning:** Terraform state is not encrypted by default. The `client_id` and `client_secret` values are stored in state (even when marked as sensitive) and may be written to local state files and remote backends. Use an encrypted remote backend (for example Terraform Cloud/Enterprise, or S3 with `encrypt = true` and SSE-KMS).
+
+Example (S3 backend with KMS):
+
+~~~hcl
+terraform {
+  backend "s3" {
+    bucket     = "my-tf-state"
+    key        = "kinde/terraform.tfstate"
+    region     = "us-east-1"
+    encrypt    = true
+    kms_key_id = "arn:aws:kms:..."
+  }
+}
+~~~
+
+See: https://developer.hashicorp.com/terraform/language/state/sensitive-data (see [below for nested schema](#nestedatt--options))
 
 ### Read-Only
 

docs/resources/user.md

@@ -17,14 +17,14 @@ Manages a user within a Kinde organization.
 
 ### Required
 
-- `first_name` (String) The first name of the user.
 - `identities` (Attributes Set) Identities for the user (email, username, phone, etc.). (see [below for nested schema](#nestedatt--identities))
-- `last_name` (String) The last name of the user.
 
 ### Optional
 
+- `first_name` (String) The first name of the user.
 - `is_suspended` (Boolean) Whether the user is suspended.
-- `organization_code` (String) The code of the organization the user belongs to.
+- `last_name` (String) The last name of the user.
+- `organization_code` (String) Organization code to create the user in. This value is sent to the API only on create and the API does not return it in read responses.
 
 ### Read-Only
 

internal/provider/connection_resource.go

@@ -140,9 +140,27 @@ func (r *ConnectionResource) Schema(_ context.Context, _ resource.SchemaRequest,
 				Required:            true,
 			},
 			"options": schema.SingleNestedAttribute{
-				MarkdownDescription: "Options for the connection. Required for OAuth2 connections. Sensitive values are stored in state and rely on state encryption for security.",
-				Optional:            true,
-				PlanModifiers:       []planmodifier.Object{&optionsEmptyPreserveModifier{}},
+				MarkdownDescription: `Options for the connection. Required for OAuth2 connections.
+
+**Warning:** Terraform state is not encrypted by default. The ` + "`client_id`" + ` and ` + "`client_secret`" + ` values are stored in state (even when marked as sensitive) and may be written to local state files and remote backends. Use an encrypted remote backend (for example Terraform Cloud/Enterprise, or S3 with ` + "`encrypt = true`" + ` and SSE-KMS).
+
+Example (S3 backend with KMS):
+
+~~~hcl
+terraform {
+  backend "s3" {
+    bucket     = "my-tf-state"
+    key        = "kinde/terraform.tfstate"
+    region     = "us-east-1"
+    encrypt    = true
+    kms_key_id = "arn:aws:kms:..."
+  }
+}
+~~~
+
+See: https://developer.hashicorp.com/terraform/language/state/sensitive-data`,
+				Optional:      true,
+				PlanModifiers: []planmodifier.Object{&optionsEmptyPreserveModifier{}},
 				Attributes: map[string]schema.Attribute{
 					"client_id": schema.StringAttribute{
 						Optional:  true,

internal/provider/user_resource.go

@@ -78,8 +78,12 @@ func (r *UserResource) Schema(_ context.Context, _ resource.SchemaRequest, resp
 				Description: "Whether the user is suspended.",
 			},
 			"organization_code": schema.StringAttribute{
-				Optional:    true,
-				Description: "The code of the organization the user belongs to.",
+				Optional:            true,
+				Description:         "The code of the organization the user belongs to.",
+				MarkdownDescription: "Organization code to create the user in. This value is sent to the API only on create and the API does not return it in read responses.",
+				PlanModifiers: []planmodifier.String{
+					stringplanmodifier.RequiresReplace(),
+				},
 			},
 			"created_on": schema.StringAttribute{
 				Description: "The timestamp when the user was created.",