Authentication and authorization

Understand the Agent Playbooks credentials, load the administration tokens, scope agent-key grants, and configure operator sign-in with OpenID Connect.

Self-managed Agent Playbooks uses administrative tokens for management and scoped agent keys for applications.

Keep administrative tokens out of application configuration and model prompts.

Credentials

Keep every credential distinct. The chart refuses to mount one Secret key as two of its credentials, but it can't compare values held in differently named Secrets.

The admin token is a shared recovery credential. It grants no access to other Iris products, and audits identify shared recovery use rather than an individual operator. Prefer operator OIDC access for day-to-day administration and keep the admin token for recovery.

Load the administrative credentials

Use an account that can read Secrets, with the port-forwards from Deploy running:

export IRIS_AGENT_PLAYBOOKS_SERVICE_URL='http://localhost:9200'
export IRIS_AGENT_PLAYBOOKS_URL='http://localhost:9201'
export IRIS_IDENTITY_URL='http://localhost:9202'
export IRIS_AGENT_PLAYBOOKS_SERVICE_TOKEN="$(kubectl -n <namespace-name> get secret \
  playbook-controlplane-admin-token -o jsonpath='{.data.token}' | base64 --decode)"
export IRIS_IDENTITY_TOKEN="$(kubectl -n <namespace-name> get secret \
  ids-control-token -o jsonpath='{.data.token}' | base64 --decode)"

The Secret name assumes fullnameOverride: playbook and a chart-generated admin token. If you set controlplane.adminToken.existingSecret, read that Secret, or load the token from your secret manager. The API examples and the Iris command-line interface (CLI) read these variables.

Supply the admin token

By default, the chart generates the admin token in a Secret annotated helm.sh/resource-policy: keep and reuses its value on each live helm upgrade. For GitOps or offline chart rendering, which can't look up the existing value, supply your own Secret so a fresh render doesn't generate a new token:

controlplane:
  adminToken:
    existingSecret: playbook-controlplane-admin
    autoGenerate: false

The same existingSecret, secretKey (default token), autoGenerate, and existingSecretChecksum settings apply to controlplane.internalToken. The data-plane runtime credential has no generator; you always supply it.

Agent-key grants

Each grant names a tenant, the playbook product and resource type, one playbook ID, and its actions:

{
  "tenant": "default",
  "product": "playbook",
  "resourceType": "playbook",
  "resourceId": "<playbook-id>",
  "actions": ["read"]
}

Set tenant to the deployment's tenantId. The Identity Service fills an omitted tenant with its runtime.apiKeyTenant.singleTenantID and rejects grants for another tenant. Before it stores a key, it asks the control plane to confirm that the playbook exists.

write doesn't include publish or propose. See Playbooks for how developers use these actions. The key examples show the complete request. For rotation and revocation, see Operations.

Configure operator OIDC access

You can keep the admin token and also accept OIDC access tokens from your identity provider (IdP). The control plane and data plane share one issuer, tenant source, audience, and trusted group mapping. Both validate tokens locally against the IdP's JSON Web Key Set (JWKS); neither calls the Identity Service for this. Agent keys stay enabled.

Add this overlay to playbook-values.yaml:

auth:
  oidc:
    audience: api://redis-iris

dataplane:
  oidc:
    enabled: true
    issuer: https://<identity-provider-host>/<issuer-path>
    jwksURI: https://<identity-provider-host>/<jwks-path>
    tenantIDClaim: <tenant-claim>
    roleClaims:
      - groups
    roleMappings:
      <viewer-group>: viewer
      <operator-group>: operator
      <playbook-admin-group>: product_admin

controlplane:
  oidc:
    enabled: true

• auth.oidc.audience is the value your IdP puts in the token's aud claim. It defaults to api://redis-iris, the audience shared by every Iris service; use the same value in every Iris chart. On Entra ID with v2 tokens, use the API's Application (client) ID instead. The chart refuses an empty or wildcard audience.
• issuer is compared with the token's iss claim and is never fetched, so it can use http://, including under the Federal Information Processing Standards (FIPS) profile. On Active Directory Federation Services (AD FS), set it to the discovery document's access_token_issuer, such as http://<adfs-host>/adfs/services/trust.
• jwksURI is fetched for signing keys, so it must use https:// unless you set the development-only allowInsecureTransport: true. The FIPS profile refuses that setting. Mount a private CA through tls.caCertSecret when the IdP uses one, and allow both planes egress to the JWKS endpoint.
• Set exactly one of tenantIDClaim and staticTenantID. A resolved or static tenant must equal tenantId. Use staticTenantID only when the issuer and its mapped groups are confined to this deployment's tenant.
• controlplane.oidc.enabled requires dataplane.oidc.enabled and non-empty roleMappings.

roleMappings defaults to empty. Unmapped claim values grant no access, even when a value matches an Iris role name. Map only trusted human administrator groups, and keep service identities out of them.

The control plane applies these role tiers:

On the data plane, explicitly mapped product_admin and suite_admin users receive full Agent Playbooks access within the configured tenant.

The planes cache the JWKS for 10 minutes and allow 5 minutes of clock skew. If a key refresh fails and no cached key validates the token, the request fails with a temporary service error rather than an authentication error. A signed token normally stays usable until it expires. Account for these fixed defaults when you set token lifetimes and retire an IdP signing key.

OIDC access to agent-key administration

The Identity Service has its own OIDC policy for its control API, configured on the Identity Service release with controlAuth.oidc and controlAuth.roleBindings. Configure it when operators must manage agent keys without the Identity Service control token. The control token remains available as a deployment-administration credential. See operator sign-in with your identity provider in the Identity Service guide.