40 lines
2.1 KiB
Markdown
40 lines
2.1 KiB
Markdown
# Kerberos / GSSAPI SSH Authentication
|
|
|
|
Orca's ssh2-based SSH stack cannot speak `gssapi-with-mic` — the ssh2 library
|
|
has no GSSAPI userauth support, and adding it would mean forking ssh2's
|
|
protocol layer plus shipping the `kerberos` native module (MIT krb5 / Heimdal /
|
|
Windows SSPI) as a prebuilt Electron dependency on three platforms. Instead,
|
|
hosts that need Kerberos ride the existing **system OpenSSH transport** — the
|
|
same parallel transport already used for `ProxyCommand`/`ProxyJump` hosts —
|
|
which delegates GSSAPI, ticket lookup (`kinit` cache, Windows domain logon),
|
|
and credential delegation to the platform's own `ssh` binary on macOS, Linux,
|
|
and Windows (Win32-OpenSSH uses SSPI).
|
|
|
|
## Transport selection
|
|
|
|
Two tiers, deliberately asymmetric because RHEL-family distros ship
|
|
`GSSAPIAuthentication yes` in the global `/etc/ssh/ssh_config`, which makes
|
|
`ssh -G` report GSSAPI enabled for *every* host:
|
|
|
|
1. **Proactive** — a target with `gssapiAuthentication: true` (parsed from an
|
|
explicit `GSSAPIAuthentication yes` in the host's `~/.ssh/config` block, or
|
|
set on the target directly) tries the system-ssh probe first. If that fails
|
|
(e.g. no ticket), the connect falls through to the normal ssh2 key/agent
|
|
path where passphrase/password prompts remain available — OpenSSH semantics
|
|
allow other auth methods alongside GSSAPI.
|
|
2. **Auth-failure fallback** — when ssh2 exhausts key/agent auth and the
|
|
`ssh -G`-resolved config enables GSSAPI (`isGssapiSystemSshFallbackCandidate`
|
|
in `ssh-connection-utils.ts`), the connection retries over system ssh
|
|
*before* prompting the user for credentials. Kerberos-only hosts on
|
|
distro-default configs connect this way; hosts where keys work never leave
|
|
the ssh2 path.
|
|
|
|
Manual (non-ssh-config) targets flagged for GSSAPI get an explicit
|
|
`-o GSSAPIAuthentication=yes` in `system-ssh-args.ts`; config-backed targets
|
|
inherit the option from their own `Host` block since the system binary re-reads
|
|
ssh_config.
|
|
|
|
Both tiers work headless (`orca serve`): the system-ssh probe needs no
|
|
credential callbacks, and GSSAPI itself is non-interactive once a ticket
|
|
exists.
|