Updated provider documentation (#28)

* update documentation with realistic examples

* cleanup from scaffolding template repo prior to release

* add CHANGELOG.md and CONTRIBUTING.md

Author: Fitzse

CHANGELOG.md

@@ -1,3 +1,41 @@
-## 0.1.0 (Unreleased)
+## 0.1.0
+
+Initial release of the Terraform Keycard Provider.
 
 FEATURES:
+
+* **New Provider**: Terraform provider for managing Keycard resources
+* **OAuth2 Authentication**: Full support for OAuth2 client credentials flow with automatic token refresh
+* **Zone Management**: Create and manage Keycard zones with OAuth2 configuration
+* **Application Management**: Full lifecycle management of applications and their configurations
+* **Identity Provider Integration**: Configure and manage identity providers and user identity mappings
+* **Resource Protection**: Define and manage protected resources within your zones
+* **Workload Identity Federation**: Support for workload identity with JWT and OIDC configurations
+* **Access Management**: Configure application dependencies and access grants
+* **Comprehensive Data Sources**: Read-only access to all managed resources for data lookups
+
+RESOURCES:
+
+* `keycard_zone` - Manage Keycard zones
+* `keycard_provider` - Configure identity and credential providers
+* `keycard_zone_user_identity_config` - Link user identities to zones
+* `keycard_application` - Manage applications
+* `keycard_application_client_secret` - Manage OAuth2 client credentials
+* `keycard_application_workload_identity` - Configure workload identity federation
+* `keycard_resource` - Define protected resources
+* `keycard_application_dependency` - Configure application access grants
+
+DATA SOURCES:
+
+* `keycard_zone` - Look up zone information
+* `keycard_provider` - Look up provider configurations
+* `keycard_zone_user_identity_config` - Look up identity configurations
+* `keycard_application` - Look up application details
+* `keycard_application_workload_identity` - Look up workload identity configurations
+* `keycard_resource` - Look up resource definitions
+
+DOCUMENTATION:
+
+* Complete provider and resource documentation
+* Okta integration guide with step-by-step instructions
+* Examples for all resources and common use cases

CONTRIBUTING.md

@@ -0,0 +1,37 @@
+# Contributing to Terraform Keycard Provider
+
+Thank you for your interest in the Terraform Keycard Provider!
+
+## Contribution Policy
+
+**We do not accept external contributions at this time.**
+
+This provider is maintained by the Keycard team and we handle all development internally to ensure consistency with our platform and roadmap.
+
+## Reporting Issues
+
+If you encounter a bug or have a feature request, please open an issue on our [GitHub Issues](https://github.com/keycardai/terraform-provider-keycard/issues) page. When reporting issues, please include:
+
+- Terraform version (`terraform version`)
+- Provider version
+- Relevant configuration snippets (sanitized of sensitive data)
+- Expected behavior vs. actual behavior
+- Steps to reproduce
+
+## Getting Support
+
+For questions, support, or general inquiries:
+
+- Review the [provider documentation](https://registry.terraform.io/providers/keycardai/keycard/latest/docs)
+- Check existing [GitHub Issues](https://github.com/keycardai/terraform-provider-keycard/issues)
+- Contact Keycard support through your regular support channels
+
+## Development
+
+This provider is built using the [Terraform Plugin Framework](https://developer.hashicorp.com/terraform/plugin/framework).
+
+For information on local development and testing, see the [README.md](README.md#local-development-installation).
+
+## License
+
+This provider is licensed under the [Mozilla Public License 2.0](LICENSE).

LICENSE

@@ -1,5 +1,3 @@
-Copyright (c) 2021 HashiCorp, Inc.
-
 Mozilla Public License Version 2.0
 ==================================
 

docs/data-sources/application.md

@@ -13,72 +13,17 @@ Reads a Keycard application. An application is a software system with an associa
 ## Example Usage
 
 ```terraform
-# Fetch an existing application by zone_id and id
-data "keycard_application" "by_id" {
-  zone_id = "etx6ju28wu5ibs3shgxqwwwpw0"
-  id      = "app123456789"
+# Look up an existing application by zone_id and id
+# Useful when you need to reference applications created outside Terraform
+data "keycard_application" "google_mcp" {
+  zone_id = keycard_zone.production.id
+  id      = var.google_mcp_server_id
 }
 
-# Fetch an existing application by zone_id and identifier
-data "keycard_application" "by_identifier" {
-  zone_id    = "etx6ju28wu5ibs3shgxqwwwpw0"
-  identifier = "https://app.example.com"
-}
-
-# Output the application details
-output "application_name" {
-  value = data.keycard_application.by_id.name
-}
-
-output "application_identifier" {
-  value = data.keycard_application.by_id.identifier
-}
-
-output "application_description" {
-  value = data.keycard_application.by_id.description
-}
-
-output "application_metadata" {
-  value = data.keycard_application.by_id.metadata
-}
-
-output "application_oauth2_redirect_uris" {
-  value = data.keycard_application.by_id.oauth2.redirect_uris
-}
-
-# Use with an application resource
-resource "keycard_zone" "production" {
-  name = "production"
-}
-
-resource "keycard_application" "web_app" {
-  zone_id     = keycard_zone.production.id
-  name        = "Web Application"
-  description = "Main production web application"
-  identifier  = "https://app.example.com"
-
-  metadata = {
-    docs_url = "https://docs.example.com/web-app"
-  }
-
-  oauth2 = {
-    redirect_uris = [
-      "https://app.example.com/auth/callback",
-      "https://app.example.com/oauth2/callback"
-    ]
-  }
-}
-
-# Lookup by ID
-data "keycard_application" "lookup_by_id" {
-  zone_id = keycard_application.web_app.zone_id
-  id      = keycard_application.web_app.id
-}
-
-# Lookup by identifier
-data "keycard_application" "lookup_by_identifier" {
-  zone_id    = keycard_application.web_app.zone_id
-  identifier = keycard_application.web_app.identifier
+# Use the data source to create client credentials for local development
+resource "keycard_application_client_secret" "local_dev" {
+  zone_id        = keycard_zone.production.id
+  application_id = data.keycard_application.google_mcp.id
 }
 ```
 

docs/data-sources/application_workload_identity.md

@@ -13,21 +13,17 @@ Reads a workload identity credential for a Keycard application. This allows you
 ## Example Usage
 
 ```terraform
-# Fetch an existing workload identity credential
-data "keycard_application_workload_identity" "example" {
-  zone_id = "zone-abc123"
-  id      = "cred-xyz789"
+# Look up an existing workload identity by zone_id and id
+# Useful for referencing workload identities credentials created outside Terraform
+data "keycard_application_workload_identity" "okta_mcp" {
+  zone_id = keycard_zone.production.id
+  id      = var.keycard_workload_identity_id
 }
 
-# Use the data source outputs
-output "workload_identity_subject" {
-  value       = data.keycard_application_workload_identity.example.subject
-  description = "The subject constraint for this workload identity"
-}
-
-output "workload_identity_provider" {
-  value       = data.keycard_application_workload_identity.example.provider_id
-  description = "The provider that validates tokens"
+# Use the data source to verify configuration
+output "mcp_service_account_subject" {
+  value       = data.keycard_application_workload_identity.okta_mcp.subject
+  description = "Kubernetes service account subject for Okta MCP server"
 }
 ```
 

docs/data-sources/provider.md

@@ -13,83 +13,24 @@ Reads a Keycard provider. A provider is a system that supplies access to resourc
 ## Example Usage
 
 ```terraform
-# Fetch an existing provider by zone_id and id
-data "keycard_provider" "by_id" {
-  zone_id = "etx6ju28wu5ibs3shgxqwwwpw0"
-  id      = "4rte3f0v5mkr3htgkp2glkrg00"
-}
-
-# Fetch an existing provider by zone_id and identifier
-data "keycard_provider" "by_identifier" {
-  zone_id    = "etx6ju28wu5ibs3shgxqwwwpw0"
-  identifier = "https://dev-123456.okta.com"
-}
-
-# Fetch the default STS Provider for a Zone 
-resource "keycard_zone" "example" {
-  name = "Example Zone"
-}
-
-data "keycard_provider" "sts" {
-  zone_id    = keycard_zone.example.id
-  identifier = keycard_zone.example.oauth2.issuer_url
-}
-
-# Output the provider details
-output "provider_name" {
-  value = data.keycard_provider.by_id.name
-}
-
-output "provider_identifier" {
-  value = data.keycard_provider.by_id.identifier
-}
-
-output "provider_description" {
-  value = data.keycard_provider.by_id.description
-}
-
-output "provider_client_id" {
-  value = data.keycard_provider.by_id.client_id
-}
-
-output "provider_oauth2_endpoints" {
-  value = {
-    authorization_endpoint = data.keycard_provider.by_id.oauth2.authorization_endpoint
-    token_endpoint         = data.keycard_provider.by_id.oauth2.token_endpoint
+# Look up an existing provider by zone_id and identifier
+# Useful for referencing providers created outside Terraform or by other teams
+data "keycard_provider" "google" {
+  zone_id    = keycard_zone.production.id
+  identifier = "https://accounts.google.com"
+}
+
+# Use the provider in resource configurations
+resource "keycard_resource" "google_photos" {
+  name                   = "Google Photos"
+  identifier             = "https://www.googleapis.com/photos/v1"
+  zone_id                = keycard_zone.production.id
+  credential_provider_id = data.keycard_provider.google.id
+
+  oauth2 = {
+    scopes = ["https://www.googleapis.com/auth/photoslibrary"]
   }
 }
-
-# Output STS Provider details
-output "sts_provider_name" {
-  value = data.keycard_provider.sts.name
-}
-
-output "sts_provider_identifier" {
-  value       = data.keycard_provider.sts.identifier
-  description = "The STS issuer URL"
-}
-
-# Use with a provider resource
-resource "keycard_provider" "okta" {
-  zone_id       = "etx6ju28wu5ibs3shgxqwwwpw0"
-  name          = "Okta"
-  description   = "Okta provider for user authentication"
-  identifier    = "https://dev-123456.okta.com"
-  client_id     = "okta-client-id"
-  client_secret = "okta-client-secret"
-}
-
-# Lookup by ID
-data "keycard_provider" "lookup_by_id" {
-  zone_id = keycard_provider.okta.zone_id
-  id      = keycard_provider.okta.id
-}
-
-# Lookup by identifier
-data "keycard_provider" "lookup_by_identifier" {
-  zone_id    = keycard_provider.okta.zone_id
-  identifier = keycard_provider.okta.identifier
-}
 ```
 
 <!-- schema generated by tfplugindocs -->