Skip to content
Xferity

Tutorial: FTPS Partner Setup

Tutorial: FTPS Partner Setup

Section titled “Tutorial: FTPS Partner Setup”

This tutorial walks through setting up an FTPS partner in Xferity from scratch, validating the TLS trust configuration, and running your first FTPS transfer.

Prerequisites: FTPS server credentials and the CA certificate (or server certificate) from your partner

What you will build

Section titled “What you will build”
  • an FTPS partner definition with explicit TLS trust
  • a download flow that picks up files from the partner’s FTP directory
  • validation and diagnostics confirming TLS connection before go-live

Step 1: Obtain trust material from the partner

Section titled “Step 1: Obtain trust material from the partner”

Ask the partner for:

  • the CA certificate that signed their server’s TLS certificate (preferred)
  • or the server certificate itself if they use a self-signed cert

Save it as ./keys/insurance-partner-ca.pem.

Step 2: Create the partner definition

Section titled “Step 2: Create the partner definition”

Create partners/insurance-ftps.yaml:

id: insurance-ftps
display_name: Insurance Partner FTPS
protocol: ftps
ftps:
  connection:
    host: ftps.insurance-partner.example
    port: 21
    passive: true
  auth:
    username: xferity-user
    password: env:INSURANCE_FTPS_PASSWORD
  tls:
    mode: explicit
    ca_cert: file:./keys/insurance-partner-ca.pem

Set the environment variable before running:

Terminal window
export INSURANCE_FTPS_PASSWORD=your-actual-password

Step 3: Validate the partner config

Section titled “Step 3: Validate the partner config”
Terminal window
xferity validate

A common mistake is forgetting the file: prefix on the ca_cert reference. The strict YAML parser will also reject unknown fields.

Step 4: Create the download flow

Section titled “Step 4: Create the download flow”

Create flows/insurance-claims-inbound.yaml:

flows:
  insurance-claims-inbound:
    direction: download
    enabled: true
    source:
      partner: insurance-ftps
      path: /outgoing/claims
    local:
      path: ./storage/insurance/claims
    files:
      - pattern: "*.xml"
    idempotency_mode: hash

Step 5: Run diagnostics

Section titled “Step 5: Run diagnostics”
Terminal window
xferity diag insurance-claims-inbound

Diagnostics test FTPS connectivity including TLS handshake. If the CA cert is wrong or the server uses a different cert chain, diagnostics will surface it.

Step 6: Run manually

Section titled “Step 6: Run manually”
Terminal window
xferity run insurance-claims-inbound

Review logs for TLS handshake confirmation and file processing results.

Pinning a specific server certificate

Section titled “Pinning a specific server certificate”

If your partner uses a certificate you want to pin exactly:

tls:
  mode: explicit
  server_cert_fingerprint: "SHA256:abcdefABCDEF0123456789..."

Get the fingerprint from your partner or from openssl:

Terminal window
openssl s_client -connect ftps.insurance-partner.example:21 -starttls ftp 2>/dev/null | \
  openssl x509 -fingerprint -sha256 -noout

Common FTPS setup problems

Section titled “Common FTPS setup problems”
IssueResolution
TLS handshake failsCA cert chain is incomplete or wrong cert provided
Connection refusedFirewall blocking port 21 or the partner requires a different port
Passive mode failsFirewall blocking the data channel port range
TLS cert validation errorserver_cert_fingerprint doesn’t match current cert
Section titled “Related pages”