Authentication and authorization

Configure Redis Agent Memory self-managed Control Plane authentication, Data Plane auth modes, worker callbacks, and gateway integration.

Self-managed Redis Agent Memory uses separate authentication models for the Control Plane and Data Plane.

The Control Plane uses an admin token for management endpoints by default. It also accepts operator tokens when OpenID Connect (OIDC) authentication is configured. The Data Plane checks each agent key with the Identity Service, using the Data Plane service credential, and enforces store-level grants.

Credentials

Credential Who presents it to whom Secret / key Auto-generated? What it unlocks
Control Plane admin token Operator → Control Plane (:9100) iris-memory-admin-token / token Yes, by the suite Store and extractor management through the /iris/v1/agent-memory admin API
Control Plane internal token Identity Service → Control Plane iris-memory-internal-token / memory Yes, by the suite Checking that the store in a grant exists
Identity Service control token Operator → Identity Service (:9200) iris-identity-service-control-token / token Yes, by the suite Creating, listing, updating, rotating and revoking agent keys
Data Plane service credential Data Plane → Identity Service iris-memory-dataplane-credential / memory-dp Yes, by the suite Checking agent keys for memory
Agent key Application → Data Plane (:9000) None; returned once when minted or rotated No The Data Plane operations its grants allow

The suite keeps generated Secrets across upgrades, rollbacks, and uninstalls. To supply your own, see Credentials. To rotate them, see Secret rotation.

Control Plane admin token

With the default configuration, Control Plane management endpoints require:

Authorization: Bearer <admin-token>

Production deployments should read the token from a mounted Secret file:

profile: prod

auth:
  type: admin-token
  admin_token:
    token_file: /etc/controlplane-onprem/admin/token

The Control Plane reads the token file on each request, so rotating the Secret does not require a Control Plane redeploy.

Data Plane auth modes

The Data Plane defaults to agent-key authentication only when the configuration sets no auth method. It also must enable no other auth provider, such as OIDC or worker identity. Set auth.method: agent_key explicitly, so that the security posture is visible in review.

Agent-key authentication

The deploy walkthrough uses agent-key authentication from the start. In the chart-rendered configuration, the suite writes the agent-key introspection settings for its Identity Service, iris-identity-service, and Memory's memory-dp credential.

A bring-your-own (BYO) Data Plane configuration needs the auth.agent_keys.introspection block, including a BYO configuration without auth. See Bring-your-own (BYO) configuration. The MEM_AUTH_METHOD environment variable overrides the method.

Clients send agent keys as Bearer credentials:

Authorization: Bearer <agent-key>

Treat agent keys as opaque credentials. Do not parse their contents.

Auth-disabled Data Plane

Use auth-disabled mode for development and testing only:

profile: dev
ownership:
  enabled: false
auth:
  method: none

These are application configuration fields; put them under memory.memory in iris-values.yaml. The Data Plane refuses auth.method: none unless profile is exactly dev. Chart-rendered configuration fails to render otherwise. With a supplied configuration Secret, the same rule is enforced at process startup.

Warning:

Do not expose an auth-disabled Data Plane to untrusted callers. In auth-disabled mode, Redis Agent Memory does not authenticate or authorize Data Plane requests; any caller that can reach the API can read or write memory for configured stores.

Store authorization and grants

For agent-key requests, Redis Agent Memory checks both identity and resource authorization:

  1. The Data Plane asks the Identity Service whether the key is valid, and caches the answer per pod.
  2. The key has a grant for the requested store resource.
  3. The grant includes the permission required by the operation.

Because of the cache, a revoked key stops working within up to 5 minutes (180 seconds soft, 300 seconds hard). If the Identity Service can't be reached, keys that aren't cached get 503.

A grant names the tenant, product, store, and actions:

{
  "tenant": "<your-tenant-id>",
  "product": "memory",
  "resourceType": "mem-store",
  "resourceId": "<store-id>",
  "actions": ["read", "write"]
}

Use the installation's tenant, global.iris.tenantId (default default), on every grant. The suite applies it to Memory, the Identity Service, and the rendered Control Plane configuration's auth.admin_tenant_id. With a supplied Control Plane configuration Secret, set auth.admin_tenant_id yourself.

Grant actions:

Action Meaning
read Read and search memory data.
write Mutate memory data. write implies read.
full full implies write.

Operation mapping:

Required permission Data Plane operations
read List sessions, get session memory, get session event, get session property, search long-term memory, get long-term memory.
write Add/delete session events, delete session memory, set session summary, set session property, create/update/delete long-term memory.

Server-side ownership enforcement

Store grants authorize access to a store. Ownership enforcement adds a check within that store: ordinary callers can access their own personal records and shared records.

