Skip to content
Open
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
1 change: 1 addition & 0 deletions cyberduck/bookmarks.md
Original file line number Diff line number Diff line change
Expand Up @@ -114,6 +114,7 @@ Select *Bookmark → Edit Bookmark (macOS `⌘E` Windows `Strg+E`)*. A panel whe
| Connect<br/>Mode | For [FTP](../protocols/ftp.md) connections only. Refer to [FTP Connect Mode](../protocols/ftp.md#ftp-connect-mode). |
| Encoding | For [FTP](../protocols/ftp.md) connections only. Character encoding of filenames on the server. You can also change<br/>the encoding used when the connection is open using *View → Text Encoding* if characters<br/>are not displayed properly. Try `UTF-8` (the default), `ISO-8859-1`, and `Windows-1252`.<br/>Refer to [Character Encoding](../protocols/ftp.md#character-encoding). |
| Timezone | For all protocols except [FTP](../protocols/ftp.md), timestamps are reported in [UTC](http://en.wikipedia.org/wiki/Coordinated_Universal_Time) from the server and there is no<br/>need for configuration. All timestamps in the browser are automatically converted to the timezone<br/>you have configured in the *System Preferences* and displayed in local time. For [FTP](../protocols/ftp.md)<br/>however, the local timezone is assumed for timestamps in directory listings If the server<br/>is configured with a different timezone that your Mac and returning the local time for<br/>modification dates, there will be an offset by the timezone difference. To get the correct local<br/>time for modification dates in the browser, you can choose the timezone of the server in the<br/>bookmark settings. Select *Bookmark → Edit Bookmark*. |
| Kerberos<br/>Realm | For [SFTP](../protocols/sftp/index.md) connections only. Default realm for [Kerberos authentication](../tutorials/sftp_kerberos.md#kerberos-realm-per-bookmark).<br/>Leave empty to use the default realm from the Kerberos configuration. |

### Passwords

Expand Down
1 change: 1 addition & 0 deletions protocols/profiles/index.md
Original file line number Diff line number Diff line change
Expand Up @@ -70,6 +70,7 @@ The value of `Vendor` must be unique among all installed connection profiles.
- `Anonymous Configurable` Boolean if anonymous access is configurable.
- `Path Configurable` Boolean if default path is configurable.
- `Certificate Configurable` Boolean if client certificate is configurable.
- `Kerberos Configurable` Boolean if the Kerberos realm is configurable in the bookmark. Defaults to `true` for [SFTP](../sftp/index.md) profiles.
- `Role Configurable`. Boolean if role is configurable. Typically an ARN referencing the AWS IAM role to assume using AWS STS API.
- `Region` Location constraint for [OpenStack Swift](../openstack/index.md) and [S3](../s3/index.md) profiles.
:::{admonition} S3
Expand Down
95 changes: 75 additions & 20 deletions protocols/sftp/index.md

Large diffs are not rendered by default.

16 changes: 16 additions & 0 deletions tutorials/index.md
Original file line number Diff line number Diff line change
Expand Up @@ -17,10 +17,14 @@ owncloud_opencloud_oidc
iam
vault_localdisk
sftp_publickeyauth
sftp_publickeyauth_securitykey
sftp_publickeyauth_pkcs11
sftp_publickeyauth_1password
sftp_publickeyauth_bitwarden
sftp_publickeyauth_yubikey
sftp_azure_blob_storage
sftp_publickeyauth_pageant
sftp_kerberos
cli_github_action
:::

Expand Down Expand Up @@ -65,6 +69,12 @@ Both [Cyberduck](../cyberduck/index.md) and [Mountain Duck](../mountainduck/inde
## [Configure Public Key Authentication for SFTP](sftp_publickeyauth.md)
Configure Public Key Authentication for SFTP using OpenSSH tools.

### [Use a FIDO2 Security Key](sftp_publickeyauth_securitykey.md)
Authenticate with a `sk-*` key in the Secure Enclave unlocked with Touch ID or on a hardware token such as a YubiKey.

### [Use a PKCS#11 Smartcard](sftp_publickeyauth_pkcs11.md)
Authenticate with a private key kept on a smartcard read with a PKCS#11 module such as OpenSC.

### [Configure 1Password SSH Agent](sftp_publickeyauth_1password.md)
Authenticate with SSH private key saved in 1Password.

Expand All @@ -77,5 +87,11 @@ Authenticate with SSH private key saved on YubiKey.
## [Connect to Azure Blob Storage with SFTP](sftp_azure_blob_storage.md)
Authenticate with a local user using a password or private key, or with an SSH certificate issued by Microsoft Entra ID.

### [Configure Pageant](sftp_publickeyauth_pageant.md)
Authenticate with SSH private key loaded in Pageant.

## [Configure Kerberos Authentication for SFTP](sftp_kerberos.md)
Authenticate with a Kerberos ticket obtained with `kinit` using GSSAPI.

## [Use Cyberduck CLI GitHub Action](cli_github_action.md)
Use Cyberduck CLI Docker Container in GitHub Actions
172 changes: 172 additions & 0 deletions tutorials/sftp_kerberos.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,172 @@
Configure Kerberos Authentication for SFTP
====

> Authentication with _Kerberos_ allows you to connect to a remote server without a password using the ticket you already obtained when logging in to your organization's realm with `kinit` or with your account on the Mac. The ticket is presented to the server using the SSH authentication method `gssapi-with-mic`, the equivalent of `ssh -o GSSAPIAuthentication=yes`.

:::{important}
* Cyberduck [9.7.0](https://cyberduck.io/changelog/) or later required
* Mountain Duck [6.0.0](https://mountainduck.io/changelog/) or later required
:::

Authentication with Kerberos is attempted after public key authentication and before prompting for a password when no password is saved for the bookmark. Without a valid ticket the method is skipped and the login continues with the next authentication method offered by the server.

## Requirements

- The server running OpenSSH is configured with `GSSAPIAuthentication yes` in `sshd_config` and has a keytab with the service principal `host/server.example.com@EXAMPLE.COM` for its fully qualified hostname. Refer to your administrator.
- Your principal such as `user@EXAMPLE.COM` is allowed to log in to the account on the server. By default the principal `user@EXAMPLE.COM` maps to the account `user`. Additional principals are listed in `~/.k5login` of the account on the server.
- The Kerberos configuration with the default realm and the Key Distribution Center (KDC) of your organization is found in `/etc/krb5.conf` or can be looked up in DNS. Alternatively set the [realm in the bookmark](#kerberos-realm-per-bookmark).
- On Windows, [MIT Kerberos for Windows](https://web.mit.edu/kerberos/dist/) is installed to obtain the ticket.

## Setup

:::::{tabs}
::::{group-tab} macOS

1. Obtain a ticket for your principal. Enter the password of your Kerberos account when prompted.
```
kinit user@EXAMPLE.COM
```

:::{tip}
Tickets obtained with _Ticket Viewer.app_ in `/System/Library/CoreServices/Applications` or when logging in to a Mac bound to a directory service with Kerberos are used as well.
:::

2. Verify a ticket for the realm is listed and has not expired.
```
klist
```

3. Verify the setup with OpenSSH before connecting with Cyberduck. Use the fully qualified hostname of the server.
```
ssh -o GSSAPIAuthentication=yes -o PreferredAuthentications=gssapi-with-mic user@server.example.com
```

A service ticket for `host/server.example.com@EXAMPLE.COM` is now listed with `klist`.

4. Add a new [Bookmark](../cyberduck/bookmarks.md) in Cyberduck or Mountain Duck. Enter the fully qualified hostname `server.example.com` in _Server_ and your account in _Username_. You do **not** need to set a value for _Password_ or select a _SSH Private Key_.

:::{warning}
The hostname must match the service principal in the keytab of the server. Connecting using an IP address or a short hostname may fail when it cannot be resolved to the fully qualified name.
:::

5. Optionally enter the realm such as `EXAMPLE.COM` in _Kerberos Realm_ in the _More Options_ tab of the bookmark when no default realm is configured or the server belongs to a [different realm](#kerberos-realm-per-bookmark).

6. Connect to the server. No prompt is displayed when the ticket is accepted.

::::
::::{group-tab} Windows

The ticket of _MIT Kerberos for Windows_ is kept in memory by its credentials cache server and cannot be read directly.The ticket granting ticket is copied to a temporary credentials cache file for the login using the `klist.exe` and `kcpytkt.exe` tools of MIT Kerberos for Windows. The temporary file is deleted afterwards.

1. Install [MIT Kerberos for Windows](https://web.mit.edu/kerberos/dist/). The tools are looked up in `%ProgramFiles%\MIT\Kerberos\bin`.

2. Obtain a ticket for your principal with _MIT Kerberos Ticket Manager_ or from the command line. Enter the password of your Kerberos account when prompted.
```
"%ProgramFiles%\MIT\Kerberos\bin\kinit.exe" user@EXAMPLE.COM
```

3. Verify a ticket for the realm is listed and has not expired.
```
"%ProgramFiles%\MIT\Kerberos\bin\klist.exe"
```

4. Add a new [Bookmark](../cyberduck/bookmarks.md). Enter the fully qualified hostname `server.example.com` in _Server_ and your account in _Username_. You do **not** need to set a value for _Password_ or select a _SSH Private Key_.

:::{warning}
The hostname must match the service principal in the keytab of the server. Connecting using an IP address or a short hostname may fail when it cannot be resolved to the fully qualified name.
:::

5. Check _Use MIT Kerberos_ in the bookmark.

6. Enter the realm such as `EXAMPLE.COM` in _Kerberos Realm_. This is required unless the [Kerberos configuration](#kerberos-configuration) is found. The configuration `krb5.ini` of MIT Kerberos for Windows in `%ProgramData%\MIT\Kerberos5` is not read.

7. Connect to the server. No prompt is displayed when the ticket is accepted.

::::
:::::

## Kerberos Realm per Bookmark

Set the realm of the server such as `EXAMPLE.COM` in _Kerberos Realm_ of the [bookmark](../cyberduck/bookmarks.md#bookmark-options) when no default realm is configured on your computer or the server belongs to a different realm than the default realm. The field is found in the _More Options_ tab on macOS.

For a connection with a realm set in the bookmark, a temporary Kerberos configuration with this default realm replaces any [configuration file](#kerberos-configuration). The KDC of the realm is looked up from DNS SRV records unless set with the hidden configuration option `java.security.krb5.kdc`. Other settings from your configuration file such as `[domain_realm]` mappings do not apply to this connection.

The realm is saved in the bookmark as the property `ssh.authentication.gssapi.realm` and can also be set in a [`.duck` bookmark file](hidden_properties.md#in-duck-bookmark-files).

## Kerberos Configuration

The Kerberos configuration is read from `/etc/krb5.conf` or on macOS from `~/Library/Preferences/edu.mit.Kerberos` and `/Library/Preferences/edu.mit.Kerberos` first when found. A minimal configuration for the realm `EXAMPLE.COM` looks like
```
[libdefaults]
default_realm = EXAMPLE.COM

[realms]
EXAMPLE.COM = {
kdc = kdc.example.com
}

[domain_realm]
.example.com = EXAMPLE.COM
```

Omit the `[realms]` section and add `dns_lookup_kdc = true` to `[libdefaults]` to look up the KDC from `_kerberos._tcp` and `_kerberos._udp` DNS SRV records of the realm instead.

The following [hidden configuration options](hidden_properties.md) apply to all connections. Options marked as per bookmark can be set for a single bookmark as well.

| Option | Description |
|-----------------------------------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| `java.security.krb5.conf` | Path to a Kerberos configuration file to use instead of the default location such as `/etc/krb5.conf`. |
| `java.security.krb5.realm` | Default realm such as `EXAMPLE.COM` overriding the configuration file. Must be set together with `java.security.krb5.kdc`. |
| `java.security.krb5.kdc` | Hostname of the KDC for the default realm overriding the configuration file. Must be set together with `java.security.krb5.realm`. Separate multiple KDCs with `:`. |
| `ssh.authentication.gssapi.ticketcache` | Path to a credentials cache file to read the ticket from instead of the default cache. Obtain a ticket written to the file with `kinit -c /path/to/file user@EXAMPLE.COM`. |
| `ssh.authentication.gssapi.realm` | Per bookmark. Default realm for the connection set with _Kerberos Realm_ in the bookmark. Refer to [Kerberos Realm per Bookmark](#kerberos-realm-per-bookmark). |
| `ssh.authentication.gssapi.mit` | Per bookmark. Windows only. Set to `true` to copy the ticket from the credentials cache of MIT Kerberos for Windows. Set with _Use MIT Kerberos_ in the bookmark. |
| `ssh.authentication.gssapi.mit.path` | Windows only. Folder with `klist.exe` and `kcpytkt.exe` of MIT Kerberos for Windows when not installed in `%ProgramFiles%\MIT\Kerberos\bin`. |

Example to set the realm and KDC for Cyberduck on macOS.
```
defaults write ch.sudo.cyberduck java.security.krb5.realm EXAMPLE.COM
defaults write ch.sudo.cyberduck java.security.krb5.kdc kdc.example.com
```

:::{note}
A KDC set with `java.security.krb5.kdc` is always contacted on the default port `88`. Use a configuration file with `kdc = kdc.example.com:port` for a KDC listening on a different port.
:::

## Connection Profiles

The _Kerberos Realm_ field is shown in the bookmark for SFTP connections. Hide it for a [connection profile](../protocols/profiles/index.md) based on SFTP by setting `Kerberos Configurable` to `false`.

## Require Public Key and Kerberos Authentication

Servers can require authentication with both a private key and a Kerberos ticket with `AuthenticationMethods publickey,gssapi-with-mic` in `sshd_config`. Select the private key in _SSH Private Key_ of the bookmark. After the key has been accepted, login completes with the Kerberos ticket.

## Troubleshooting

:::{warning}
When you are prompted for a password instead, no ticket was found or the server did not accept it. Verify with `klist` that the ticket for the realm has not expired and obtain a new ticket with `kinit` otherwise. Verify the login with `ssh -v -o GSSAPIAuthentication=yes user@server.example.com` which prints the reason why the method failed.
:::

:::{warning}
The message _Server not found in Kerberos database_ printed by `ssh -v` indicates no service principal matches the hostname used to connect. Connect using the fully qualified hostname matching the keytab of the server.
:::

:::{warning}
Authentication fails when the clock of your computer differs by more than five minutes from the KDC or the server. Enable _Set time and date automatically_ in _System Settings → General → Date & Time_.
:::

:::{warning}
On Windows, when you are prompted for a password, verify `klist.exe` of MIT Kerberos for Windows lists a ticket granting ticket `krbtgt/EXAMPLE.COM@EXAMPLE.COM` for your realm. When MIT Kerberos for Windows is installed in a different folder, set the hidden configuration option `ssh.authentication.gssapi.mit.path` to the folder containing `klist.exe` and `kcpytkt.exe`.
:::

:::{note}
The `GSSAPIAuthentication` directive in `~/.ssh/config` is not required. The authentication method is always attempted when offered by the server. Change the order in which methods are tried with [`PreferredAuthentications`](../protocols/sftp/index.md#configuration-file) instead. Methods not listed are still tried afterwards.
:::

## References

- [`GSSAPIAuthentication` in ssh_config](https://man.openbsd.org/ssh_config#GSSAPIAuthentication)
- [`GSSAPIAuthentication` in sshd_config](https://man.openbsd.org/sshd_config#GSSAPIAuthentication)
- [RFC 4462: GSS-API Authentication and Key Exchange for SSH](https://www.rfc-editor.org/rfc/rfc4462)
- [MIT Kerberos: krb5.conf](https://web.mit.edu/kerberos/krb5-latest/doc/admin/conf_files/krb5_conf.html)
- [Java Kerberos Requirements](https://docs.oracle.com/en/java/javase/21/security/kerberos-requirements1.html) for the lookup of the configuration file and the system properties `java.security.krb5.realm` and `java.security.krb5.kdc`.
Loading
Loading