> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.usepassport.ai/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.usepassport.ai/_mcp/server.

# Configure the Passport Proxy

The Passport Proxy runs in your environment, so you tell it which organization it serves, give it the keys it uses to issue certificates and find credentials, and point it at your secret store and audit destination. This page walks you through finding your organization ID, generating the proxy's keys, and setting those values in `values.yaml`. It assumes you've completed [Get registry access](/passport/set-up/deploy/get-registry-access/), including exporting the chart's default values to `values.yaml`.

## Find your organization ID

Your organization ID ties this proxy deployment to your Passport organization. The proxy only issues certificates for the organization you list, and it won't issue any without one.

To copy your organization ID from the Passport app, do the following:

1. In the Passport app, click **Org Settings** in the header.
2. Select **Overview**.
3. Copy the **Organization ID**.

You'll use this value as `bundle.allowedTeamIds`. If you leave it set to the `CHANGE-ME` placeholder, `helm install` fails with the error `bundle.allowedTeamIds is still set to the placeholder 'CHANGE-ME'`.

## Generate the proxy keys

The proxy won't start without the following two private keys, which you generate in your own environment:

* **CA key** — The proxy uses it to issue certificates to your members' machines. Members authenticate to the proxy with those certificates.
* **Reference key** — The proxy uses it to decrypt the information it needs to find the right credential in your secret store when a request uses a secret reference. You register the matching public key in Passport, which uses it to encrypt that information so that only your proxy can read it.

Both must be RSA keys in PEM format. The following commands generate 2048-bit keys. The proxy creates its own CA certificate from the CA key, so you don't need to create one.

You store the keys in a Kubernetes Secret, and the chart mounts them as files in the proxy. This keeps key material out of `values.yaml`, so don't put it there.

1. Generate the two keys, and the public key for the reference key:

   ```sh showLineNumbers={false}
   mkdir passport-keys && cd passport-keys

   openssl genrsa -out ca-private-key.pem 2048
   openssl genrsa -out reference-private-key.pem 2048
   openssl rsa -in reference-private-key.pem -pubout -out reference-public-key.pem
   ```

   The last command writes the reference key's public half to `reference-public-key.pem`. Keep this file, because you enter it when you [register the proxy](/passport/set-up/set-up-proxy/).

2. Create a Kubernetes namespace for the proxy, then store the two private keys in a Secret named `passport-keys`. A Kubernetes namespace groups resources in your cluster, and it's separate from a Passport namespace. The Secret must be in the namespace that the proxy is installed into, so create the namespace first. Then return to the directory that contains your `values.yaml`:

   ```sh showLineNumbers={false}
   kubectl create namespace passport

   kubectl -n passport create secret generic passport-keys \
     --from-file=ca-private-key=ca-private-key.pem \
     --from-file=reference-private-key=reference-private-key.pem

   cd ..
   ```

> **Warning**
>
> Keep your reference key. If you generate a new one, every secret reference created for the old key stops working, and you must register the proxy again with the new public key.

## Set up the management URL

The management URL is the HTTPS address of the proxy's management endpoint. Your members' machines call it to get certificates from the proxy when they run `passport setup`, where they pass it with the `--management-url` option. You also enter it when you [register the proxy](/passport/set-up/set-up-proxy/). It's separate from the proxy URL, which is where members send API traffic.

By default, the management endpoint is reachable only inside your cluster, so you expose it at a hostname that your members can reach. The chart does this with a Kubernetes Ingress that exposes only the two routes members need for setup. The rest of the management endpoint stays internal.

To set up the management URL, do the following:

1. Choose a hostname for the management endpoint, such as `proxy-mgmt.example.com`, and point it at your cluster's ingress controller.
2. Store a TLS certificate for that hostname in a Kubernetes TLS Secret. The ingress controller handles TLS, because the management endpoint itself uses plain HTTP.
3. Set the `ingress` and `proxy.managementHost` values in `values.yaml`, as shown in the next section.

Your management URL is then the HTTPS address of that hostname, such as `https://proxy-mgmt.example.com`.

## Configure values.yaml

A `values.yaml` file holds the settings for a Helm chart. The file you exported earlier contains the chart's defaults. When you install the proxy, Helm uses your edited copy and falls back to the chart's defaults for anything you didn't change. Most of the file is optional tuning, so you only need to edit the values shown in the following example.