This section applies to on-prem deployments. Ownership enforcement is off by default in the on-prem server, worker, and chart. Turn it on with memory.memory.ownership.enabled: true after you configure a user identity; see Enable or change ownership enforcement.

Setting Personal access Shared access
ownership.enabled: false Your trusted backend must authorize every read and write, including direct-ID requests. Owner fields and filters do not authenticate the user. Your backend checks which shared namespaces the user may access.
ownership.enabled: true The server compares the stored owner with the authenticated user ID. Search and list restrictions apply in addition to client filters. Callers with the required store permission can access shared records. Shared scope does not enforce team membership.

Keep application-specific checks in your backend in both modes. Use separate stores and grants if teams need separate server-enforced access. Worker credentials are for background services; do not give them to applications.

Match stored owners to authenticated users

Use the same stable user ID in stored records and the verified user token. Matching is exact, including case. IDs must meet the format in the API reference; an email address or an identity-provider subject containing punctuation may need a separate compatible claim. Changing a claim mapping does not rewrite stored owners.

The first session event's actorId becomes the session owner. Later events in an accessible session can use an assistant's actor ID without changing ownership. Directly created memories and personal namespace roots use the ownerId supplied by your application. Session extraction inherits the session owner. See Identify users and conversations for client and server fields.

With enforcement on:

  • A new personal owner, or an owner update, must match the authenticated user ID. A mismatch returns 403 Forbidden, including when the record would enter a shared namespace.
  • Another user's personal record is hidden from direct-ID reads and mutations with 404 Not Found. Search and list filters cannot expand access.
  • A personal namespace child inherits its root's owner.
  • A caller without a user ID can access shared records within its grants, but cannot claim a named personal owner. Ownerless private records are hidden.

Agent keys created by POST /v1/api-keys have no user binding by default, and a key never copies its creator's identity. To bind a key to one user, set identityService.apiKeys.userBinding.enabled: true (default false) and send userId when you mint the key. The control token and a suite_admin can set any user ID; other callers can set only their own. The Data Plane then uses that user ID for the key's requests. For an application that acts for many users, use delegation instead. Configuring an OpenID Connect (OIDC) claim alone does not bind a key.

An unbound key can pass store health checks and access allowed shared data while personal creation returns 403. A successful health check does not establish a user identity.

Delegate a user with an agent key

Delegation lets an application use its agent key for store permissions and a user's access token for personal identity. This path is supported in on-prem release 1.0.0. It does not add the user's store grants to the key.

  1. Configure your identity provider to issue signed access tokens with an issuer, a compatible user ID claim, and the intended audience. Obtain the user's token through your application's login process.
  2. Set that issuer and its JSON Web Key Set (JWKS) in global.iris.auth.oidc. The suite applies them to the Data Plane.
  3. Enable delegation and choose an audience distinct from direct OIDC sign-in.
  4. Send both credentials on each request for that user.

For chart-rendered configuration, merge this fragment into iris-values.yaml:

memory:
  memory:
    ownership:
      enabled: true
    auth:
      oidc:
        enabled: true
        user_id_claim: sub
        allow_azp_fallback: false
      delegation:
        enabled: true
        audience:
          - api://memory-delegation

The suite fills in the issuer, JWKS URL, and audience from global.iris.auth.oidc, and the static tenant from global.iris.tenantId. See Ownership and delegation with the suite chart. For a bring-your-own configuration file, place ownership and auth at the root, set auth.oidc.static_tenant_id to that same tenant, and set auth.oidc.audience to the direct-sign-in audience as a list. Do not also configure tenant_id_claim for a single-tenant deployment.

The server verifies the token's signature, issuer, audience, expiry, tenant, and user claim. JWKS verification does not decrypt a token or exchange it for another credential. An application-issued signed JSON Web Token (JWT) works only when the deployment trusts its issuer and verification keys.

Delegation defaults to off and requires OIDC to be enabled. Its audience must not overlap the direct OIDC audience; keep allow_azp_fallback off with a separate delegation audience. Without a separate audience, the same user token can also be presented as a direct sign-in.

Direct OIDC sign-in remains a preview in this release: it validates the token but does not resolve the subject's store grants. A valid token alone receives 403 for store operations. Use the agent key and delegated token together for personal access.

Set USER_TOKEN to the access token for the current request's user, and OWNER_ID to that token's verified user ID. Use the connection values from the quickstart. These examples list that user's session metadata:

import asyncio
import os

import httpx
from redis_agent_memory import AgentMemory


async def main():
    async with httpx.AsyncClient(
        headers={"X-Iris-User-Token": os.environ["USER_TOKEN"]},
    ) as transport:
        async with AgentMemory(
            server_url=os.environ["AGENT_MEMORY_URL"],
            store_id=os.environ["STORE_ID"],
            api_key=os.environ["API_KEY"],
            async_client=transport,
        ) as memory:
            page = await memory.list_sessions_async(
                owner_id=os.environ["OWNER_ID"], limit=20,
            )
            print(page.model_dump_json(by_alias=True))


asyncio.run(main())

Create a separate request-scoped client or transport for each user's token. Do not change a shared client's user header while it handles concurrent requests.

A missing or invalid primary credential, an invalid or expired user token, or a missing user identity returns 401. A token from another tenant, or a delegation header used with a credential other than an agent key, returns 403. A valid delegated user still needs the key's store grant.

Enable or change ownership enforcement

For a new deployment that enables enforcement, configure the user-identity path before writing personal data. If your application does not use a trusted identity provider, leave enforcement off and apply backend authorization.

Before upgrading an existing deployment:

  1. Keep memory.memory.ownership.enabled: false explicitly set while preparing the transition.
  2. Compare stored personal owners with the verified user IDs your application will send. Resolve owner mismatches before enabling enforcement; the setting does not rewrite owners.
  3. Configure delegation, then set memory.memory.ownership.enabled: true in chart-rendered values. For a bring-your-own file, use ownership.enabled: true at the root.
  4. Apply the setting to both Data Plane servers and workers, then roll out those processes. MEM_OWNERSHIP_ENABLED overrides the file value; check both for conflicting settings.
  5. Replace existing Summary Views when changing this setting. A view retains the source-access policy from its creation.
  6. Test two users: each can access their own personal records, neither can retrieve or search for the other's records, and both can access shared records allowed by their store grants.
  7. Test an agent key without a user token: it must not retrieve personal records or create a session for a named owner.

For the two-user read check, use an ordinary agent key with store read access, without operator privileges. Set USER_TOKEN to the first user's valid token. Set OWN_SESSION_ID, OTHER_SESSION_ID, and SHARED_SESSION_ID to existing sessions owned by that user, owned by the other user, and placed in a shared namespace, respectively:

for session_id in "$OWN_SESSION_ID" "$OTHER_SESSION_ID" "$SHARED_SESSION_ID"; do
  curl --silent --show-error --output /dev/null --write-out '%{http_code}\n' \
    --header "Authorization: Bearer $API_KEY" \
    --header "X-Iris-User-Token: $USER_TOKEN" \
    "$AGENT_MEMORY_URL/iris/data/v1/agent-memory/stores/$STORE_ID/sessions/$session_id"
done

Expect 200, 404, and 200, in that order. Repeat with the second user's token and swap OWN_SESSION_ID with OTHER_SESSION_ID. A 401 indicates a token configuration problem; it does not prove ownership enforcement works.

Disabling enforcement restores store-wide access within the credential's grants. Keep backend authorization in place before disabling it. It does not remove stored owner fields, reassign records, or remove the need for store authentication.

Worker callbacks

Redis Agent Memory workers consume background jobs and call the Data Plane to read session events and write extracted long-term memories.

The deploy values already enable worker callbacks. Each platform also needs the setup in Prepare worker identity for your platform.

Workers authenticate with Kubernetes projected ServiceAccount tokens. The suite configures both sides: it mounts the worker's token (workerAuth.enabled, memory.dataplane_client) and trusts the worker's ServiceAccount, system:serviceaccount:<namespace>:redis-agent-memory-worker, in memory.auth.worker_identity, against global.iris.workloadIdentity. Don't set these values yourself: a differing value fails the render.

With a bring-your-own Data Plane configuration, add the dataplane_client and auth.worker_identity blocks yourself, as in the Data Plane configuration file. The worker identity grants store access with resource keys such as mem-store:<store-id>, or mem-store:* for a shared worker identity, with read, write, or full.

Gateway and identity provider integration

Use a gateway when it owns external authentication and coarse policy. For example, a gateway can authenticate callers through an identity provider before it forwards requests to Redis Agent Memory.

If the gateway also owns the standard Authorization header, forward the Agent Memory key in X-Api-Key:

Authorization: Bearer <gateway-token>
X-Api-Key: <ram-agent-key>

Redis Agent Memory uses X-Api-Key as the Redis Agent Memory credential when present. The gateway token is still available to the gateway, but Redis Agent Memory authorizes the request from the server-side grants attached to the Redis Agent Memory key.

Gateway rules:

  • The gateway owns external authentication and perimeter policy.
  • Redis Agent Memory owns store-level authorization.
  • Redis Agent Memory keys are stored and forwarded by trusted infrastructure or trusted applications.
  • Callers must not be able to bypass the gateway and reach the Data Plane directly unless they also present a valid Redis Agent Memory credential.
RATE THIS PAGE
Back to top ↑