Secure Connection Service agent

Configure the Secure Connection Service agent before enabling Identity Service client integration. Its credentials are not generated by the provisioner; without this setup, Secure Connections cannot authenticate.

1. Generate the agent's credentials

Using openssl and jq, generate private credentials for the Secure Connection Service and public credentials for Identity Service:

SCS_CLIENT_ID="secure-connection-$(openssl rand -hex 4)"
SCS_KEY_ID="secure-connection-key-$(openssl rand -hex 4)"
SCS_KEY=$(openssl ecparam -name secp384r1 -genkey -noout | openssl pkcs8 -topk8 -nocrypt)
SCS_PUBLIC_KEY=$(printf '%s\n' "$SCS_KEY" | openssl pkey -pubout)
SCS_AGENT_PRIVATE=$(SCS_KEY="$SCS_KEY" jq -n --arg c "$SCS_CLIENT_ID" --arg k "$SCS_KEY_ID" \
  '{clientId: $c, keyId: $k, key: env.SCS_KEY}' | base64 | tr -d '\n')
SCS_AGENT_PUBLIC=$(jq -n --arg c "$SCS_CLIENT_ID" --arg k "$SCS_KEY_ID" --arg key "$SCS_PUBLIC_KEY" \
  '{clientId: $c, keyId: $k, key: $key}' | base64 | tr -d '\n')
test -n "$SCS_KEY" && test -n "$SCS_PUBLIC_KEY" && echo "Agent credentials generated" \
  || echo "Generation failed: check the output above" >&2

The key must be ECDSA P-384: the Identity Service refuses any other agent key. $SCS_AGENT_PRIVATE holds the private key, so treat it as a secret. Nothing is written to disk, so keep this shell open until step 3 and close it afterwards.

2. Register the agent with the Identity Service

Add $SCS_AGENT_PUBLIC to istari-identity as ISTARI_DIGITAL_IDENTITY_SERVICE_SCS_AGENT, then choose the chart configuration below for your installation.

New agents

Set tenantSlug to the tenant's slug. This configuration works with any sign-in provider and does not require a Zitadel organization mapping or Configurator Secret.

istari-values.yaml (excerpt)

identity:
  agentRegistration:
    enabled: true
    agents:
      - name: secure-connection
        keyEnv: ISTARI_DIGITAL_IDENTITY_SERVICE_SCS_AGENT
        tenantSlug: <tenant-slug>
        displayName: Secure Connection Service Agent
        platformRoles:
          - secure_connector

The chart creates the tenant if it does not exist. Use the slug of the tenant whose resources the agent will access.

Existing Zitadel agents

For an agent that already uses Zitadel, keep the username binding to preserve access to its existing files and grants. Configurator 1.9.0 or later supplies the username and organization variables:

istari-values.yaml (excerpt)

identity:
  agentRegistration:
    enabled: true
    extraEnvSecrets:
      - zitadel-identity-service-env # also needed here
    agents:
      - name: secure-connection
        keyEnv: ISTARI_DIGITAL_IDENTITY_SERVICE_SCS_AGENT # you add this
        usernameEnv: ISTARI_DIGITAL_IDENTITY_SERVICE_SCS_AGENT_USERNAME # from the Configurator
        providerName: zitadel
        providerTenantIdEnv: ISTARI_DIGITAL_IDENTITY_SERVICE_SCS_AGENT_PROVIDER_TENANT_ID # from the Configurator
        displayName: Secure Connection Service Agent
        platformRoles:
          - secure_connector

Include the Configurator Secret in agentRegistration.extraEnvSecrets, even if it is already in identity.extraEnvSecrets. The agent registers in the imported organization's tenant.

For either configuration, add the public credentials before you run helm upgrade: the registration Job runs only on install and upgrade, and skips the agent without an error if the variable is empty.

3. Point the Secure Connection Service at the Identity Service

Add these to the Secure Connection Service's secret (the one secureConnection.secretName names, or one listed in secureConnection.extraEnvSecrets), then restart the Secure Connection Service:

Variable	Value
ISTARI_DIGITAL_IDENTITY_ROUTER_ENABLED	"true"
ISTARI_DIGITAL_IDENTITY_ROUTER_URL	https://api.<customer_istari_fqdn>/identity
ISTARI_DIGITAL_IDENTITY_SERVICE_CLIENT_CREDENTIALS	$SCS_AGENT_PRIVATE from step 1

Secure Connection Service releases before 11.3.0 read the credential as ISTARI_DIGITAL_IDENTITY_ROUTER_AGENT_KEY instead; setting both names with the same value works on every release. With these set, the Secure Connection Service no longer uses its Zitadel variables to get its tokens.