{"id":40057665,"url":"https://github.com/cbchhaya/unix-oidc","last_synced_at":"2026-01-19T07:01:11.446Z","repository":{"id":333333559,"uuid":"1136656747","full_name":"cbchhaya/unix-oidc","owner":"cbchhaya","description":"OIDC step-up authentication for Linux SSH and sudo. DPoP token binding, device flow MFA, provider-agnostic (Azure AD, Okta, Keycloak). Written in Rust.","archived":false,"fork":false,"pushed_at":"2026-01-19T00:47:22.000Z","size":306,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-01-19T00:48:15.288Z","etag":null,"topics":["authentication","dpop","linux","mfa","oidc","pam","rust","security","ssh","sudo"],"latest_commit_sha":null,"homepage":null,"language":"Rust","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"other","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/cbchhaya.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":"CODEOWNERS","security":"SECURITY.md","support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":"NOTICE","maintainers":"MAINTAINERS.md","copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-01-18T04:57:31.000Z","updated_at":"2026-01-19T00:47:26.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/cbchhaya/unix-oidc","commit_stats":null,"previous_names":["cbchhaya/unix-oidc"],"tags_count":null,"template":false,"template_full_name":null,"purl":"pkg:github/cbchhaya/unix-oidc","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cbchhaya%2Funix-oidc","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cbchhaya%2Funix-oidc/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cbchhaya%2Funix-oidc/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cbchhaya%2Funix-oidc/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/cbchhaya","download_url":"https://codeload.github.com/cbchhaya/unix-oidc/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cbchhaya%2Funix-oidc/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":28562682,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-01-19T03:31:16.861Z","status":"ssl_error","status_checked_at":"2026-01-19T03:31:15.069Z","response_time":67,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.6:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["authentication","dpop","linux","mfa","oidc","pam","rust","security","ssh","sudo"],"created_at":"2026-01-19T07:00:56.283Z","updated_at":"2026-01-19T07:01:11.409Z","avatar_url":"https://github.com/cbchhaya.png","language":"Rust","funding_links":[],"categories":[],"sub_categories":[],"readme":"\u003cp align=\"center\"\u003e\n  \u003cimg src=\"assets/logo.svg\" alt=\"unix-oidc logo\" width=\"120\" height=\"120\"\u003e\n\u003c/p\u003e\n\n\u003ch1 align=\"center\"\u003eunix-oidc\u003c/h1\u003e\n\n\u003cp align=\"center\"\u003e\n  \u003cstrong\u003eStep-up authentication layer for Linux SSH and sudo with OIDC\u003c/strong\u003e\n\u003c/p\u003e\n\n\u003cp align=\"center\"\u003e\n  \u003ca href=\"https://github.com/cbchhaya/unix-oidc/actions/workflows/ci.yml\"\u003e\u003cimg src=\"https://github.com/cbchhaya/unix-oidc/actions/workflows/ci.yml/badge.svg\" alt=\"CI\"\u003e\u003c/a\u003e\n  \u003ca href=\"https://github.com/cbchhaya/unix-oidc/actions/workflows/provider-tests.yml\"\u003e\u003cimg src=\"https://github.com/cbchhaya/unix-oidc/actions/workflows/provider-tests.yml/badge.svg\" alt=\"Provider Tests\"\u003e\u003c/a\u003e\n  \u003ca href=\"https://github.com/cbchhaya/unix-oidc/blob/main/LICENSE\"\u003e\u003cimg src=\"https://img.shields.io/badge/license-Apache--2.0%20OR%20MIT-blue.svg\" alt=\"License\"\u003e\u003c/a\u003e\n  \u003ca href=\"https://github.com/cbchhaya/unix-oidc/releases\"\u003e\u003cimg src=\"https://img.shields.io/github/v/release/cbchhaya/unix-oidc?include_prereleases\" alt=\"Release\"\u003e\u003c/a\u003e\n\u003c/p\u003e\n\n\u003cp align=\"center\"\u003e\n  \u003ca href=\"#why-unix-oidc\"\u003eWhy?\u003c/a\u003e •\n  \u003ca href=\"#features\"\u003eFeatures\u003c/a\u003e •\n  \u003ca href=\"#quick-start\"\u003eQuick Start\u003c/a\u003e •\n  \u003ca href=\"#documentation\"\u003eDocumentation\u003c/a\u003e •\n  \u003ca href=\"#architecture\"\u003eArchitecture\u003c/a\u003e •\n  \u003ca href=\"#learn-more\"\u003eLearn More\u003c/a\u003e\n\u003c/p\u003e\n\n---\n\n## Why unix-oidc?\n\nSSH key management at scale is painful. Keys get copied, shared, never rotated, and rarely audited. When someone leaves, do you really know all the servers they had access to?\n\n**[OpenID Connect (OIDC)](https://openid.net/specs/openid-connect-core-1_0.html)** solves identity, but existing tools have significant limitations:\n\n### Open Source Alternatives\n\n| Tool | Limitation |\n|------|------------|\n| [pam_oidc](https://github.com/salesforce/pam_oidc) (Salesforce) | Bearer tokens only—if stolen, attacker has full access. No sudo step-up. |\n| [pam_oauth2_device](https://github.com/ICS-MU/pam_oauth2_device) | Device flow support, but still bearer tokens. No cryptographic binding. |\n| [pam-keycloak-oidc](https://github.com/zhaow-de/pam-keycloak-oidc) | Keycloak-specific. Embeds OTP in password field (hacky UX). |\n| [ssh-oidc](https://github.com/EOSC-synergy/ssh-oidc) | Token passed as password—limited to 1023 bytes by OpenSSH. |\n\n### Commercial Alternatives\n\n| Tool | Trade-off |\n|------|-----------|\n| [Teleport](https://goteleport.com/) | Excellent but requires proxy infrastructure. SSH OIDC is enterprise-only ($$$). No sudo step-up. |\n| [Boundary](https://www.boundaryproject.io/) (HashiCorp) | Session brokering focus. Requires Vault integration. Complex architecture. |\n| [Smallstep](https://smallstep.com/) | Certificate-based approach. Requires running your own CA. Different security model. |\n| [StrongDM](https://www.strongdm.com/) | Full PAM solution but significant cost (~$100+/user/year). Vendor lock-in. |\n\n### Feature Comparison\n\n| Feature | unix-oidc | pam-keycloak-oidc | Teleport | Smallstep |\n|---------|-----------|-------------------|----------|-----------|\n| SSH OIDC auth | ✅ | ✅ | Enterprise | ✅ |\n| Sudo step-up | ✅ | ❌ | ❌ | ❌ |\n| DPoP token binding | ✅ | ❌ | ❌ | ❌ |\n| Device flow | ✅ | ❌ | N/A | N/A |\n| ACR enforcement | ✅ | Basic | ❌ | ❌ |\n| SSSD integration | ✅ | ❌ | ❌ | ❌ |\n| Provider-agnostic | ✅ | ❌ | ✅ | ✅ |\n| Self-hosted option | ✅ | ✅ | ✅ | ✅ |\n| Open source | ✅ | ✅ | Partial | Partial |\n\n**unix-oidc** was built to address these gaps:\n\n- **[DPoP token binding](https://datatracker.ietf.org/doc/html/rfc9449)** (RFC 9449): Tokens are cryptographically bound to a key pair. Even if an attacker intercepts a token, they can't use it without the private key. This is the same security model used by modern banking APIs.\n\n- **Sudo step-up authentication**: SSH login is just the beginning. Sensitive commands like `systemctl restart` or `kubectl delete` can require fresh MFA via [OAuth 2.0 Device Authorization Grant](https://datatracker.ietf.org/doc/html/rfc8628) (RFC 8628)—bringing web-grade security to the terminal.\n\n- **Provider-agnostic**: Works with Azure AD, Auth0, Google, Okta, Keycloak, or any OIDC-compliant provider. No vendor lock-in.\n\n- **Memory-safe implementation**: Written in Rust. No buffer overflows, no use-after-free, no memory corruption vulnerabilities that plague C-based [PAM modules](https://www.man7.org/linux/man-pages/man8/pam.8.html).\n\n- **Production-ready security**: Rate limiting, [JTI](https://datatracker.ietf.org/doc/html/rfc7519#section-4.1.7) replay protection, structured audit logging, and alignment with [NIST SP 800-63](https://pages.nist.gov/800-63-3/) digital identity guidelines.\n\n### Developer \u0026 User Experience\n\nEnterprise MFA solutions often create friction that developers actively work around. unix-oidc was designed with usability as a core requirement:\n\n| Pain Point | Traditional MFA | unix-oidc |\n|------------|----------------|-----------|\n| Password fatigue | Yet another password to remember | **No passwords**—use your existing IdP (Google, Azure AD, Okta) |\n| Token management | Hardware tokens to carry, batteries that die | **Phone-based**—device flow works with authenticator apps you already have |\n| SSH workflow disruption | Copy-paste tokens, time-sensitive OTPs | **Transparent**—token passed via SSH auth, cached for session |\n| Sudo interruptions | MFA prompt for every privileged command | **Context-aware**—step-up only for sensitive commands, configurable grace periods |\n| Learning curve | New tools, new interfaces, training required | **Familiar flows**—same \"scan QR, tap approve\" as consumer apps |\n| Network dependencies | VPN required, proxy servers to configure | **Direct to IdP**—works from anywhere your IdP is reachable |\n| Emergency access | Locked out when MFA fails | **Break-glass auth**—configurable fallback for emergencies |\n\n**What developers actually experience:**\n\n```\n$ ssh prod-server.example.com\n→ Browser opens: \"Sign in with Google\" (or your IdP)\n→ Approve on phone if MFA required\n→ You're in. Session token cached.\n\n$ sudo systemctl restart critical-service\n→ Phone notification: \"Approve sudo on prod-server?\"\n→ Tap approve\n→ Command runs\n```\n\nNo new passwords. No hardware tokens. No copy-pasting OTPs. Just your existing identity, extended to the terminal.\n\n### A Human-AI Collaboration\n\nThis project was developed collaboratively by [Chiradeep Chhaya](https://github.com/cbchhaya) and [Claude](https://claude.ai) (Anthropic's AI assistant).\n\n**Chiradeep** brought domain expertise in enterprise identity systems, security architecture, and real-world operational requirements from years of experience with PAM, LDAP, and SSO at scale. He defined the security requirements, threat model, and ensured the design would work in production environments.\n\n**Claude** contributed rapid prototyping, comprehensive documentation, security analysis (including [NIST Cybersecurity Framework](https://www.nist.gov/cyberframework) and [MITRE ATT\u0026CK](https://attack.mitre.org/) mappings), and systematic implementation of the Rust codebase. The AI's ability to maintain consistency across a large codebase and generate thorough test coverage accelerated development significantly.\n\nThis collaboration demonstrates that human expertise and AI capabilities can complement each other effectively—humans providing judgment, context, and real-world grounding; AI providing speed, consistency, and tireless attention to detail.\n\n## Features\n\n- **OIDC Authentication for SSH**: Authenticate SSH sessions using [OpenID Connect](https://openid.net/specs/openid-connect-core-1_0.html) tokens\n- **Step-up MFA for Sudo**: Require additional authentication for privileged commands\n  - [OAuth 2.0 Device Authorization Grant](https://datatracker.ietf.org/doc/html/rfc8628) (RFC 8628)\n  - Custom webhook approval workflows\n  - Future: Push notifications, [FIDO2/WebAuthn](https://fidoalliance.org/fido2/)\n- **[DPoP Token Binding](https://datatracker.ietf.org/doc/html/rfc9449)** (RFC 9449): Cryptographically bind tokens to prevent theft\n  - [ES256](https://datatracker.ietf.org/doc/html/rfc7518#section-3.4) and ML-DSA-65 (post-quantum ready)\n  - Replay attack protection\n  - Cross-language libraries: [Rust](rust-oauth-dpop/), [Go](go-oauth-dpop/), [Python](python-oauth-dpop/), [Java](java-oauth-dpop/)\n- **[JWT](https://datatracker.ietf.org/doc/html/rfc7519) Signature Verification**: Cryptographically validates tokens using [JWKS](https://datatracker.ietf.org/doc/html/rfc7517) from OIDC discovery\n- **[SSSD](https://sssd.io/) Integration**: Maps to existing LDAP/AD users via SSSD\n- **Policy-Based Control**: Configure requirements per host classification and command\n- **Audit Logging**: Structured JSON audit events for security monitoring\n- **Multi-Provider Support**: Works with Azure AD, Auth0, Google, Okta, Keycloak, and any OIDC provider\n\n## Quick Start\n\n### Prerequisites\n\n- Linux with PAM support\n- SSSD configured for user directory\n- OIDC-compliant Identity Provider (Keycloak, Azure AD, Okta, etc.)\n\n### Installation\n\n```bash\n# Build the PAM module\ncargo build --release\n\n# Install the PAM module\nsudo cp target/release/libpam_unix_oidc.so /lib/security/pam_unix_oidc.so\n\n# Create configuration directory\nsudo mkdir -p /etc/unix-oidc\n\n# Copy example policy\nsudo cp examples/policy.yaml /etc/unix-oidc/policy.yaml\n```\n\n### Configuration\n\nSet environment variables:\n\n```bash\nexport OIDC_ISSUER=\"https://your-idp.example.com/realms/your-realm\"\nexport OIDC_CLIENT_ID=\"unix-oidc\"\n```\n\nConfigure PAM for SSH (`/etc/pam.d/sshd`):\n\n```\nauth    sufficient    pam_unix_oidc.so\nauth    required      pam_unix.so try_first_pass\n```\n\nConfigure PAM for sudo (`/etc/pam.d/sudo`):\n\n```\nauth    required    pam_unix_oidc.so\nauth    required    pam_unix.so try_first_pass\n```\n\n## Development\n\n```bash\n# Start test environment (Keycloak, LDAP, test host)\nmake dev-up\n\n# Run unit tests\ncargo test\n\n# Run integration tests\nmake test-integration\n\n# Stop test environment\nmake dev-down\n```\n\n## Documentation\n\n### User Documentation\n- [Installation Guide](docs/installation.md) - Installing and configuring unix-oidc\n- [User Guide](docs/user-guide.md) - Day-to-day usage for end users\n- [Sudo Step-Up Authentication](docs/sudo-step-up.md) - Step-up configuration reference\n- [Deployment Patterns](docs/deployment-patterns.md) - Choose the right deployment for your environment\n\n### Security Documentation\n- [Security Guide](docs/security-guide.md) - Hardening, compliance, and best practices\n- [Threat Model](docs/threat-model.md) - Security analysis with NIST CSF and MITRE ATT\u0026CK mapping\n- [Security Policy](SECURITY.md) - Vulnerability reporting\n\n### Developer Documentation\n- [Testing Guide](docs/testing.md) - Running tests at all levels\n- [Extensibility Guide](docs/extensibility-guide.md) - Webhooks, custom mappers, and plugins\n- [Contributing](CONTRIBUTING.md) - How to contribute\n- [Design Document](docs/plans/2026-01-16-unix-oidc-design.md) - Original design\n\n## Architecture\n\nunix-oidc works with **any OIDC-compliant Identity Provider**:\n\n| Provider | Status | Notes |\n|----------|--------|-------|\n| Azure AD (Entra ID) | Tested | Enterprise SSO, Conditional Access |\n| Auth0 | Tested | Developer-friendly, free tier |\n| Google Cloud Identity | Tested | Google Workspace integration |\n| Okta | Supported | Enterprise IdP |\n| Keycloak | Tested | Self-hosted, used in our CI |\n| Any OIDC Provider | Supported | Must support Device Authorization Grant |\n\n### Basic Architecture\n\n```\n┌──────────────┐     ┌──────────────┐     ┌──────────────┐\n│   SSH/Sudo   │────\u003e│  PAM Module  │────\u003e│   OIDC IdP   │\n│   Client     │     │  (unix-oidc) │     │  (Your IdP)  │\n└──────────────┘     └──────┬───────┘     └──────────────┘\n                           │\n                           v\n                     ┌──────────────┐\n                     │     SSSD     │\n                     │  (user dir)  │\n                     └──────────────┘\n```\n\n### Deployment Patterns\n\n**Pattern A: Direct to Cloud IdP** (Simplest)\n- Point unix-oidc directly at Azure AD, Auth0, Google, or Okta\n- Users authenticate with their existing cloud identity\n- Best for: Organizations already using a cloud IdP\n\n**Pattern B: Self-hosted IdP** (Full Control)\n- Deploy Keycloak or similar on your infrastructure\n- Full control over authentication policies\n- Best for: Air-gapped environments, compliance requirements\n\n**Pattern C: Federated via Keycloak** (Hybrid)\n- Keycloak brokers to upstream IdPs (Azure AD, Google, etc.)\n- Centralized policy enforcement\n- Best for: Multi-IdP environments, complex mapping requirements\n\nSee [docs/deployment-patterns.md](docs/deployment-patterns.md) for detailed guidance.\n\n## Testing Status\n\n### What We've Tested\n\n| Component | Environment | Status |\n|-----------|-------------|--------|\n| **Identity Providers** | | |\n| Keycloak | CI (automated) | ✅ Fully tested |\n| Auth0 | Manual testing | ✅ Tested |\n| Google Cloud Identity | Manual testing | ✅ Tested |\n| Azure AD (Entra ID) | Manual testing | ⚠️ Basic flows tested |\n| Okta | Not yet tested | 🔄 Community reports welcome |\n| **Operating Systems** | | |\n| Ubuntu 22.04 LTS | CI (automated) | ✅ Fully tested |\n| Ubuntu 24.04 LTS | Manual testing | ✅ Tested |\n| Debian 12 | Not yet tested | 🔄 Community reports welcome |\n| RHEL 9 / Rocky 9 | Not yet tested | 🔄 Community reports welcome |\n| Amazon Linux 2023 | Not yet tested | 🔄 Community reports welcome |\n\n### Enterprise Readiness\n\nThis is a **beta release**. While the core security mechanisms (DPoP binding, token validation, rate limiting) are thoroughly tested, enterprise deployments should consider:\n\n- **Additional IdP testing**: If you're using Azure AD, Okta, or another IdP in production, please test and report your experience\n- **OS compatibility**: Test on your target OS and report any issues\n- **Scale testing**: We haven't yet tested with hundreds of concurrent authentications\n- **HA/failover**: Document your high-availability setup if you deploy one\n\n**We welcome contributions!** If you test unix-oidc with an IdP or OS not listed above, please:\n1. Open an issue with your test results\n2. Submit a PR to update this table\n3. Share your deployment configuration (sanitized) to help others\n\nSee [CONTRIBUTING.md](CONTRIBUTING.md) for how to contribute.\n\n### CI Infrastructure\n\nOur CI uses Keycloak in Docker for automated testing. This is **not** a requirement for production—use whatever OIDC provider your organization already has.\n\n## Security\n\nSee [SECURITY.md](SECURITY.md) for vulnerability reporting and security design principles.\n\n## Learn More\n\nThis project implements several important security standards. Here are resources to learn more:\n\n### Standards \u0026 RFCs\n- **[RFC 9449 - DPoP](https://datatracker.ietf.org/doc/html/rfc9449)**: Demonstrating Proof of Possession—how we bind tokens to keys\n- **[RFC 8628 - Device Authorization Grant](https://datatracker.ietf.org/doc/html/rfc8628)**: OAuth 2.0 flow for devices without browsers\n- **[RFC 7519 - JSON Web Token (JWT)](https://datatracker.ietf.org/doc/html/rfc7519)**: The token format we validate\n- **[RFC 7517 - JSON Web Key (JWK)](https://datatracker.ietf.org/doc/html/rfc7517)**: How public keys are published\n- **[OpenID Connect Core 1.0](https://openid.net/specs/openid-connect-core-1_0.html)**: The identity layer on OAuth 2.0\n\n### Security Frameworks\n- **[NIST SP 800-63](https://pages.nist.gov/800-63-3/)**: Digital Identity Guidelines—our authentication assurance levels align with these\n- **[NIST Cybersecurity Framework](https://www.nist.gov/cyberframework)**: Risk management framework we map our controls to\n- **[MITRE ATT\u0026CK](https://attack.mitre.org/)**: Threat modeling framework we use for attack analysis\n\n### Linux Security\n- **[Linux-PAM](https://www.man7.org/linux/man-pages/man8/pam.8.html)**: Pluggable Authentication Modules documentation\n- **[SSSD](https://sssd.io/)**: System Security Services Daemon for identity management\n\n## License\n\nLicensed under either of Apache License, Version 2.0 or MIT license at your option.\n\nSee [LICENSE](LICENSE) for details.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcbchhaya%2Funix-oidc","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fcbchhaya%2Funix-oidc","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcbchhaya%2Funix-oidc/lists"}