Microsoft Entra ID OAuth

Azure AD can be configured from Admin Settings or with Admin Server environment variables. Azure AD OAuth has two parts:

An Azure app registration in Microsoft Entra ID.
FalkorDB Enterprise OAuth settings, stored in Admin Settings and Kubernetes Secrets.

Prerequisites

FalkorDB Enterprise is installed and the Admin UI is reachable.
You can sign in as an admin with the settings.update permission.
You know the public URL users use to reach the Admin UI, for example https://admin.example.com.
You can create or update an app registration in Microsoft Entra ID.
For group-based role mapping, you can grant Microsoft Graph application permissions and admin consent.

Create the Azure app registration

Open the Microsoft Entra admin center.
Go to Identity > Applications > App registrations.
Select New registration.
Enter a name, for example FalkorDB Enterprise Admin.
Choose the supported account type for your organization.
Under Redirect URI, choose Web and add:

https://admin.example.com/api/auth/oauth/azure/callback

Replace https://admin.example.com with the public Admin UI origin for your installation.

Save the app registration.
Copy the Application (client) ID and Directory (tenant) ID.
Open Certificates & secrets and create a new client secret.
Copy the client secret value immediately. Azure shows it only once.

Configure API permissions

For basic login, the app needs delegated Microsoft Graph permissions:

Permission	Type	Purpose
`User.Read`	Delegated	Read the signed-in user’s profile from Microsoft Graph.
`openid`	Delegated	Request OpenID Connect identity.
`email`	Delegated	Request the user’s email claim when available.
`profile`	Delegated	Request basic profile claims.
`offline_access`	Delegated	Allow refresh tokens.

For group-based role mapping, add Microsoft Graph application permissions and grant admin consent:

Permission	Type	Purpose
`GroupMember.Read.All`	Application	Read group memberships for users.
`Group.Read.All` or `Directory.Read.All`	Application	Read group metadata when listing or validating groups.

After adding permissions, select Grant admin consent for the tenant.

Configure Azure AD in the Admin UI

Sign in to the Admin UI as an admin.
Open System Settings.
Open OAuth / SSO.
Expand the Azure AD provider card.
Fill in the Azure OAuth fields:

Field	Value
Azure Client ID	Application client ID from the app registration.
Tenant ID	Directory tenant ID from Microsoft Entra ID.
Azure Client Secret Secret	Kubernetes Secret name that will store the OAuth client secret, for example `azure-oauth-client-secret`.
Azure Redirect URI	The same redirect URI registered in the app registration, for example `https://admin.example.com/api/auth/oauth/azure/callback`.
Azure Client Secret	Paste the Azure client secret value. This value is write-only and is not shown again after saving.

Configure sign-in policy fields as needed:

Field	Purpose
Allowed Domains	Comma-separated email domains allowed to sign in. Leave empty to allow any Azure AD account accepted by the app registration.
Auto-Onboard OAuth Users	Creates a FalkorDB Enterprise user on first successful OAuth login.
Strict Role Attribute Matching	Rejects OAuth logins if the configured role claim is missing or unknown.
Role Attribute Path	JMESPath expression for reading a role from the OAuth profile, when role claims are used.

Select Save Settings.

The Admin Server stores client_id, tenant_id, redirect_uri, and client_secret_secret_ref in Admin Settings. The client secret itself is written to the referenced Kubernetes Secret under the client_secret key.

Configure with the API

You can also configure Azure AD OAuth through the settings API. Authenticate as an admin first, then send a PATCH request to /api/settings/.

curl -X PATCH 'https://admin.example.com/api/settings/' \
  -H 'Content-Type: application/json' \
  -H 'Cookie: token=<session-cookie>' \
  --data @- <<'JSON'
{
  "features": {
    "self_service_onboarding": true
  },
  "oauth": {
    "allowed_domains": ["example.com"],
    "role_attribute_strict": false
  },
  "azure_oauth": {
    "client_id": "00000000-0000-0000-0000-000000000000",
    "tenant_id": "11111111-1111-1111-1111-111111111111",
    "redirect_uri": "https://admin.example.com/api/auth/oauth/azure/callback",
    "client_secret_secret_ref": "azure-oauth-client-secret",
    "client_secret": "replace-with-azure-client-secret"
  }
}
JSON

Configure with Kubernetes Secrets and ConfigMap

Create the OAuth client secret:

kubectl -n falkordb-system create secret generic azure-oauth-client-secret \
  --from-literal=client_secret='replace-with-azure-client-secret'

Then patch Admin Settings with the public Azure metadata:

