Skip to content

Introduction#

Welcome to the comprehensive documentation for ssh-oidc, a solution that enables SSH access using federated identities through OpenID Connect.

What is ssh-oidc?#

ssh-oidc is a collection of tools that allows you to use your federated identity (like your university or organisation login) to access SSH servers securely. Instead of managing SSH keys, you can use your existing institutional credentials through OpenID Connect.

ssh-oidc Is a collection/suite of tools that enables SSH access using OpenID Connect (OIDC) tokens Acts as the overall solution for federated SSH authentication Includes multiple components working together:

  • motley-cue (for identity mapping and user provisioning)
  • mccli (client-side wrapper)
  • oidc-agent (for managing OIDC tokens)
  • Depending on authentication mechaniems:
    • oinit (for ssh-certificates)
    • pam-ssh-oidc (for using Access Tokens via PAM)
  • Other supporting tools

Why ssh-oidc?#

Traditional SSH authentication has several limitations in federated environments:

  • SSH keys are permanent and can be shared across devices and teams
  • No built-in expiration unless manually revoked
  • Trust-on-First-Use (TOFU) security model
  • SSH key management is difficult at scale
  • No federated identity integration

With ssh-oidc we solve these problems by:

  • Time-limited access through token expiration
  • Strong identity binding to prevent key sharing
  • Dynamic user provisioning - no pre-existing accounts needed
  • Single Sign-On across multiple systems
  • Audit trails and user traceability
  • Works with standard SSH - no client modifications required