Skip to content

Auth Mode Management

AgentCube supports two authentication modes that can be switched via environment variable configuration.

Modes

Mode Variable Description
Basic AGENTCUBE_AUTH_MODE=basic (or not set) Service account — all requests use shared credentials
OIDC AGENTCUBE_AUTH_MODE=oidc Per-user SSO — each user authenticates individually

Switching from Basic to OIDC

  1. Complete the SSO setup prerequisites:
  2. Add the OIDC environment variables (see Environment Variables)
  3. Set AGENTCUBE_AUTH_MODE=oidc
  4. Restart the container (environment variable changes require a restart)
  5. Verify with curl https://{connector_hostname}/health — auth_mode should show oidc

Tip

You can keep the basic auth credentials (ESSBASE_USERNAME, etc.) in the environment even after switching to OIDC. They are ignored when AGENTCUBE_AUTH_MODE=oidc is set, and having them available makes it easy to switch back if needed.

Switching from OIDC to Basic

  1. Set AGENTCUBE_AUTH_MODE=basic (or remove the variable entirely)
  2. Ensure basic auth credentials are configured (ESSBASE_USERNAME/ESSBASE_PASSWORD or PLANNING_USERNAME/PLANNING_PASSWORD)
  3. Restart the container
  4. Verify with the health endpoint — auth_mode should show basic

Behavior Differences

Aspect Basic Mode OIDC Mode
User identity Service account Per-user corporate SSO
Data access Same for all users Oracle security profiles per user
Health check backend test Tests connectivity using service account Cannot test without user context (backend_connected: null)
AI platform setup No OAuth configuration needed OAuth flow on first connection
Container restart impact Immediate reconnection Users re-authenticate on next request