kubectl -n falkordb-system patch configmap falkordb-admin-settings --type merge -p "$(cat <<'JSON'
{
  "data": {
    "settings.json": "{\n  \"features\": {\n    \"oauth2_enabled\": true,\n    \"local_users_enabled\": true,\n    \"self_service_onboarding\": true,\n    \"multi_cluster_mode\": false,\n    \"backup_auto_schedule\": true,\n    \"metrics_collection\": true,\n    \"api_docs_enabled\": true\n  },\n  \"oauth\": {\n    \"allowed_domains\": [\"example.com\"],\n    \"role_attribute_strict\": false\n  },\n  \"azure_oauth\": {\n    \"client_id\": \"00000000-0000-0000-0000-000000000000\",\n    \"tenant_id\": \"11111111-1111-1111-1111-111111111111\",\n    \"redirect_uri\": \"https://admin.example.com/api/auth/oauth/azure/callback\",\n    \"client_secret_secret_ref\": \"azure-oauth-client-secret\"\n  },\n  \"retention\": {\n    \"audit_log_retention_days\": 90,\n    \"metrics_retention_days\": 30\n  },\n  \"metrics\": {\n    \"prometheus_port\": 9121\n  },\n  \"ui\": {}\n}"
  }
}
JSON
)"

Prefer the Admin UI or settings API when possible; they preserve existing settings and avoid replacing the full settings.json document by hand.

Configure with environment variables

Azure AD OAuth can also be configured with Admin Server environment variables. This is useful for local development or simple deployments:

OAUTH_PROVIDER=azure
AZURE_CLIENT_ID=00000000-0000-0000-0000-000000000000
AZURE_CLIENT_SECRET=replace-with-azure-client-secret
AZURE_TENANT_ID=11111111-1111-1111-1111-111111111111
AZURE_REDIRECT_URI=http://localhost:3000/api/auth/oauth/azure/callback

Settings configured in the Admin UI are preferred for Azure AD OAuth at request time. Environment variables remain a fallback when settings-backed Azure AD OAuth is not configured.

Configure with Helm

For Helm-based deployments, set the Azure values on install or upgrade:

adminServer:
  secret:
    azureClientId: "00000000-0000-0000-0000-000000000000"
    azureClientSecret: "replace-with-azure-client-secret"
  env:
    oauthProvider: azure
    azureTenantId: "11111111-1111-1111-1111-111111111111"
    azureRedirectUri: "https://admin.example.com/api/auth/oauth/azure/callback"

Start the OAuth flow from a browser:

https://admin.example.com/api/auth/oauth/azure

Do not start from the raw Microsoft authorization URL during manual testing. The FalkorDB Enterprise OAuth endpoint sets the CSRF state cookie required by the callback. After a successful login, the Admin UI should show a Continue with Azure AD button whenever Azure AD is configured and OAuth login is enabled.

Rotate the client secret

To rotate the Azure client secret:

Create a new client secret in the Azure app registration.
Open System Settings > OAuth / SSO.
Expand Azure AD.
Keep the same Secret reference or enter a new Secret name.
Paste the new value in Azure Client Secret.
Select Save Settings.

Troubleshooting

Symptom	Check
Azure AD provider does not appear on the login page	Confirm `azure_oauth.client_id`, `azure_oauth.tenant_id`, and `azure_oauth.client_secret_secret_ref` are saved, or that `AZURE_CLIENT_ID`, `AZURE_CLIENT_SECRET`, and `AZURE_TENANT_ID` are set.
OAuth callback returns `Invalid state parameter`	Start the flow at `/api/auth/oauth/azure`, not directly at Microsoft.
Microsoft returns a redirect URI mismatch	Confirm the Azure app registration contains the exact `/api/auth/oauth/azure/callback` URL used by FalkorDB Enterprise.
Login works but group role mapping fails	Confirm Microsoft Graph application permissions are granted and admin consent was completed.
Secret reference is saved but login fails	Confirm the referenced Secret exists in the FalkorDB Enterprise namespace and contains `client_secret`.

Get started

Install

Authentication

Deploy databases

Operations

Upgrade and uninstall

Troubleshooting

Prerequisites

Create the Azure app registration

Configure API permissions

Configure Azure AD in the Admin UI

Configure with the API

Configure with Kubernetes Secrets and ConfigMap

Configure with environment variables

Configure with Helm

Rotate the client secret

Troubleshooting

​Prerequisites

​Create the Azure app registration

​Configure API permissions

​Configure Azure AD in the Admin UI

​Configure with the API

​Configure with Kubernetes Secrets and ConfigMap

​Configure with environment variables

​Configure with Helm

​Test the login flow

​Rotate the client secret

​Troubleshooting

Prerequisites

Create the Azure app registration

Configure API permissions

Configure Azure AD in the Admin UI

Configure with the API

Configure with Kubernetes Secrets and ConfigMap

Configure with environment variables

Configure with Helm

Test the login flow

Rotate the client secret

Troubleshooting