Learn about syncing your user list using an SFTP connection.
An SFTP integration allows an organization to synchronize user and group information by uploading CSV files using SFTP. WorkOS maintains a receiving SFTP server that can be connected to from the organization's HRIS provider/SFTP client.
If the organization's HRIS has a built-in SFTP client, SFTP will allow them to automatically sync their data and ensure your data is always up to date. An SFTP integration allows for provider-agnostic ingestion of employee data into your product ecosystem.
Once the integration is set up, WorkOS automatically creates and hosts an SFTP folder for the organization's HRIS provider to upload files at a regular cadence.
An SFTP integration has the following advantages:
Your app interfaces with an SFTP directory the same as with other directories; receiving webhook events when the directory is created or updated:
WorkOS provides an SFTP server URL and username specific to the directory. Once set up, the URL and username will be available under directory settings in the WorkOS Dashboard
The SFTP URL is the location of the SFTP server to upload user and group information. Authentication uses a username and a key pair.
You’ll need to provide a public key for authentication. Normally this will come from a key pair provided your customer’s IT team and may be created by their HRIS. Maximum key length is 2048 bytes and supported keys are: ED25519
, RSA
, and ECDSA
.
Your customer will need to export the users and groups as CSV files with the structure below.
This file is not required. Additional metadata may be also included in this file.
If you're interested in setting up an SFTP Integration, please reach out to WorkOS support
Login to your WorkOS Dashboard and select “Organizations” from the left hand navigation bar. Select the organization you’ll be configuring a new Directory Sync connection with.
Click “Add Directory”. Select “SFTP” as the directory type, and then enter a name for this directory.
Click “Create Directory”.
Retrieve the public key that will be used for SFTP from the organization’s admin.
Click “Update Directory” in the WorkOS Dashboard.
Enter the customer’s public key in the input field.
After adding the public key, WorkOS generates a username. You will see the green “Linked” icon appear.
Share the username with the organization admin and ask them to upload the CSV files using their private key to sftp.workos.com
.
Now, whenever your customer assigns users or groups to your application, you’ll receive updates based on the changes in their directory.
Click on the “Users” tab in the dashboard to view synced users.
SFTP (Secure File Transfer Protocol) uses SSH (Secure Shell protocol) to symmetrically encrypt traffic after an asymmetric key negotiation for authentication.
Our solution leverages The AWS Transfer Family
We leverage the default security policy (security-policy-transfer-2020-06
As the data is stored in an AWS S3 bucket the default (since January 2023) is that it is encrypted at rest (SSE-S3
Each of the organizations you’re onboarding will create an SSH key pair
Each of your organizations is mapped to a distinct S3 bucket based on an internal (cryptographically random) identifier for the SSH key pair.
In either of the following events your organization’s data, and the S3 bucket will be deleted: