Please use the form below to provide your feedback. Because your feedback is valuable to us, the information you submit in this form is recorded in our issue tracking system (JIRA), which is publicly available. You can track the status of your feedback using the ticket number displayed in the dialog once you submit the form.

Configure Agent Memory Authentication

  • how-to
Secure Agent Memory with OIDC/OAuth2 authentication by connecting it to your external identity provider (IdP).

Agent Memory acts as a stateless resource server that validates JWT access tokens issued by an IdP. Agent Memory never issues tokens or stores secrets such as client credentials or refresh tokens. Agent Memory validates each request independently using a cached JSON Web Key Set (JWKS) fetched from your IdP.

You can connect Agent Memory to any OIDC-compliant identity provider, including:

Prerequisites

  • You have an identity provider that supports OIDC and is reachable over HTTPS.

  • Your IdP meets the following technical requirements:

    OIDC Discovery endpoint

    Your IdP must expose a discovery document at /.well-known/openid-configuration.

    JWKS endpoint

    The discovery document must contain a jwks_uri field pointing to the JSON Web Key Set endpoint.

    RS256 signing algorithm

    Access tokens must be signed with RS256 (RSA + SHA-256).

    Key ID (kid) claim

    The JWT header must include a kid claim for key lookup against the JWKS endpoint.

    Standard claims

    Access tokens must include the following claims: iss, aud, exp.

Procedure

To configure authentication for Agent Memory:

  1. Configure a client in your IdP.

    The steps to configure a client in your IdP vary by provider. For more information, see your IdP’s documentation.

    When configuring your client, make sure to complete the following:

    1. Create a new client or application. Use a confidential client type with the client credentials grant (service account), so that your application can obtain tokens without user interaction.

    2. Set the signing algorithm to RS256.

    3. Note the following values for the next step:

      Issuer URL

      The base URL of your IdP realm or tenant, for example https://your-idp.example.com/realms/myrealm.

      Audience

      The aud value that appears in access tokens, typically the client ID or a custom API identifier.

      Client ID and Client secret

      Your application uses these to obtain access tokens from the IdP.

  2. Add the following environment variables to the .env file in your Agent Memory project directory:

    OIDC_AUTH_ENABLED=true
OIDC_ISSUER=$OIDC_ISSUER_URL
OIDC_AUDIENCE=$OIDC_AUDIENCE

    Replace each $ placeholder with the values from your IdP client configuration. For a description of all available variables, see Environment Variables.

  3. Recreate the Agent Memory container to apply the new environment variables:

    This command briefly interrupts the Agent Memory service. In-flight requests fail until the new container is ready. 
    docker compose up -d --force-recreate agentmemory-server

    On startup, Agent Memory fetches and caches the JWKS from your IdP. The JWKS cache has no expiry time and persists until Agent Memory encounters a token signed with an unrecognized kid, at which point it re-fetches the JWKS once. If your IdP rotates key material while reusing the same kid, Agent Memory cannot detect the change automatically and continues to use the old key until you restart the container. The logs include the following message:

    OIDC authentication initialized issuer=\https://your-idp.example.com/realms/myrealm

  4. Verify that authentication is working by sending a request with a Bearer token.

    1. Obtain an access token from your IdP using the client credentials flow:

      TOKEN=$(curl -s -X POST "$IDP_TOKEN_ENDPOINT" \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "grant_type=client_credentials" \
  -d "client_id=$CLIENT_ID" \
  -d "client_secret=$CLIENT_SECRET" \
  | jq -r '.access_token')

    2. Send an authenticated request to Agent Memory:

      curl -X POST "https://$AGENTMEM_HOST/users" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"user_id": "test-user-1", "name": "Test User"}'

      A 401 Unauthorized response with {"detail": "Authentication required"} means the token was not sent or is invalid.

Environment Variables

Variable Required Default Description

OIDC_AUTH_ENABLED

No

false

Enable or disable authentication. Set to true to require tokens on all requests.

OIDC_ISSUER

Yes1

 — 

OIDC provider issuer URL, for example https://your-idp.example.com/realms/myrealm.

OIDC_AUDIENCE

Yes1

 — 

Expected aud claim value in access tokens.

1 Required when OIDC_AUTH_ENABLED=true.

Production Considerations

Agent Memory normalizes host.docker.internal to localhost when comparing the issuer URL in a token against OIDC_ISSUER. This means tokens issued with either hostname validate against the other. In production, always set OIDC_ISSUER to the real public issuer URL. Never use localhost or host.docker.internal.

Troubleshooting

If you encounter an error when setting up authentication for your Agent Memory instance, use the following information to help troubleshoot:

Error Cause Solution

"OIDC provider not initialized"

Auth is enabled but OIDC discovery failed at startup. Agent Memory retries discovery 3 times with exponential backoff, then exits the container. A transient network issue at container start can trigger this, not only a misconfigured issuer URL.

Verify that OIDC_ISSUER is reachable over HTTPS and exposes /.well-known/openid-configuration. Check that the network path from the container to your IdP is available when the container starts. If you use an orchestrator such as Docker Compose or Kubernetes, configure a restart policy so the container restarts automatically on failure.

"Token has expired"

The token’s exp claim is in the past.

Obtain a fresh access token from your IdP.

"Invalid token claims"

iss or aud in the token does not match OIDC_ISSUER or OIDC_AUDIENCE.

Decode your token with echo $TOKEN | cut -d'.' -f2 | base64 -d | jq . and compare the claims against your environment variables.

"Unknown signing key"

A token arrived with a kid (key ID) not present in the cached JWKS.

Agent Memory re-fetches the JWKS once on encountering an unknown kid. If the issue persists, the IdP may have rotated key material while reusing the same kid — a rotation pattern Agent Memory cannot detect automatically. Restart Agent Memory to force a fresh JWKS fetch.

"ID tokens are not accepted"

An ID token was used instead of an access token.

Use the access_token field from the /token response, not id_token.

Next Steps