Skip to content
Dashboard
Theme
Theme

Pulled directory sources

Directories that OhAuthCat reads on a schedule instead of receiving SCIM: a CSV file on an SFTP server, and the Workday, HiBob, Personio, BambooHR, Rippling and Google Workspace APIs. Covers credentials, host-key pinning, previews and the sync interval.

View Markdown

Some customers cannot push SCIM. For them a directory can be a pulled source: OhAuthCat reads the source on a schedule and applies the result with the same rules as a CSV import. Changes reach you as the usual directory events.

Provider Source Credentials (PUT /v1/directories/{dir}/source) Setup guide
sftp_csv A CSV file on the customer’s SFTP server host, optional port (22), username, host_key_fingerprint, path, and private_key unless a key pair was generated SFTP (CSV)
workday Workday Reports-as-a-Service, JSON report_url, username, password (an integration system user) Workday
hibob HiBob people search service_user_id, token HiBob
personio Personio employees client_id, client_secret Personio
bamboohr BambooHR employee directory None: connect from the setup portal with Connect BambooHR (OAuth); API keys are refused with directory_source_method_unavailable BambooHR
rippling_hris Rippling api_token Rippling (HRIS)
google_admin_sdk Google Workspace None: connect from the setup portal with Connect Google (OAuth) Google Workspace

Connect Google is the recommended Google Workspace source: it syncs people and groups, with group members, and works in every Workspace. Google can also push people to a SCIM directory (provider google) through its custom SCIM profiles beta; see Google Workspace (SCIM, beta). That route sends people only, never groups, skips people on secondary domains and works only in Workspaces Google admitted to the beta.

The hosted setup portal offers the same setup, so an organization’s IT admin can connect the source without you handling their credentials.

Create the directory with POST /v1/directories and the source’s provider, as for any directory. A pulled directory, and a csv directory, has no SCIM endpoint: the response has no scim_base_url and no token, and SCIM requests to it answer directory_source_mismatch. Its state is awaiting_first_sync until the first successful sync (or, for csv, the first import), then active.

Saving checks the credentials with one read from the source, then stores them sealed and schedules a sync right away. Credentials are never returned. Refused or malformed credentials answer directory_source_credentials_invalid and an unreachable source directory_source_unavailable; nothing is stored in either case. A directory of another provider answers directory_source_mismatch.

GET /v1/directories/{dir}/source returns the poll state: next_sync_at, last_synced_at, last_error, failures, sync_interval_minutes and the counts of the last successful poll.

Connecting with OAuth (Gusto, BambooHR, Google)

Section titled “Connecting with OAuth (Gusto, BambooHR, Google)”

Gusto, BambooHR and Google Workspace connect through OAuth instead of stored credentials: the setup portal’s Connect button, or POST /v1/directories/{dir}/source/oauth/start from your server.

  1. The answer’s authorization_url is an OhAuthCat confirm page, not the provider. It names the organization and environment the directory will attach to, so the IT admin can see where their people will go before they approve anything. Send the IT admin’s browser there within 30 minutes.
  2. Only pressing Continue on that page, in the same browser, sends them on to the provider’s consent screen. A flow that reaches the callback without that confirmation is refused with directory_source_oauth_confirm_required and nothing is connected. An unknown, expired or used link answers directory_source_oauth_state_invalid.
  3. For Google, the Workspace domain of the admin who approves must be a verified domain of the directory’s organization. Otherwise the grant is refused with directory_source_oauth_domain_unverified and nothing is stored. Have the organization verify its domain first, with a portal link for the domain_verification or sso intent or POST /v1/organizations/{org}/domains.
  4. The browser returns to your return_url with ohauthcat_oauth set to connected, choose_company (Gusto, when the grant reaches several companies) or error with error_code, plus directory_id.

Never build the provider’s consent URL yourself or skip the confirm page; the callback refuses any flow that did not pass it.

Each source is read every 5 minutes by default. Set sync_interval_minutes (5 to 1440) with the credentials to read less often, for example once a day for a nightly HR export. To change only the interval later, send PATCH /v1/directories/{dir}/source with {"sync_interval_minutes": 1440}: the credentials, and a Gusto, BambooHR or Google OAuth connection, stay as they are. The route answers 404 until a source has been saved. After a failure the worker waits longer between tries, up to an hour, whatever the interval.

POST /v1/directories/{dir}/source/preview (or the portal’s Preview button) reads the source once with the saved credentials and returns what a sync would add, update and remove, without changing anything. Use it to catch a wrong report, a filtered export or missing columns before people are deprovisioned. Unreadable data answers directory_csv_invalid.

  • Key pair. POST /v1/directories/{dir}/source/ssh_key generates an Ed25519 key pair. The private key is sealed and never returned; the response has public_key (an OpenSSH authorized_keys line) and its fingerprint. Install the public key for the SFTP user, then save the credentials without private_key. Generating again replaces the pair; a source saved earlier keeps its key until its credentials are saved again. GET on the same route returns the current public key. Customers who prefer their own key send an Ed25519 or RSA (2048 bits or more) private_key instead. Password authentication is not supported.
  • Host key pinning. host_key_fingerprint is required. It is the server’s SHA256 fingerprint as ssh-keygen -l -f /etc/ssh/ssh_host_ed25519_key.pub prints it on the server, or as ssh-keyscan <host> | ssh-keygen -lf - prints it from elsewhere (check that value with the server’s admin). An unknown key is never trusted on first use. A server whose key does not match answers directory_source_host_key_mismatch and syncs stop until the new fingerprint is saved.
  • Path. path is absolute. Its last segment may be a glob such as /exports/users-*.csv; the newest matching file is read. No match answers directory_source_file_not_found.
  • File. The CSV columns and limits are the CSV import’s (10 MiB, 50,000 users). Each sync applies the whole file, so people missing from it are removed.
  • Network. Only public addresses are reached, with a 15 second connect and 2 minute session limit.
  • Workday reads a custom report published as a web service. The report_url must be https on a workday.com or myworkday.com host and return JSON, with columns employee_id, email, first_name, last_name and optional title, department, manager_id, active.
  • HiBob uses an API service user with view access to the default employee fields.
  • Personio uses API credentials with read access to employees; only the attributes the credential may read are shared.

Every HRIS sync reads the full list. Terminated or inactive people are deprovisioned, departments become groups, and rate-limit or server errors are retried with the source’s Retry-After.