Terraform Provider for Pocket-ID

The Terraform Provider for Pocket-ID enables you to manage OIDC clients, users, and groups in your Pocket-ID instance using Infrastructure as Code.

What is Pocket-ID?

Pocket-ID is a simple, self-hosted OpenID Connect (OIDC) provider that uses passkeys for authentication instead of passwords. This makes it more secure and user-friendly than traditional authentication methods.

Features

• 🔐 OIDC Client Management: Create and manage OAuth2/OIDC client applications
• 👥 User Management: Manage user accounts (passkey registration via UI)
• 👨‍👩‍👦‍👦 Group Management: Organize users and control access with groups
• 🔑 Secure Authentication: API token-based provider authentication
• 🚀 Easy to Use: Simple, intuitive resource definitions
• 📚 Well Documented: Comprehensive documentation and examples

Requirements

• Terraform >= 1.0
• Go >= 1.20 (for development)
• A running Pocket-ID instance
• An API token from your Pocket-ID instance

Installation

Terraform Registry

terraform {
  required_providers {
    pocketid = {
      source  = "trozz/pocketid"
      version = "~> 1.0"
    }
  }
}

Manual Installation

1. Download the latest release from the releases page
2. Extract the archive
3. Move the binary to ~/.terraform.d/plugins/registry.terraform.io/trozz/pocketid/${VERSION}/${OS_ARCH}/

Verifying Release Attestations

All release artifacts include build attestations for supply chain security. To verify the authenticity of a release:

# Using GitHub CLI
gh attestation verify terraform-provider-pocketid_v1.0.0_darwin_amd64.zip \
  --owner Trozz \
  --repo terraform-provider-pocketid

For more information about attestations, see our attestations documentation.

Quick Start

1. Configure the Provider

# Using provider configuration
provider "pocketid" {
  base_url  = "https://auth.example.com"
  api_token = var.pocketid_api_token
}

# Or using environment variables
# export POCKETID_BASE_URL="https://auth.example.com"
# export POCKETID_API_TOKEN="your-api-token"

2. Create an OIDC Client

resource "pocketid_client" "web_app" {
  name = "My Web Application"
  callback_urls = [
    "https://app.example.com/callback",
    "http://localhost:3000/callback"
  ]
  is_public    = false
  pkce_enabled = true
}

output "client_id" {
  value = pocketid_client.web_app.id
}

output "client_secret" {
  value     = pocketid_client.web_app.client_secret
  sensitive = true
}

3. Create Groups and Users

# Create a group
resource "pocketid_group" "developers" {
  name          = "developers"
  friendly_name = "Development Team"
}

# Create a user
resource "pocketid_user" "john_doe" {
  username   = "johndoe"
  email      = "[email protected]"
  first_name = "John"
  last_name  = "Doe"
  groups     = [pocketid_group.developers.id]
}

Resources

Available Resources

• pocketid_client - Manages OIDC client applications
• pocketid_user - Manages user accounts
• pocketid_group - Manages user groups

Available Data Sources

• pocketid_client - Queries a single OIDC client
• pocketid_clients - Lists all OIDC clients
• pocketid_user - Queries a single user by ID or username
• pocketid_users - Lists users with optional filtering

Documentation

Full documentation is available on the Terraform Registry.

Quick Links

• Provider Configuration
• Resource: pocketid_client
• Resource: pocketid_user
• Resource: pocketid_group

Examples

See the examples directory for complete working examples:

• Basic Provider Setup
• Complete Example - Full setup with clients, users, and groups
• Resource Examples - Individual resource examples

Development

Prerequisites

• Go 1.20+
• Terraform 1.0+
• A Pocket-ID instance for testing

Building the Provider

# Clone the repository
git clone https://github.com/Trozz/terraform-provider-pocketid.git
cd terraform-provider-pocketid

# Install dependencies
make deps

# Build the provider
make build

# Install locally for testing
make install

Running Tests

Important Note: Due to Pocket-ID's security model, acceptance tests cannot be run in CI/CD pipelines. Pocket-ID requires:

• Manual passkey registration through the web UI
• Manual API key generation through the admin interface
• No programmatic way to bootstrap an instance

Unit Tests (Automated)

# Run unit tests - these run in CI
make test

Acceptance Tests (Manual)

Acceptance tests require a manually configured Pocket-ID instance:

1. Start a Pocket-ID instance

2. Register a user with a passkey through the web UI

3. Generate an API key in the admin interface

4. Set environment variables:

   export POCKETID_BASE_URL="https://your-pocket-id-instance.com"
   export POCKETID_API_TOKEN="your-api-token"

5. Run acceptance tests:

   make test-acc

See TESTING.md for detailed testing instructions and strategies.

Test Analytics

This project uses Codecov for code coverage and test analytics:

Features

• Code Coverage: Track test coverage across all packages
• Test Analytics: Monitor test performance and identify flaky tests
• Failed Test Reporting: Get detailed reports on test failures
• PR Comments: Automatic coverage reports on pull requests

Running Tests with JUnit Output

For detailed test reporting, use gotestsum:

# Install gotestsum if not already installed
go install gotest.tools/gotestsum@latest

# Run tests with JUnit XML output
make test-junit

# Or run in CI format
make test-ci

This generates:

• coverage.out - Code coverage report
• junit.xml - JUnit format test results for test analytics

Local Coverage Report

Generate an HTML coverage report:

make test-coverage
# Opens coverage.html in your default browser

Local Development

1. Start a local Pocket-ID instance:

   make pocket-id-start

2. Build and install the provider:

   make dev

3. Use the provider in your Terraform configuration

Debugging

Enable debug logging:

export TF_LOG=DEBUG
terraform apply

Contributing

Contributions are welcome! Please see our Contributing Guidelines for details.

How to Contribute

1. Fork the repository
2. Create your feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'Add some amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull Request

Development Workflow

1. Write tests for your changes
2. Ensure all tests pass (make test-all)
3. Update documentation as needed
4. Follow the existing code style
5. Add yourself to the CONTRIBUTORS file

Roadmap

• Support for webhook resources
• Bulk user import functionality
• Enhanced policy management
• Session management features
• Automated passkey registration (when/if API supports it)

Support

• Issues: GitHub Issues
• Discussions: GitHub Discussions
• Pocket-ID: Pocket-ID Repository

Security

Reporting Security Issues

Please report security vulnerabilities to [email protected]. Do not open public issues for security problems.

Best Practices

1. Never commit API tokens to version control
2. Use environment variables or secure secret management
3. Enable TLS verification in production
4. Regularly rotate API tokens
5. Follow the principle of least privilege for API tokens

License

This project is licensed under the MIT License - see the LICENSE file for details.

Acknowledgments

• The Pocket-ID team for creating an awesome OIDC provider
• The Terraform Plugin Framework team
• All contributors who have helped improve this provider

Maintainers

• @trozz

---

Made with ❤️ by the Terraform Pocket-ID Provider community