https://github.com/easy-oidc/easy-oidc
Easy OIDC is an Open Source, minimal OIDC server written in Go and designed for use with Kubernetes
https://github.com/easy-oidc/easy-oidc
kubernetes oauth oauth2 oidc oidc-server
Last synced: about 15 hours ago
JSON representation
Easy OIDC is an Open Source, minimal OIDC server written in Go and designed for use with Kubernetes
- Host: GitHub
- URL: https://github.com/easy-oidc/easy-oidc
- Owner: easy-oidc
- License: apache-2.0
- Created: 2025-11-05T13:22:31.000Z (8 months ago)
- Default Branch: main
- Last Pushed: 2025-12-03T04:02:18.000Z (7 months ago)
- Last Synced: 2025-12-06T05:24:31.647Z (6 months ago)
- Topics: kubernetes, oauth, oauth2, oidc, oidc-server
- Language: Go
- Homepage: https://easy-oidc.dev
- Size: 94.7 KB
- Stars: 26
- Watchers: 1
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- License: LICENSE
- Agents: AGENTS.md
Awesome Lists containing this project
README
# Easy OIDC
Minimal OIDC server designed for use with Kubernetes, with Google/GitHub/Generic federation, and support for static group overrides.
## Overview
`easy-oidc` is a lightweight, single-binary OIDC server designed specifically for Kubernetes clusters. Instead of managing passwords, it delegates authentication to GitHub, Google, or generic OAuth2+UserInfo or OIDC providers (including Dex, Keycloak, etc) and maps users to Kubernetes groups via simple static configuration.
**Perfect for:**
- Developers already using GitHub or GMail/Google Workspace
- Simple RBAC with static group overrides
- Running on a single EC2 instance with minimal cost
Easy OIDC was created by [Nadrama](https://nadrama.com). Nadrama is an Open Source PaaS that helps you deploy containers, in your cloud account, in minutes.
## Key Features
- **Zero password management** - Delegates to GitHub, Google, or any OAuth2+UserInfo/OIDC provider
- **Static group overrides** - Map a list of emails to groups in the JSONC config
- **PKCE-only** - Secure public client flow (no client secrets to leak)
- **Ed25519 signing** - State-of-the-art cryptography
- **Single binary** - Embedded SQLite (no external database), no external dependencies
- **Multi-cloud support** - Terraform modules for your cloud (AWS [here](https://github.com/easy-oidc/terraform-aws-easy-oidc), GCP/Azure planned)
## Quick Start
See [AWS Terraform Module](https://github.com/easy-oidc/terraform-aws-easy-oidc?tab=readme-ov-file#prerequisites) for instructions on how to deploy to AWS.
## Documentation
- **[SPEC.md](SPEC.md)** - Full specification, architecture, and configuration reference
- **[Terraform Module](https://github.com/easy-oidc/terraform-aws-easy-oidc)** - AWS infrastructure module
## Architecture
```
┌─────────────────┐
│ Secrets Manager │
│ (AWS/GCP/Azure) │
└──────┬──────────┘
│
┌──────────┐ ┌─────────┐ ┌───▼─────┐
│kubelogin │───────▶│ Caddy │───────▶│easy-oidc│
└──────────┘ HTTPS │ (TLS) │ :8080 │ (Go) │
:443 └─────────┘ └────┬────┘
│
┌─────────┼─────────┐
│ │ │
┌─────────▼─┐ ┌─────▼───┐ ┌───▼──────┐
│ Google │ │ GitHub │ │ Generic │
│ OAuth │ │ OAuth │ │ OAuth │
└───────────┘ └─────────┘ └──────────┘
```
- Single VM instance (minimal footprint)
- Caddy handles automatic TLS (via Let's Encrypt)
- Embedded SQLite for OAuth state and authorization code storage with replay protection
- Secrets from cloud-native stores (AWS/GCP/Azure)
## License
Easy OIDC is licensed under the Apache License, Version 2.0.
Copyright 2025 Nadrama Pty Ltd.
See the [LICENSE](./LICENSE) file for details.