Skip to navigation

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, 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:

    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.

  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:

    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 ..

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. 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.

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"
ValueWhat to enter
namespace.createLeave as false, because you already created the Kubernetes namespace when you stored the keys.
image.repository, image.tag, image.pullSecretsThe image you pulled in Get registry access and the passport-registry pull secret you created there.
proxy.dataplaneCertSANsThe 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.managementHostThe hostname of the management URL from 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.tlsExposes 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.classNameThe ingress class of your cluster’s ingress controller.
bundle.allowedTeamIdsThe organization ID from Find your organization ID.
bundle.jwksUrlLeave at its default. The proxy uses this public Passport key endpoint to verify the access bundles that Passport issues.
keysLeave as shown. It reads the passport-keys Secret you created.
vault.sourceThe 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, select the same provider under Vault providers.
service.type, service.annotationsHow 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.sinkWhere 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.