# SFTP (CSV) SFTP directory sync

<!-- Generated by scripts/generate.ts. Do not edit. -->

Put a CSV export of your users on an SFTP server you run, let us sign in with a key pair, and we read the newest file on a schedule you choose.

:::note[Verification]
Verified on a real SFTP (CSV) tenant on 2026-11-09.
:::

The values in braces, such as `{ssh_public_key}`, are specific to your connection. The setup link from the application you are connecting shows them with a copy button. The same steps appear there.

## Steps

<ol class="idp-steps">

<li class="idp-step">

<a id="csv-file"></a>

### Export your users as a CSV file

Have your HR or identity system write a CSV file with a header row to a folder on your SFTP server. It uses the same columns as the CSV import: external_id is required, plus a user_name or email column; given_name, family_name, display_name, active, title, department, employee_number and groups are optional, and any other column is refused. A file can hold up to 50,000 users and 10 MiB.

</li>

<li class="idp-step">

<a id="sftp-user"></a>

### Create a read-only SFTP user

Create a user on the SFTP server that can only read the export folder. We sign in with an SSH key only; passwords are not supported.

</li>

<li class="idp-step">

<a id="generate-key"></a>

### Generate our key pair

Select Generate key in this setup. We create an Ed25519 key pair, keep the private key encrypted and show you the public key. Generating again replaces the earlier pair.

<div class="setup-values">

Paste into SFTP (CSV):

- SSH public key: `{ssh_public_key}`

</div>

</li>

<li class="idp-step">

<a id="authorize-key"></a>

### Install the public key for the SFTP user

Add `{ssh_public_key}` as one line to the SFTP user's authorized_keys file, or paste it into your managed SFTP service's key screen for that user. If you prefer to use your own key, paste its private key in this setup instead (Ed25519, or RSA of 2048 bits or more).

<div class="setup-values">

Paste into SFTP (CSV):

- SSH public key: `{ssh_public_key}`

</div>

:::caution[Labels not confirmed in step 4]
Where the authorized_keys file lives depends on your SFTP server; managed SFTP services usually have their own screen for user keys.
:::

</li>

<li class="idp-step">

<a id="host-key"></a>

### Find the server's host key fingerprint

We never trust a server key we have not been told about. On the server, run ssh-keygen -l -f with the path of its host public key (for example /etc/ssh/ssh_host_ed25519_key.pub). From another computer, run ssh-keyscan with the host name and pipe it to ssh-keygen -lf -, then check the result with your server admin. Copy the SHA256 fingerprint, which starts with SHA256:.

Fixes: [`directory_source_host_key_mismatch`](/errors/directory_source_host_key_mismatch/)

</li>

<li class="idp-step">

<a id="connection"></a>

### Enter the server details in this setup

Enter the host name, the port (22 unless your server uses another), the username, the host key fingerprint and the absolute path of the file, such as /exports/users.csv. The last part of the path may be a pattern such as /exports/users-*.csv; we then read the newest matching file. We connect once to check everything before saving; if the check fails, nothing is saved.

Fixes: [`directory_source_file_not_found`](/errors/directory_source_file_not_found/), [`directory_source_credentials_invalid`](/errors/directory_source_credentials_invalid/), [`directory_source_unavailable`](/errors/directory_source_unavailable/)

</li>

<li class="idp-step">

<a id="preview"></a>

### Preview the first sync

Select Preview to see who would be added, updated and removed, without changing anything. Fix the file if the counts look wrong.

</li>

<li class="idp-step">

<a id="interval"></a>

### Choose how often we read the file

We read the file every 5 minutes by default. You can set any interval from 5 minutes to 24 hours. After a failure we wait longer between tries, up to an hour.

</li>

<li class="idp-step">

<a id="who"></a>

### Know who is synced

Each sync applies the whole file. People missing from the file are removed from the directory, so keep the export complete. If the server's host key changes, syncs stop until you enter the new fingerprint.

Fixes: [`directory_source_host_key_mismatch`](/errors/directory_source_host_key_mismatch/)

</li>

</ol>

## Sources

- [ssh-keygen(1) manual page (OpenBSD)](https://man.openbsd.org/ssh-keygen.1), read on 2026-10-30
- [ssh-keyscan(1) manual page (OpenBSD)](https://man.openbsd.org/ssh-keyscan.1), read on 2026-10-30
- [sshd(8) manual page, AUTHORIZED_KEYS FILE FORMAT (OpenBSD)](https://man.openbsd.org/sshd.8), read on 2026-10-30
