Engity's Bifröst

Bifröst is a fully RFC‑4253 compliant SSH server that extends the classic sshd experience with modern identity federation, container isolation, and automated user lifecycle management. At its core it accepts standard SSH key authentication but can also validate OpenID Connect (OIDC) or OAuth2 tokens, allowing a single credential to drive both the SSH session and any downstream services. This dual‑mode authentication is exposed through a lightweight HTTP endpoint that exchanges the OIDC token for an SSH public key, eliminating the need for a dedicated client or agent on the user’s machine.

The server is written in Go, leveraging its robust networking primitives and excellent support for concurrency. The codebase exposes a modular plugin architecture: authentication back‑ends, session launchers, and post‑session cleanup hooks are all pluggable via Go interfaces. This makes it trivial to drop in a custom LDAP auth provider or replace the Docker session executor with one that uses rkt, Podman, or even a bare‑metal sandbox.

• Language & Runtime: Go 1.22+, compiled to a single static binary.
• Network Layer: Uses the golang.org/x/crypto/ssh package for low‑level SSH protocol handling, ensuring full compatibility with OpenSSH clients.
• Authentication:
  • Public key – standard SSH key validation against a local or LDAP‑backed store.
  • OIDC/OAuth2 – a short‑lived HTTP token endpoint that validates the ID token, extracts the user’s identity and optional groups, then synthesizes a temporary SSH key pair for the session.
• Session Execution:
  • Docker – runs each user in an isolated container, configurable via a YAML template that specifies image, volumes, networks, and resource limits.
  • Kubernetes – launches a dedicated Pod per session using the Kubernetes API, enabling native cluster access without port forwarding.
  • Local – falls back to a standard shell if no container orchestration is configured.
• Lifecycle Management: An optional “automatic provisioning” module creates and deletes local UNIX users based on OIDC claims, cleaning up home directories and terminating orphaned processes after a configurable idle timeout.
• Persistence: Minimal state is stored in SQLite for user templates, session logs, and temporary key caching. All configuration resides in YAML files that are parsed at startup.

Bifröst is designed for self‑hosting in diverse environments:

• Docker Compose / Podman – a single container image (engity/bifroest) can be run with environment variables or mounted config files.
• Kubernetes – a Helm chart (under development) deploys the server as a Deployment with ConfigMaps for configuration and PersistentVolumeClaims for logs.
• Bare‑metal – the static binary can be copied to any Linux host; it requires only a modern kernel (≥ 4.15) and the ability to run Docker/K8s if those back‑ends are used.
• Scalability – the stateless nature of the SSH server allows horizontal scaling behind a load balancer; session state is kept in SQLite or an external database if needed.

• Custom Auth Providers – implement the AuthProvider interface to plug in LDAP, SAML, or custom OAuth2 flows.
• Session Executors – replace the Docker/K8s launchers with your own executor (e.g., Singularity, remote VNC).
• Webhooks – configure HTTP callbacks for session start/end events; useful for audit logging or triggering downstream services.
• Configuration API – a REST endpoint (secured with OIDC) can reload configuration at runtime without restarting the server.

• Declarative Config – YAML files are human‑readable; the schema is documented in docs/reference/configuration/.
• Extensive Docs – usage examples, advanced configuration sections, and a developer guide are available on the website.
• Community & Support – active GitHub repository, issue tracker, and a Code of Conduct ensure a welcoming environment. Contributions are accepted via pull requests with automated tests.
• Testing – the project ships a suite of unit and integration tests that can be run locally; continuous integration is set up on GitHub Actions.

| Scenario | How Bifröst Helps