OIDC SSH login for Linux, without the gateway
Replace static SSH keys with short-lived IdP-issued tokens, validated directly at the host through PAM, without requiring a gateway or SSH certificate authority.
Why? • How It Works • Quick Start • Documentation • Contributing
Why prmana?
SSH keys get copied, shared, and never rotated. When someone leaves, finding all their access is archaeology. Corporate MFA stops at the browser — you need it for email but not for root on production.
prmana bridges this gap by bringing OIDC (the same protocol behind "Sign in with Google/Microsoft/Okta") to Linux PAM, with DPoP token binding to prevent token theft.
Why teams try it
- Kill static SSH keys without forcing a full access platform rollout
- Keep direct-to-host SSH instead of routing everything through a proxy
- Reuse your existing IdP (Keycloak, Okta, Azure AD, Auth0, Google) for Linux login
- Get proof-of-possession with DPoP — not just bearer-token login
- Stay Linux-native with PAM at the host boundary
- Start small on a few hosts before deciding whether you need more
What makes it different
Most alternatives fall into one of three buckets:
- Access platforms that introduce a proxy, gateway, or managed control plane
- SSH certificate systems that add a CA and cert lifecycle layer
- Simpler PAM/OIDC modules that provide SSO but not strong proof-of-possession
prmana takes a different path: OIDC-backed login directly at the Linux host, with DPoP-bound authentication for stronger token handling. No gateway. No SSH CA. No static keys.
What it is not
prmana is not a session recording platform, a universal infrastructure access proxy, or a full privileged-access management suite. It is a focused tool for SSH login.
How It Works
User's Machine Linux Server
┌─────────────────────┐ ┌─────────────────────┐
│ prmana-agent │ SSH │ sshd │
│ ┌───────────────┐ │ ──────────────▶ │ ┌───────────────┐ │
│ │ OIDC token │ │ │ │ PAM module │ │
│ │ + DPoP proof │ │ │ │ (pam_prmana) │ │
│ └───────────────┘ │ │ └───────────────┘ │
└─────────────────────┘ └─────────────────────┘
│ │
▼ ▼
┌─────────────────────┐ ┌─────────────────────┐
│ Identity Provider │ │ Token validation │
│ (Keycloak/Okta/ │ │ + DPoP verify │
│ Azure AD/Auth0) │ │ + JWKS cache │
└─────────────────────┘ └─────────────────────┘
prmana-agenton the user's machine acquires an OIDC token from your IdP (device flow or auth code + PKCE)- The agent generates a DPoP proof binding the token to an ephemeral key pair
- On SSH connection, the server's PAM module validates the token signature, issuer, audience, expiration, and DPoP binding
- If validation passes and the username maps to a local account (via SSSD), authentication succeeds
Key Components
| Component | Purpose |
|---|---|
prmana-core |
Shared OIDC discovery and JWKS primitives |
pam-prmana |
PAM module — token validation, DPoP verification, break-glass |
prmana-agent |
Client-side agent — token acquisition, DPoP proof generation |
Hardware Key Support
DPoP proofs can be bound to hardware security keys for stronger assurance:
- Software signer — ephemeral P-256 key pair (default)
- YubiKey — PKCS#11 via
--features yubikey - TPM 2.0 — platform TPM via
--features tpm(Linux)
Quick Start
Prerequisites
- A Linux server with OpenSSH and PAM
- An OIDC identity provider (Keycloak, Okta, Azure AD, Auth0, Google)
- Rust toolchain for building from source
Build
Install
# Install the PAM module sudo cp target/release/libpam_prmana.so /lib/security/pam_prmana.so # Install the agent cp target/release/prmana-agent ~/.local/bin/ # Configure sudo cp examples/policy.yaml /etc/prmana/policy.yaml # Edit policy.yaml with your issuer URL and client ID
Login
# On the client machine prmana-agent login # Then SSH normally ssh user@server
See the installation guide for detailed setup including IdP configuration, SSSD integration, and break-glass access.
Documentation
| Guide | Description |
|---|---|
| Installation | Full setup guide |
| PAM Integration | PAM module configuration |
| Security Guide | Hardening and threat model |
| Hardware Key Setup | YubiKey and TPM configuration |
| Break-Glass | Emergency access procedures |
| Keycloak Reference | Keycloak DPoP setup |
| Entra ID Setup | Azure Entra ID configuration |
| Community Testing | Testing on various platforms |
| Threat Model | STRIDE model and residual risks |
| Competitive Threat Surface | Head-to-head security comparison vs alternatives (fact-checked against primary sources) |
Architecture Decision Records
Design decisions are documented in docs/adr/.
Contributing
See CONTRIBUTING.md for development setup and guidelines.
# Run tests cargo test --workspace # Lint cargo clippy --workspace -- -D warnings # Format cargo fmt --all
Community
We'd love your feedback — questions, ideas, bug reports, or just sharing how you're using prmana.
- GitHub Discussions — ask questions, share ideas
- Issues — bug reports and feature requests
Maintained By
Built by Chiradeep Chhaya, cybersecurity architect focused on identity and access management for production infrastructure.
All releases are signed with Sigstore (keyless) and GPG. Commits are signed with the project's GPG key.
Security
See SECURITY.md for vulnerability reporting.
Important: Always configure break-glass access before deploying to production. Getting locked out of servers because your IdP is down is a catastrophic failure mode.
The Name
Pramana (Sanskrit: प्रमाण, pramāṇa) means "proof" and "means of knowledge" — the classical Indian epistemological framework for how you know something is true. The six pramanas are the valid means by which accurate knowledge is acquired: direct perception, inference, testimony, comparison, postulation, and proof by absence.
For this project, the connection is literal: DPoP is a pramana — cryptographic proof-of-possession, not just a bearer token asserting identity.
License
Apache-2.0. See LICENSE.