Kerberos authentication
Upcoming release
You are reading the reference manual of an upcoming release. Read the current manual »
This page details setting up Kerberos authentication for ContainerSSH. The ContainerSSH kerberos backend can utilize your existing Kerberos/Active-Directory infrastructure to provide authentication for ContainerSSH. The Kerberos backend supports the standard kerberos authentication protocol (GSSAPI) which provides passwordless authentication given that a valid user principal is available on the users device. Failing that, the Kerberos backend can also perform password based authentication. If a correct password is provided ContainerSSH will generate a principal for the user and place it inside the container at a configurable location. This allows users to authenticate to other services without retyping their passwords.
To use the kerberos backend you'll need two things:
- A service keytab
- A valid kerberos config file (
krb5.conf
) for your infrastructure
Configuration¶
The configuration for Kerberos authentication looks as follows:
auth:
password:
method: kerberos
kerberos:
keytab: /path/to/krb5.keytab
configPath: /path/to/krb5.conf
gssapi:
method: kerberos
kerberos:
keytab: /path/to/krb5.keytab
configPath: /path/to/krb5.conf
This will allow logging in either via passwordless login using kerberos tickets (GSS-Api authentication) or by typing the users password.
An example krb5.conf
file looks like this:
[libdefaults]
default_realm = TESTING.CONTAINERSSH.IO
dns_lookup_realm = false
dns_lookup_kdc = false
ticket_lifetime = 24h
renew_lifetime = 7d
forwardable = true
[realms]
TESTING.CONTAINERSSH.IO = {
kdc = 127.0.0.1
}
[domain_realm]
The ticket_lifetime
, renew_lifetime
and forwardable
flags take effect when generating an initial ticket for the user when they logged in via password authentication. They control the lifetime of the users credentials, the amount of time the user can renew those credentials and if these credentials can be forwarded to other services the user logs into.
Additional configuration¶
Furthermore, inside the kerberos
section the following options are supported (and can be customized per-authentication method).
Option | Type | Default | Description |
---|---|---|---|
keytab |
string | /etc/krb5.keytab |
The location of the keytab file for the SSH service |
acceptor |
string | any |
The keytab entry (acceptor) that will be used to verify the users tickets when using GSS-Api authentication. The special value any will check all acceptors. |
configPath |
string | /etc/krb5.conf |
The location of the kerberos configuration file, used only for password-based authentication, a valid realm must be configured |
enforceUsername |
boolean | true |
Whether to ensure that the authenticated username matches the requested username. ⚠ DANGER if set to false: See the Authorization section ⚠ |
credentialCachePath |
string | /tmp/krb5cc |
The path to store the users credentials inside the container. |
clockSkew |
time duration | 5m |
The maximum allowed clock skew for Kerberos messages. Any messages with an older timestamp will be rejected. This is used to prevent replay attacks. |
Authorization and username matching¶
The setting enforceUsername
controls whether to make sure that users can only log in to their own account. When a user connects to an SSH server via kerberos there are 2 different usernames in force, first is the principal username, this is the username present in the kerberos credentials and the real username of the user. The second username is the username that the user requests to log in as.
As an example, if my username is nikos
and I run the following ssh command:
ssh root@myfancykerberosserver.example.org
nikos
, my username, and the username that I request to log in as is root
.
In other words, enforceUsername
makes sure that authenticatedUsername == requestedUsername
and as a result, with the default value of this setting, the aforementioned ssh command would fail as nikos
is not allowed to log into the root
account (only root
can).
In cases where it is desirable for some users to be able to log in with a different username than their own, this setting can be disabled. In this mode, it is strongly advised to use an authorization webhook to control the autnorization. In the authorization webhook both the authenticated username and the requested username are provided so any custom logic can be implemented.
Credential Forwarding¶
ContainerSSH can place a kerberos ticket to the file specified in credentialCachePath
inside the container. This ticket can be used to authenticate to any other kerberos-enabled service with the users credentials. In order for a ticket to be placed the following conditions have to be satisfied:
- The parent directory of
credentialCachePath
needs to exist and writable - The ContainerSSH agent needs to be enabled and present inside the container
- The user has to have used a forwardable kerberos ticket when logging in via GSSAPI or the user must have logged in via password authentication.
If these 3 conditions hold true then the users ticket-granting-ticket will be written to credentialCachePath
. Please note that in order for the credential cache to be picked up by kerberos the path needs to be configured as such in /etc/krb5.conf
, or the equivalent kerberos configuration file.
Info
The relevant configuration setting in the kerberos configuration is default_ccache_name
. An example snippet is:
[libdefaults]
default_ccache_name = FILE:/tmp/krb5cc
When a user logs in using passwordless (GSSAPI) authentication and the users ticket has forwarding enabled then the forwardable ticket will be written to the file specified by credentialCachePath