Docs › Your data
Install and pair a gateway
A gateway is a small service you install on a machine inside your network. It reaches databases the cloud can't (an on-premises ERP, a private cloud database) and runs the same refreshes there, over a single outbound connection. It needs no inbound firewall rule, its credentials never leave the machine, and its own administrator decides what it may touch.
Plan availability Gateways are part of the Data sources add-on, on the Plus and Ultimate plans. The workspace must require an authenticator app of every member first (see Connect a database).
What you need#
- A Windows, Windows Server, Linux or macOS machine that can reach the database and make outbound HTTPS connections (port 443) to our gateway service. A machine with a TLS-inspecting proxy needs the gateway host to bypass inspection.
- Administrator rights on that machine to install it. The gateway itself runs as a low-privilege service account.
- A workspace owner or admin to create the pairing code and approve the machine.
Install it#
| System | Package |
|---|---|
| Windows | A signed MSI with the service, the command line and the desktop app. On Windows Server Core the app is left out; use ifp-gateway setup |
| Linux | .deb and .rpm packages from our signed repository: ifp-gateway, and ifp-gateway-desktop for the app |
| macOS | A signed, notarized .pkg with the service, the command line and the app |
The Add gateway dialog links each package for your system, with its version and SHA-256 checksum to check the download against; where a package isn't listed, it links to this guide.
Automatic updates are on by default, inside a window you choose on the gateway. The Gateways page shows the setting each gateway reports (automatic with its window, any time, or off); only the gateway's administrator changes it. A gateway older than the minimum supported version receives no work until it is updated.
Pair it#
- In the app, open Data sources, Gateways, and choose Add gateway. Name it and choose Create pairing code.
- The code (two groups of five letters and digits) is shown once and works for 10 minutes.
- On the machine, enter the code in the desktop app's setup wizard, or run
ifp-gateway setup, or in a scriptifp-gateway pair --code <code>. - The machine shows its key fingerprint. In the app, the gateway appears under Waiting for your approval with the machine name, operating system, public IP and the same fingerprint.
- Approve it only if the fingerprints match. Both sides confirm, so an intercepted code alone can't enrol a gateway.
The gateway then collects its certificate and shows as Online.
Add a data source through it#
- Add a data source as usual and choose Through a gateway, then pick the gateway.
- On the sign-in step, choose how the gateway signs in, the certificate trust, the account and the database's time zone. Nothing secret is entered in the app: these are proposed to the gateway.
- On the gateway (desktop app or
ifp-gateway source approve), the new data source waits as pending. Check its connection there, enter its password if it uses one, test it, choose the allowed objects and approve it. - Back in the app, run the test and confirm it.
Integrated sign-in (SQL Server)#
For SQL Server, the gateway can sign in with Windows / Kerberos authentication as its own service account, so there is no password anywhere:
- On Windows, run the gateway service as a group managed service account (gMSA), for example
CONTOSO\svc-ifp-gw$, and give that login read access in SQL Server. On Linux or macOS, give the service a Kerberos keytab. - Enter the server by its DNS name, not an IP address: Kerberos asks for a ticket for that name.
- Enter the account in the app as
DOMAIN\account. If the server reports a different account (for example the computer account, because the service still runs as its virtual account), the test warns you.
The Gateways page shows each data source's local approval state. Only the gateway's administrator can change it.
Write-back through a gateway#
A data source through a gateway can take write-back like any other: sealed for writing in the app, with write-back turned on by its owner or an admin. The gateway adds its own say, set only on the machine:
- Allow write actions on this source: off by default. Off, every write to the source is refused.
- Each write action a save runs must be approved on the gateway, by its id and its exact definition. A changed action (another table, column, key or parameter mapping) is a new definition and waits for approval again.
- Each query text, read or written, must be approved on the gateway, by its id and its exact text. The gateway classifies and scans the text again itself, with its own rules, before it approves it and before every run.
None of this is entered in the app; the app's approval of a query text doesn't approve it on the gateway.
Approving on the gateway#
In the desktop app, open Data sources, pick the source and its Write-back tab:
- Tick Allow write actions on this source and click Save. "When on, the web app may run the write actions approved below against this source, with the account's own rights. Each action and query text must also be approved here, by its exact definition; a changed action waits for approval again. Off, every write is refused."
- Under Waiting for approval are the write actions and query texts a save named that this gateway hasn't approved: "The statement is what this gateway would run; values are never written into it." Each shows that statement (the generated statement for a table, the
EXECfor a procedure, or the text), its bindings or the scanner's findings, and when it was seen. - Click Approve on each one you accept. A query text with findings needs I have read the findings of the text I approve ticked first; one the gateway's checks refuse can't be approved ("This text cannot be approved: the statement checks refuse it.").
- Approved lists what is approved, each with Withdraw approval.
The command line does the same:
| Command | What it does |
|---|---|
ifp-gateway source writeback <id> on / off | Allows or refuses write actions on the source. Without on or off it lists the approved and pending write actions, with the statement this gateway would run and their bindings, and the query texts with the scanner's findings. |
ifp-gateway source approve-action <id> <actionId> [--hash] | Approves a pending write action, by the definition shown |
ifp-gateway source revoke-action <id> <actionId> | Withdraws an action's approval |
ifp-gateway source approve-text <id> <textId> [--acknowledge-findings] | Approves a pending query text; one with findings needs --acknowledge-findings |
ifp-gateway source revoke-text <id> <textId> | Withdraws a text's approval |
Every change is recorded in the gateway's local activity log with your user name, and the approvals with the definition or text they approve.
An action or text appears under Waiting for approval only after a save (or, for a read text, a read) has named it and been refused. So the first save through a new action on a gateway source is refused; approve the action on the gateway, then save again. The first save after that is the action's dry run.
When the gateway refuses a write#
The save fails, and the failure popup says why in words, with the gateway's code at the end for support, for example "the gateway's administrator hasn't approved this write action yet. Ask them to approve it in the gateway app (Write-back tab), then save again (actionNotApproved)." The gateway's Activity shows the refused job too.
| Code | Why | What to do |
|---|---|---|
writebackNotAllowed | Allow write actions on this source is off on the gateway. | Turn it on, if write-back should be allowed. |
actionNotApproved | This action, with this exact definition, isn't approved on the gateway. | Approve it under Waiting for approval, then save again. |
textNotApproved | A query text the action (or a dataset read) uses isn't approved on the gateway. | Approve the text, then save or read again. |
textRefusedByScanner | The gateway's own checks refuse the text, for example after an update brought newer rules. | Rewrite the text in the app; it is tested and reviewed again. |
payloadMissing, payloadMismatch | The rows of the save didn't reach the gateway complete and unchanged. | Save again. If it keeps happening, check the gateway's connection. |
Keep it healthy#
- Status shows online or offline, the version, when it was last seen and when its certificate renews.
- Rename changes its name in the app.
- Revoke stops it at once: its certificate is refused, its data sources are disabled and the machine must pair again. To move a gateway to a new machine, install and pair the new one, approve its sources, then revoke the old one.
- On the machine, Disable in the app or
ifp-gateway disablestops it accepting work whatever the cloud says.
Plan limits summary#
| Feature | Free | Mini | Plus | Ultimate |
|---|---|---|---|---|
| Gateways (part of the Data sources add-on, $30 a month per workspace) | No | No | With the add-on | With the add-on |
| Integrated sign-in for SQL Server through a gateway | No | No | With the add-on | With the add-on |
| Write-back and query texts through a gateway, approved on the gateway | No | No | With the add-on | With the add-on |