The example is an illustration, not a file to copy as is. The hostnames, ingress class, TLS Secret name, load balancer annotation, region, and organization ID are placeholders, so replace them with your own values. The example also uses AWS Secrets Manager as the secret store, so change the `vault` values to match the store you use. The table after the example explains where each value comes from.

```yaml showLineNumbers={false}
namespace:
  create: false

image:
  repository: ociregistry.usepassport.ai/passport/passport-proxy
  tag: latest
  pullSecrets:
    - name: passport-registry

proxy:
  dataplaneCertSANs: "proxy.example.com"
  managementHost: "proxy-mgmt.example.com"

ingress:
  enabled: true
  className: "<your-ingress-class>"
  host: "proxy-mgmt.example.com"
  tls:
    - secretName: "<your-tls-secret>"
      hosts:
        - "proxy-mgmt.example.com"

bundle:
  allowedTeamIds: "<your-organization-id>"

keys:
  mode: existingSecret
  existingSecret:
    name: passport-keys

vault:
  source: aws-secrets-manager
  aws:
    region: us-east-1

audit:
  sink: stdout

service:
  type: LoadBalancer
  annotations:
    <your-internal-load-balancer-annotation>: "true"
```

| Value                                                | What to enter                                                                                                                                                                                                                                                                                                                                                                                                                                                 |
| ---------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `namespace.create`                                   | Leave as `false`, because you already created the Kubernetes namespace when you stored the keys.                                                                                                                                                                                                                                                                                                                                                              |
| `image.repository`, `image.tag`, `image.pullSecrets` | The image you pulled in [Get registry access](/passport/set-up/deploy/get-registry-access/#pull-the-docker-image) and the `passport-registry` pull secret you created there.                                                                                                                                                                                                                                                                                  |
| `proxy.dataplaneCertSANs`                            | The hostname that your team's machines connect to, such as the DNS name of your load balancer. It must include that hostname, or the TLS handshake fails with `ERR_TLS_CERT_ALT_NAME_INVALID`. Use a comma-separated list for multiple hostnames.                                                                                                                                                                                                             |
| `proxy.managementHost`                               | The hostname of the management URL from [Set up the management URL](#set-up-the-management-url). Enter the host only, with optional port. Don't include `https://` or a path. The proxy adds this hostname to the certificates it issues.                                                                                                                                                                                                                     |
| `ingress.enabled`, `ingress.host`, `ingress.tls`     | Exposes the management endpoint's setup routes at your hostname. Set `ingress.host` to the same hostname as `proxy.managementHost`, and `ingress.tls` to the TLS Secret for that hostname.                                                                                                                                                                                                                                                                    |
| `ingress.className`                                  | The ingress class of your cluster's ingress controller.                                                                                                                                                                                                                                                                                                                                                                                                       |
| `bundle.allowedTeamIds`                              | The organization ID from [Find your organization ID](#find-your-organization-id).                                                                                                                                                                                                                                                                                                                                                                             |
| `bundle.jwksUrl`                                     | Leave at its default. The proxy uses this public Passport key endpoint to verify the access bundles that Passport issues.                                                                                                                                                                                                                                                                                                                                     |
| `keys`                                               | Leave as shown. It reads the `passport-keys` Secret you created.                                                                                                                                                                                                                                                                                                                                                                                              |
| `vault.source`                                       | The secret store that holds your real API credentials. When a request uses a secret reference, the proxy looks up the credential here. Options are `aws-secrets-manager`, `gcp-secret-manager`, or `hashicorp`. Set the matching block (`vault.aws`, `vault.gcpSecretManager`, or `vault.hashicorp`) for your region, project, or address. When you [register the proxy](/passport/set-up/set-up-proxy/), select the same provider under **Vault providers**. |
| `service.type`, `service.annotations`                | How your team's machines reach the proxy's data port (8443). The default, `ClusterIP`, is reachable only inside your cluster. To let machines outside the cluster connect, set `service.type` to `LoadBalancer`. Add your cloud's annotation for an internal load balancer so the proxy isn't exposed publicly, and point the hostname in `proxy.dataplaneCertSANs` at the load balancer.                                                                     |
| `audit.sink`                                         | Where the proxy sends audit events, which record each member's API requests. It's required, because the proxy fails to start without one. The `stdout` option writes audit events to the pod logs. Other options are `file`, `http`, `s3`, `gcs`, and `azure`.                                                                                                                                                                                                |

Leave all other values at their defaults.

## Next steps

With the keys stored and `values.yaml` configured, [install the Passport Proxy](/passport/set-up/deploy/install-proxy/).