# Secret providers

> Link Falak secrets to Vault/OpenBao, AWS, 1Password Connect, Doppler, Infisical or an HTTPS webhook: setup, references, caching and watching.

Source: https://falak.sh/docs/secrets/providers/

A **linked** secret keeps a *reference* to a value held by an external provider instead of the value itself. Falak resolves it on the control plane when a deployment (or a build) needs it, so the value never has to be copied into Falak by hand.

## Add a provider

1. Open **Settings → Secret providers** → **Add** (`secrets.providers.manage`, owners and admins).
2. Pick the type and fill in its settings (below). Credentials are write-only: they are sealed at rest and never shown again.
3. Optionally set the **cache TTL** (default 5 minutes, 0 always asks the provider).
4. Save, then **Test connection**. The provider's status turns *OK* or *Failing* with the reason.

Then create a secret on any Secrets page with **Source: Linked to a provider**, pick the provider and enter the reference.

## Providers and references

| Provider | Reference |
|---|---|
| HashiCorp Vault / OpenBao | `vault://<mount>/data/<path>#<key>` (KV v2) · `vault://<mount>/<path>#<key>` (KV v1, set on the provider) |
| AWS Secrets Manager | `aws-sm://<name or ARN>` · `aws-sm://<name>#<json key>` (one key of a JSON secret) |
| AWS SSM Parameter Store | `aws-ssm:///<path/name>` (or `aws-ssm://<name>`; read with decryption) |
| 1Password | `op://<vault>/<item>/<field>` · `op://<vault>/<item>/<section>/<field>` |
| Doppler | `doppler://<project>/<config>/` |
| Infisical | `infisical://<project id>/<environment>[/<path>…]/` |
| HTTPS webhook | `https://<base URL>/<name>` |

