Introducing Easy OIDC: straightforward OIDC for K8S

TL;DR

• Easy OIDC is a new Apache 2.0 licensed OIDC server designed specifically for Kubernetes authentication.
• It delegates authentication to Google or GitHub - no local passwords or user management required.
• Maps user emails to Kubernetes groups via static configuration for simple RBAC.
• Runs as a single binary on an VM instance with all configuration via a JSONC file.
• Terraform/OpenTofu modules available for AWS, with GCP and Azure coming soon.
• Please support us by starring the Easy OIDC GitHub repository!

Today, while attending KubeCon North America 2025, we are launching Easy OIDC; our new Open Source OIDC server for Kubernetes that makes authentication simple by delegating to Google or GitHub. As with our other Open Source project, we are releasing Easy OIDC under the Apache 2.0 license.

Easy OIDC is available on GitHub today and can be deployed to AWS in minutes using our Terraform module. Full documentation is available at easy-oidc.dev.

If you’re running Kubernetes and want a straightforward way to authenticate users with their existing Google or GitHub accounts while maintaining control over group mappings and RBAC, Easy OIDC might be exactly what you need.

If you’re interested to learn more about why we built Easy OIDC and the design decisions behind it, please read on!

The challenge with Kubernetes authentication

When running Kubernetes clusters, one of the first operational challenges you encounter is authentication. How do your team members and services authenticate to the cluster in a secure, auditable way?

The Kubernetes documentation offers several options: client certificates, bearer tokens, authenticating proxies, or OIDC. Of these, OIDC is the best option for human users, but it requires running an OIDC provider/server.

Existing solutions are complex or expensive

Most organizations end up choosing between a few options:

1. Managed identity providers like Auth0, Okta, or cloud provider IAM - These work well but add monthly costs and introduce dependencies on third-party services or vendor lock-in. For smaller teams or side projects, the pricing doesn’t always make sense.

2. Self-hosted identity platforms like Keycloak or Dex - These are powerful and feature-rich, but come with significant operational overhead. You need to manage databases, handle user provisioning, configure complex authentication flows, and maintain high availability.

3. Client certificates - The simplest option, but certificates are difficult to rotate, hard to audit, and don’t integrate well with existing identity providers.

For teams with developers already using Gmail, Google Workspace, or GitHub, there’s a simpler path: delegate authentication to these existing identity providers and just handle the OIDC token issuance for Kubernetes.

Authentication shouldn’t require a database

After working with various authentication systems over the years, one thing became clear: for Kubernetes authentication specifically, you often don’t need a full-featured identity platform with user databases, password resets, MFA configuration, and admin UIs.

What you actually need is:

• A way to verify users are who they say they are (authentication)
• A mapping from users to Kubernetes groups (authorization data)
• Signed tokens that Kubernetes can validate (OIDC)

If your organization already uses Google or GitHub, the first part is handled. The second part is just configuration. The third part is straightforward with modern crypto libraries.

This realization led to Easy OIDC.

Design Philosophy

Easy OIDC embraces simplicity and the Unix philosophy of doing one thing well. Here’s what that means in practice:

Delegate authentication, not authorization

Easy OIDC never sees user passwords. It redirects users to Google or GitHub for authentication, receives a verified email address back, and issues Kubernetes tokens based on static configuration.

This means:

• No password management or reset flows
• No MFA configuration (use your IdP’s)
• No user database to secure or backup
• Automatic compliance with your IdP’s security policies

Configuration as code

All configuration lives in a single JSONC file with support for comments. Email-to-groups mappings are static and version-controlled. Want to give someone cluster access? Add their email to the config file and redeploy, which takes less than 90 seconds.

This approach trades dynamic user management for simplicity and auditability. Every permission change is in git history.

Minimal infrastructure

Easy OIDC runs as a single Go binary on a single VM instance behind Caddy for automatic TLS. There’s no database to manage (it uses embedded SQLite for temporary OAuth state), no clustering to configure, and no load balancers to provision.

For most use cases, a t4g.nano ARM instance (~$3/month) is sufficient. The Terraform module handles the entire setup including, for example on AWS:

• EC2 instance with dual-stack IPv4/IPv6 (or IPv6-only)
• Security groups
• IAM roles for AWS Secrets Manager access
• Systemd service configuration
• Caddy for automatic Let’s Encrypt TLS

Security by default

Easy OIDC enforces PKCE (Proof Key for Code Exchange) for all flows - no fallback to less secure methods. Signing keys and OAuth credentials are stored in AWS Secrets Manager, never in configuration files or Terraform state.

The instance IAM role has read-only access to secrets, and all secrets are created manually via AWS CLI to keep them out of version control.

How It Works

The architecture is straightforward:

1. User runs kubectl with kubelogin configured
2. kubelogin initiates OIDC flow to Easy OIDC
3. Easy OIDC redirects to Google/GitHub for authentication
4. After successful auth, Easy OIDC receives verified email
5. Looks up email in static configuration to resolve groups
6. Issues signed JWT with email and groups claims
7. Kubernetes API server validates the token and enforces RBAC

All communication with Easy OIDC is over HTTPS (Caddy handles TLS termination). The Go binary only listens on localhost and never sees OAuth credentials in plaintext - they’re fetched from Secrets Manager at startup using the AWS SDK.

What’s Next for Easy OIDC?

Easy OIDC is ready for production use today on AWS. The immediate roadmap includes:

• GCP and Azure modules - Terraform/OpenTofu modules for Google Cloud and Azure are planned, following the same design patterns as the AWS module
• Additional upstream providers - Support for other OIDC-compatible identity providers beyond Google and GitHub, which will be prioritised based on demand from the community
• Advanced claims templates - Optional ability to perform more complex claims transformations based on the user’s identity

The goal is to keep Easy OIDC focused on the core use case: making Kubernetes authentication simple for teams already using modern identity providers. With that said, you can use Easy OIDC for anything requiring an OIDC-server.

We believe authentication infrastructure should be boring and reliable. Easy OIDC aims to be exactly that - a small, focused tool that does one thing well.

Check out the documentation at easy-oidc.dev, deploy it with the Terraform module, and let us know what you think!

Please show your support by starring the Easy OIDC GitHub repository.

If you’re interested in hearing more about the Open Source PaaS we’re building, or want to connect at KubeCon this week, please join our Discord server.

Published: Nov 11, 2025 .