Skip to content
Dashboard
Theme
Theme

SFTP (CSV) SFTP directory sync

Set up directory sync from a CSV file on an SFTP server

View Markdown

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.

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.

  1. 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.

  2. 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.

  3. 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.

    Paste into SFTP (CSV):

    • SSH public key: {ssh_public_key}
  4. 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).

    Paste into SFTP (CSV):

    • SSH public key: {ssh_public_key}
  5. 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

  6. 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, directory_source_credentials_invalid, directory_source_unavailable

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

  8. 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.

  9. 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