- A reference must match its provider's type; Falak checks it when the secret is saved. When the organization has exactly one provider of a reference's type, you can leave the provider out.
- Values are text. Vault and AWS JSON values pick one key (`#key`); numbers and booleans become their JSON text.

  
    | Setting | Notes |
    |---|---|
    | Address | `https://vault.example.com` |
    | Namespace | Optional (Vault Enterprise / HCP) |
    | KV version | 2 (default) or 1 |
    | Auth method | **Token**; **AppRole** (role id + secret id); **JWT / OIDC** (role + JWT). Optional auth mount |
    | CA certificate | Optional, for a private CA |

    Logins (AppRole and JWT client tokens) are cached sealed until shortly before they expire.
  
  
    One provider type each for **Secrets Manager** and **SSM Parameter Store**.

    | Setting | Notes |
    |---|---|
    | Region | e.g. `eu-central-1` |
    | Auth | Access key id + secret access key (+ session token), optionally an STS **AssumeRole** (role ARN, external id) |

    **Instance profile.** When the control plane runs on EC2, the operator can let AWS providers use its own role (IMDSv2) with `FALAK_SECRETS_PROVIDERS_ALLOW_INSTANCE_PROFILE=true` (off by default). The instance profile is then only ever used to assume a role of the organization's (the role ARN is required), and the external ID sent is always the **organization's id**. Pin it in the role's trust policy, so no other organization of the instance can assume the role:

    ```json
    {"Effect": "Allow", "Principal": {"AWS": "arn:aws:iam::<control plane account>:role/<control plane role>"},
     "Action": "sts:AssumeRole", "Condition": {"StringEquals": {"sts:ExternalId": "<your organization id>"}}}
    ```
  
  
    | Setting | Notes |
    |---|---|
    | Connect URL | Your [1Password Connect](https://developer.1password.com/docs/connect/) server |
    | Token | A Connect token |
    | CA certificate | Optional |

    Service account tokens only work through 1Password's SDKs and CLI, so run a Connect server (it can use the same vaults). Lookups must be unambiguous: two vaults, items or fields with the same name (and no section to tell fields apart) are an error, as is an empty field.
  
  
    | Setting | Notes |
    |---|---|
    | Token | A Doppler service token |
  
  
    | Setting | Notes |
    |---|---|
    | Base URL | Infisical Cloud or your self-hosted URL |
    | Client id, client secret | A machine identity with **universal auth** |
    | CA certificate | Optional |
  
  
    For anything without a native driver: an internal secrets service, or a small adapter in front of another vault (the same model as External Secrets' webhook provider).

    | Setting | Notes |
    |---|---|
    | Base URL | `https://secrets.internal.example.com/v1` |
    | Header | Optional auth header, e.g. `Authorization: Bearer …` or `X-Api-Key: …` |
    | CA certificate | Optional |

    The contract:

    ```text
    GET {base URL}?ref=<name>
    <header>: <value>                      (when configured)
    Accept: application/json

    200 {"value": "the secret value"}
    ```

    - `<name>` is everything after the base URL in the reference, sent as `ref`. The header is only ever sent to the base URL.
    - Any non-2xx answer is a failure (`404` reads as "not found", `401`/`403` as "access refused"). `value` must be a string, number or boolean. Redirects are not followed.
    - **Test connection** asks for `ref=__falak_connection_test__`: any `2xx` or `404` passes, `401`/`403` fails.
  

## Caching and outages

- A resolved value is cached **sealed** in the database, bound to its provider and reference. Within the cache TTL, deployments use it without calling the provider.
- After the TTL the provider is asked again. If it fails, the **last good value** is used, the provider turns *Failing*, and `secrets.provider_unreachable` fires (once, until `secrets.provider_recovered`).
- The last good value is used for at most 24 hours after it was fetched (`FALAK_SECRETS_PROVIDERS_MAX_STALE_SECONDS`). Past that, or with nothing cached, deployments fail with the reason — never with credentials, values or the provider's response body:

  ```text
  secret DB_PASS: Production Vault: HashiCorp Vault / OpenBao at vault.example.com is unreachable …
  ```

- Values larger than 64 KiB are refused.
- Changing a provider's settings drops its cached values and logins.

## Watching for changes

A linked secret can be **watched**: set **Watch every** (minutes, at least 1) when you create or edit it. Falak asks the provider at that interval and compares the answer with the last value it saw (only an HMAC of it is kept). On a change, Falak:

1. records a **new version** (same reference, note *Changed upstream*) holding the new value as a sealed snapshot;
2. fires `secrets.linked_changed` (names only);
3. does what **When it changes** says: nothing more, **restart** the processes of the services that use it, or **redeploy** them.

A value reaches a service's environment when it is deployed, so choose **redeploy** for environment variables; **restart** suits apps that read the secret from the provider themselves when they boot.

### Rolling back a linked secret

Each version keeps its reference and, when the watch saw it, the value it had. Rolling back to such a version **pins** the secret to that value: deployments use the snapshot instead of asking the provider, and the watch pauses. Saving the reference again (a new version) unpins it. Rolling back to a version without a snapshot only restores its reference.

## Network safety

- Endpoints must be `https://`, and TLS is always verified (add a CA certificate for a private CA). Timeouts: 5 s to connect, 10 s in total, one retry.
- Endpoints must resolve to **public addresses**. A provider on a private network needs both the instance setting `FALAK_SECRETS_PROVIDERS_ALLOW_PRIVATE=true` (operator, off by default) and the provider's **Allow private network** (Vault, OpenBao, Infisical, 1Password Connect and webhooks).
- Link-local and cloud metadata addresses are always refused. The check runs when the provider is saved and before every request, and the request is pinned to the addresses checked.

## Permissions

`secrets.view` sees providers (names, types, status, non-secret settings). `secrets.providers.manage` (owners and admins) adds, edits, tests and deletes them — whoever edits an endpoint decides where credentials are sent, so changing a URL, CA certificate, namespace, region, role, external ID or webhook header requires entering every credential again. Developers link secrets to existing providers with `secrets.manage`. A provider used by linked secrets can't be deleted.

## Next steps
