Authentication

By default Phoenix deploys with authentication disabled as you may be just trying Phoenix for the very first time or have Phoenix deployed in a VPC. However you might want to further protect access to your data via authentication. Below are the steps.

Setup#

To enable authentication on your Phoenix, you will have to set two environment variables:

The following environment variables are optional but recommended:

Deploy Phoenix with the above environment variables set. You will know that you have setup authentication correctly if the UI navigates to to a login screen.

By default Phoenix will create an admin user account. To get started:

1. Log in as the admin user. The email should be admin@localhost and the password will be admin
2. Set a new password for admin. You will be prompted to set a new password. Use a sufficiently complex password and save it in a safe place.
3. Go to the settings page on the left nav and create your first system API key. This API key can be used to log traces, use the Phoenix client, and programmatically hit Phoenix’s APIs. Store the system API key in a safe place.
4. In your application code, make sure to set the proper authentication headers with the system API key. Phoenix respects headers in the form of bearer auth, meaning that you should set the header in the form Authorization: Bearer <token>. Note that if you are using the Phoenix Client or Phoenix Otel, you simply need to set the PHOENIX_API_KEY environment variable.

Re-deploy your application with the API key created above and you will see traces stream in as before.

docker run \  -e PHOENIX_ENABLE_AUTH=true \  -e PHOENIX_SECRET=change-me-32chars-min1digit1lower \  -e PHOENIX_DEFAULT_ADMIN_INITIAL_PASSWORD='strong-admin-password' \  -p 6006:6006 arizephoenix/phoenix:latest

Password Policy#

By default, Phoenix requires passwords to be a minimum of 4 characters long. For deployments that need stricter security, you can enable a strong password policy by setting the PHOENIX_ENABLE_STRONG_PASSWORD_POLICY environment variable to True.

When the strong password policy is enabled, passwords must meet all of the following requirements:

• At least 12 characters long
• At least one uppercase letter
• At least one lowercase letter
• At least one number
• At least one special character (!@#$%^&*()_+)

export PHOENIX_ENABLE_STRONG_PASSWORD_POLICY=True

Brute Force Login Protection#

Phoenix includes built-in brute force login protection that temporarily locks accounts after repeated failed login attempts. By default, after 5 failed attempts, the account is locked out for 5 minutes.

• PHOENIX_BRUTE_FORCE_LOGIN_PROTECTION_MAX_ATTEMPTS: Maximum number of failed login attempts before temporary lockout. Defaults to 5.
• PHOENIX_DISABLE_BRUTE_FORCE_LOGIN_PROTECTION: Set to true to disable brute force login protection entirely. Defaults to false.

# Increase max attempts before lockoutexport PHOENIX_BRUTE_FORCE_LOGIN_PROTECTION_MAX_ATTEMPTS=10

User Management#

Users can be added and removed from a Phoenix instance with authentication enabled. Users have one of three roles: admin, member, or viewer. See permissions below to learn more about the permissions for each role.

Only admins can manage phoenix users. They can add, delete, and reset the passwords of other users. To manage users go to the /settings page.

Permissions#

This section outlines the specific actions that users can perform based on their assigned roles within the system: Admin, Member, and Viewer. The permission matrix is divided into two main categories:

• Mutations: Operations that allow users to create, update, or delete data within the system.
• Queries: Operations that enable users to retrieve or view data from the system.

Mutations#

Mutations are operations that enable users to create, update, or delete data within the system. This permission matrix ensures that only authorized roles can execute sensitive actions, such as managing users and API keys, while allowing members to perform essential account-related updates like changing their own passwords and usernames. Viewers have read-only access and cannot perform mutations.

Queries#

Queries are operations that allow users to retrieve and view data from the system.

REST API Permissions (v1/ endpoints)#

For programmatic access via REST API endpoints (paths beginning with /v1/), permissions are determined by both the user’s role and the HTTP method used:

API Keys#

There are two kinds of API keys in Phoenix: system and user.

System Keys#

System keys act on behalf of the system as a whole rather than any particular user. They can only be created by admins, are not meaningfully associated with the admin who creates them except for auditing purposes, and do not disappear if that admin is deleted. A system key would be the recommended kind of key to use in programmatic interactions with Phoenix that do not involve a user (e.g., automated flows querying our REST APIs).

Creating a system key requires an admin access-token session or PHOENIX_ADMIN_SECRET, on both REST and GraphQL. API keys cannot mint additional keys.

User Keys#

User API keys are associated with and act on behalf of the user to which they are issued. That user has the ability to view and delete their own user keys, and if the user is deleted, so are all of their associated user keys. A user might create their own user key into order to run an experiment in a notebook, for example.

Creating a user key requires an access-token session, on both REST and GraphQL; an existing API key cannot mint a replacement. Through Phoenix 18, GraphQL allowed API-key-authenticated issuance for backward compatibility; as of Phoenix 19 both surfaces enforce the same non-transitive policy. Workflows that used an API key for unattended key creation must instead provision keys from a logged-in session (for example, the Settings page or a script that authenticates with user credentials).

Setting and Using API Keys with Environment Variables#

Phoenix API keys can be set with the PHOENIX_API_KEY environment variable:

export PHOENIX_API_KEY=<SYSTEM-OR-USER-KEY>

If authentication is enabled on Phoenix, all interactions with the server need to include an authorization header. Phoenix will read the PHOENIX_API_KEY environment variable, and automatically include it as an authorization header. Interactions with Phoenix include:

• Using phoenix.Client
• Running experiments
• Sending OpenInference traces (more details below)

Sending OpenInference traces#

API Keys also need to be included on OpenInference traces sent to the Phoenix server. If you’ve set the PHOENIX_API_KEY environment variable, the phoenix.otel module will automatically include an authorization header with the API key:

from phoenix.otel import registertracer_provider = register()

Alternatively, you can explicitly set the authorization header on the exporter if using OpenTelemetry primitives directly.

from opentelemetry.exporter.otlp.proto.http.trace_exporter import OTLPSpanExporterfrom opentelemetry.sdk import trace as trace_sdkfrom opentelemetry.sdk.trace.export import ConsoleSpanExporter, SimpleSpanProcessorendpoint = "http://127.0.0.1:6006/v1/traces"tracer_provider = trace_sdk.TracerProvider()exporter = OTLPSpanExporter(    endpoint,    headers={"authorization": "Bearer <SYSTEM-OR-USER-KEY>"},)tracer_provider.add_span_processor(SimpleSpanProcessor(exporter))

Agent Authentication Discovery#

Phoenix serves three discovery endpoints so AI agents can learn how to authenticate against a deployed instance. All are always available and require no configuration:

• GET /auth.md — a human- and agent-readable Markdown guide describing this deployment’s auth model. When authentication is disabled it states that all endpoints are public; when enabled it directs the caller to create an API key under Settings → API Keys and send an Authorization: Bearer <token> header. It follows the auth.md convention.
• GET /.well-known/oauth-protected-resource — RFC 9728 Protected Resource Metadata (JSON), advertising the resource, that bearer tokens are sent in the header, and a link to /auth.md.
• GET /.well-known/oauth-protected-resource/mcp — the same RFC 9728 metadata scoped to the built-in MCP server, advertising /mcp as the protected resource so MCP clients can discover how to authenticate against it. It is served only when the MCP server is mounted at /mcp (the default) and otherwise responds 404.

When authentication is enabled, 401 Unauthorized responses include a WWW-Authenticate header pointing at the Protected Resource Metadata endpoint, giving agents a stable entry point for discovering how to authenticate. When the OAuth2 authorization server is enabled, the metadata also advertises it, so OAuth-capable clients (such as MCP clients) can log in interactively; other clients are provisioned out of band with API keys, and access is always governed by the role of the user the credential belongs to.

OAuth2 Authorization Server#

When authentication is enabled, Phoenix also acts as its own OAuth2 authorization server so that interactive clients — MCP clients like Claude Code and Cursor connecting to the Remote MCP Server, and the Phoenix CLI — can log in through the browser instead of handling long-lived API keys. The flow is standard authorization code with PKCE: clients register via RFC 7591 dynamic client registration, discover endpoints via RFC 8414 server metadata, and a token is minted only after a logged-in user approves the consent page. Tokens are audience-bound to the resource they were minted for and carry the permissions of the approving user.

Registration alone grants no authority: an authorization code is delivered only to the exact registered redirect URI, PKCE binds the exchange to the flow’s initiator, and nothing is issued without a logged-in user’s consent. The defaults are designed to work out of the box with MCP clients in the wild; the variables below let you tighten or disable the surface.

Password Recovery#

With SMTP (Simple Mail Transfer Protocol)#

Using SMTP ensures that your password recovery emails are delivered reliably and securely. SMTP is the standard protocol for sending emails, making sure that you receive the reset link promptly in your inbox.

Below is an example configuration to enable SMTP for sendgrid.

export PHOENIX_SMTP_HOSTNAME=smtp.sendgrid.netexport PHOENIX_SMTP_USERNAME=apikeyexport PHOENIX_SMTP_PASSWORD=XXXXXXXXXXXXXXXXX

Without SMTP#

If SMTP is not configured, you have a few options to recover your forgotten password:

• Contact an administrator and request that they reset your password. Admins can reset user passwords on the settings page.
• As a last resort, you can manually update the database tuple that contains your password salt and hash.

Configuring OAuth2 Identity Providers#

Phoenix supports login via third-party identity providers (IDPs), including:

• Google
• AWS Cognito
• Microsoft Entra ID (previously known as Azure Active Directory)
• IDPs that support OpenID Connect and a well-known configuration endpoint at GET /.well-known/openid-configuration

Phoenix uses the OAuth2 authorization code flow for web applications, which requires setting a few environment variables in addition to PHOENIX_ENABLE_AUTH and PHOENIX_SECRET:

Optional OAuth2 Configuration#

The following optional environment variables provide additional control over OAuth2 authentication behavior:

Where Phoenix Reads Group and Role Claims#

GROUPS_ATTRIBUTE_PATH and ROLE_ATTRIBUTE_PATH are evaluated against the claims Phoenix receives at login as an OpenID Connect client: the verified ID token and the UserInfo response. Phoenix checks the ID token first and, when a configured claim is missing there, fetches the UserInfo endpoint and checks the response.

Keeping authorization claims off the ID token. If your security policy is to keep authorization data out of the ID token, the UserInfo response is a fully supported target. Configure your IdP to return the group/role claim from UserInfo (rather than embedding it in every ID token), request the appropriate scope, and point GROUPS_ATTRIBUTE_PATH / ROLE_ATTRIBUTE_PATH at the claim. When a configured claim is absent from the ID token, Phoenix fetches UserInfo with the access token during login, so a claim exposed only through UserInfo is still picked up — with no access-token decoding involved.

Provider claim configuration. Exposing the claim is done in your IdP’s console. Common starting points (consult each provider’s current docs for exact steps):

• Okta — request the groups scope from Phoenix (PHOENIX_OAUTH2_OKTA_SCOPES=groups) and add a groups claim. On the org authorization server, configure the app’s Groups claim and filter; on a custom authorization server, add the claim under Security → API → Authorization Servers → (your server) → Claims. To return the claim through UserInfo (instead of forcing it into every ID token), choose the Userinfo/id_token request option. See Okta’s groups claim guide and custom claims docs.
• Auth0 — add a namespaced custom claim to the ID token from a Post-Login Action with api.idToken.setCustomClaim(...).
• Microsoft Entra ID (Azure AD) — configure the optional groups claim (or app-role roles) in the app registration’s Token configuration, with handling for group overage on large group lists.
• Keycloak — add a Group Membership or role mapper to the client or client scope with Add to ID token and/or Add to userinfo enabled.

Multiple Identity Providers#

You can configure multiple IDPs simultaneously by setting environment variables for each provider with different IDP identifiers. Users will see all configured providers as login options on the Phoenix login page. Each IDP is configured independently with its own set of variables.

Example with both Google and Okta:

# Google OAuthexport PHOENIX_OAUTH2_GOOGLE_CLIENT_ID=google_client_idexport PHOENIX_OAUTH2_GOOGLE_CLIENT_SECRET=google_secretexport PHOENIX_OAUTH2_GOOGLE_OIDC_CONFIG_URL=https://accounts.google.com/.well-known/openid-configuration# Internal Okta with group restrictionsexport PHOENIX_OAUTH2_OKTA_CLIENT_ID=okta_client_idexport PHOENIX_OAUTH2_OKTA_CLIENT_SECRET=okta_secretexport PHOENIX_OAUTH2_OKTA_OIDC_CONFIG_URL=https://your-domain.okta.com/.well-known/openid-configurationexport PHOENIX_OAUTH2_OKTA_GROUPS_ATTRIBUTE_PATH=groupsexport PHOENIX_OAUTH2_OKTA_ALLOWED_GROUPS="engineering,platform-team"

Common OAuth2 Configuration Examples#

Public client with PKCE (no client secret):

export PHOENIX_OAUTH2_MOBILE_CLIENT_ID=mobile_app_idexport PHOENIX_OAUTH2_MOBILE_OIDC_CONFIG_URL=https://auth.example.com/.well-known/openid-configurationexport PHOENIX_OAUTH2_MOBILE_TOKEN_ENDPOINT_AUTH_METHOD=noneexport PHOENIX_OAUTH2_MOBILE_USE_PKCE=true

With nested group path (Keycloak):

export PHOENIX_OAUTH2_KEYCLOAK_GROUPS_ATTRIBUTE_PATH=resource_access.phoenix.rolesexport PHOENIX_OAUTH2_KEYCLOAK_ALLOWED_GROUPS="admin,developer"

With special characters in path (AWS Cognito - quotes REQUIRED):

export PHOENIX_OAUTH2_COGNITO_GROUPS_ATTRIBUTE_PATH='"cognito:groups"'export PHOENIX_OAUTH2_COGNITO_ALLOWED_GROUPS="Administrators,PowerUsers"

With namespaced claims (Auth0 - quotes REQUIRED):

export PHOENIX_OAUTH2_AUTH0_GROUPS_ATTRIBUTE_PATH='"https://myapp.com/groups"'export PHOENIX_OAUTH2_AUTH0_ALLOWED_GROUPS="admin,users"

With array projection (extract names from objects):

export PHOENIX_OAUTH2_CUSTOM_GROUPS_ATTRIBUTE_PATH="teams[*].name"export PHOENIX_OAUTH2_CUSTOM_ALLOWED_GROUPS="engineering,operations"

Single sign-on with auto-login:

export PHOENIX_OAUTH2_COMPANY_DISPLAY_NAME="Company SSO"export PHOENIX_OAUTH2_COMPANY_AUTO_LOGIN=trueexport PHOENIX_OAUTH2_COMPANY_ALLOW_SIGN_UP=false

With custom email attribute path (Azure AD/Entra ID without email claim):

# Use preferred_username (UPN) when email claim is nullexport PHOENIX_OAUTH2_AZURE_AD_EMAIL_ATTRIBUTE_PATH=preferred_username

With role mapping (simple):

export PHOENIX_OAUTH2_OKTA_ROLE_ATTRIBUTE_PATH=roleexport PHOENIX_OAUTH2_OKTA_ROLE_MAPPING="Owner:ADMIN,Developer:MEMBER,Viewer:VIEWER"

With role mapping (nested path for Keycloak):

export PHOENIX_OAUTH2_KEYCLOAK_ROLE_ATTRIBUTE_PATH=resource_access.phoenix.roleexport PHOENIX_OAUTH2_KEYCLOAK_ROLE_MAPPING="admin:ADMIN,user:MEMBER"

With role mapping in strict mode (deny unmapped roles):

export PHOENIX_OAUTH2_OKTA_ROLE_ATTRIBUTE_PATH=roleexport PHOENIX_OAUTH2_OKTA_ROLE_MAPPING="Owner:ADMIN,Developer:MEMBER"export PHOENIX_OAUTH2_OKTA_ROLE_ATTRIBUTE_STRICT=true

With conditional logic to compute role from groups (no mapping needed):

export PHOENIX_OAUTH2_OKTA_ROLE_ATTRIBUTE_PATH="contains(groups[*], 'admin') && 'ADMIN' || contains(groups[*], 'editor') && 'MEMBER' || 'VIEWER'"

With both groups and roles (groups control access, roles control permissions):

export PHOENIX_OAUTH2_OKTA_GROUPS_ATTRIBUTE_PATH=groupsexport PHOENIX_OAUTH2_OKTA_ALLOWED_GROUPS="engineering,platform-team"export PHOENIX_OAUTH2_OKTA_ROLE_ATTRIBUTE_PATH=roleexport PHOENIX_OAUTH2_OKTA_ROLE_MAPPING="Owner:ADMIN,Developer:MEMBER,Guest:VIEWER"

With a fixed role for all users from an IDP

export PHOENIX_OAUTH2_OKTA_GROUPS_ATTRIBUTE_PATH=groupsexport PHOENIX_OAUTH2_OKTA_ALLOWED_GROUPS="engineering,platform-team"export PHOENIX_OAUTH2_OKTA_ROLE_ATTRIBUTE_PATH="'ADMIN'"

With role mapping for provisioning, but admin-managed roles thereafter

# New users are provisioned from their Okta group, but a role set in the Phoenix# UI is never overwritten on subsequent logins.export PHOENIX_OAUTH2_OKTA_ROLE_ATTRIBUTE_PATH=roleexport PHOENIX_OAUTH2_OKTA_ROLE_MAPPING="Owner:ADMIN,Developer:MEMBER,Guest:VIEWER"export PHOENIX_OAUTH2_OKTA_ROLE_RESYNC=false

Detailed instructions for common IDPs are provided below.

Google#

1. In Google Cloud Console, select a GCP project in which to register your Phoenix OAuth2 app.
2. Select APIs and Services.
3. In the Credentials page, click on Create Credentials and select OAuth Client ID.
4. From the Application type dropdown, select Web application.
5. Enter a name for your Phoenix app, which will be displayed to users when signing in.
6. Under Authorized JavaScript origins, click Add URI and enter the origin URL where you will access Phoenix in the browser.
7. Under Authorized redirect URIs, click Add URI. Take the URL from the previous step and append the slug /oauth2/google/tokens. Alternatively, if you have configured a root path via the PHOENIX_HOST_ROOT_PATH environment variable, append a slug of the form /<root-path>/oauth2/google/tokens. Enter the resulting URL.
8. Copy your client ID and client secret.
9. Deploy Phoenix with the three environment variables described above, substituting GOOGLE for <IDP>. The well-known configuration endpoint is https://accounts.google.com/.well-known/openid-configuration.

AWS Cognito#

1. In the AWS Management Console, navigate to the Cognito page.
2. From the User Pools page, select Create User Pool.
3. Under Required attributes, in the Additional required attributes dropdown, select email (you can optionally require name and picture to ensure user profiles have this information in Phoenix).
4. In the Initial app client section:
   1. Under App type, select Confidential client.
   2. Under App client name, enter a name for your Phoenix app.
   3. Under Client secret, ensure Generate a client secret is selected.
5. Create your user pool and navigate to the page for the newly created user pool by clicking on its name.
6. Add at least one user to your user pool in the Users section.
7. Copy and save your user pool ID from the top of the page. The ID should be of the form <region>_<hash>, e.g., us-east-2_x4FTon498.
8. Under App Integration > Domain, create a domain to contain the sign-in page and OAuth2 endpoints.
9. Under App Integration > App client list > App clients and analytics, select your newly created client.
10. Copy and save your client ID and client secret.
11. Under Hosted UI, click Edit. On the Edit Hosted UI page:
    1. Add an Allowed callback URL of the form <origin-url>/oauth2/aws_cognito/tokens, where <origin-url> is the URL where you will access Phoenix in the browser. Alternatively, if you have configured a root path via the PHOENIX_HOST_ROOT_PATH environment variable, your callback URL will have the form <origin-url>/<root-path>/oauth2/aws_cognito/tokens.
    2. In the Identity Providers dropdown, select Cognito user pool.
    3. Under OAuth 2.0 grant types, select Authorization code grant.
    4. Under OpenID Connect scopes, select OpenID, Email, and Profile.
    5. Save your changes.
12. The well-known configuration endpoint is of the form https://cognito-idp.<region>.amazonaws.com/<user-pool-id>/.well-known/openid-configuration, where the user pool ID was copied in a previous step and the region is the first part of the user pool ID preceding the underscore. Test this URL in your browser to ensure it is correct before proceeding to the next step.
13. Deploy Phoenix using the three environment variables described above, substituting AWS_COGNITO for <IDP>.

Microsoft Entra ID#

1. From the Azure portal, navigate to Microsoft Entra ID.
2. Select Add > App Registration.
3. On the Register an Application page:
   1. Enter a name for your application.
   2. Under Redirect URI, in the Select a platform dropdown, select Web and a redirect URI of the form <origin-url>/oauth2/microsoft_entra_id/tokens, where <origin-url> is the URL where you will access Phoenix in the browser. Alternatively, if you have configured a root path via the PHOENIX_HOST_ROOT_PATH environment variable, your redirect URI will have the form <origin-url>/<root-path>/oauth2/microsoft_entra_id/tokens.
4. Copy and save the Application (client) ID.
5. Under Endpoints, copy and save the well-known configuration endpoint under OpenID Connect metadata document.
6. Under Client credentials, click Add a certificate or secret. Create a client secret and copy and save its value.
7. Deploy Phoenix using the three environment variables described above, substituting MICROSOFT_ENTRA_ID for <IDP>.

Workload identity without a client secret#

On Kubernetes, Phoenix can authenticate to Entra ID with the pod’s projected service account token instead of a client secret, so no long-lived credential exists to store or rotate. Entra trusts the cluster’s OIDC issuer through a federated credential, and Phoenix relays the projected token as a client assertion (RFC 7523 §2.2).

This replaces step 6 above — create no client secret.

1. Install the Azure Workload Identity webhook on the cluster.

2. On the app registration, under Certificates & secrets → Federated credentials, add a credential of scenario Kubernetes accessing Azure resources:

   • Cluster issuer URL — your AKS OIDC issuer, from az aks show --query oidcIssuerProfile.issuerUrl.
   • Namespace and Service account name — where Phoenix runs.
   • Subject identifier — system:serviceaccount:<namespace>:<serviceAccountName>.

3. Label the Phoenix pods so the webhook projects a token into them. With the Helm chart:

   deployment:  podLabels:    azure.workload.identity/use: "true"

4. Configure the provider with no secret:

   export PHOENIX_OAUTH2_MICROSOFT_ENTRA_ID_CLIENT_ID=entra_client_idexport PHOENIX_OAUTH2_MICROSOFT_ENTRA_ID_OIDC_CONFIG_URL=https://login.microsoftonline.com/<tenant-id>/v2.0/.well-known/openid-configurationexport PHOENIX_OAUTH2_MICROSOFT_ENTRA_ID_TOKEN_ENDPOINT_AUTH_METHOD=client_assertion_jwtexport PHOENIX_OAUTH2_MICROSOFT_ENTRA_ID_CLIENT_ASSERTION_FILE_ENV_VAR=AZURE_FEDERATED_TOKEN_FILE

   AZURE_FEDERATED_TOKEN_FILE is exported by the webhook and holds the path to the projected token. Phoenix is given the variable’s name rather than the path, because the webhook owns that location and has moved it between releases.

At startup Phoenix logs which variable each provider resolved through:

OAuth2 IDP microsoft_entra_id: client assertion path resolved from AZURE_FEDERATED_TOKEN_FILE

If the pod label is missing the webhook projects nothing, and startup fails with a message naming both the variable and the label.

Keycloak#

1. From the Keycloak Console create a new Realm or skip this part if you want to reuse a existing Realm
2. Select Clients.
3. Click on new Client
   1. Enter the Client ID phoenix
   2. Enter the Name Phoenix Client
   3. Enter below Root URL the root url of your phoenix instance, like https://example.com/subpath/subpath
   4. Enter below Home URL the home url of your phoenix instance, like /subpath/subpath
   5. Enter below Valid redirect URIs a redirect url to your phoenix instance, like https://example.com/subpath/subpath/*
   6. Enter below Valid post logout redirect URIs +
   7. Enter below Web origins your url, like https://example.com
   8. Enter below Admin URL your admin url, like https://example.com/subpath/subpath/
   9. Enable Client authentication
   10. Ensure that only Standard flow and Direct access grants is enabled
   11. Hit the Save button
4. Go to the Client phoenix and to the tab credentials and copy the client-secret
5. Deploy Phoenix using the three environment variables described above, substituting KEYCLOAK for <IDP>:

PHOENIX_OAUTH2_KEYCLOAK_CLIENT_ID=""PHOENIX_OAUTH2_KEYCLOAK_OIDC_CONFIG_URL="https://<your-keycloak-domain>/realms/<your-realm>/.well-known/openid-configuration"PHOENIX_OAUTH2_KEYCLOAK_CLIENT_SECRET=""

Other Identity Providers#

Phoenix can integrate with any OAuth2 IDP that supports OpenID Connect and has a well-known configuration endpoint. Detailed instructions will vary by IDP, but the general steps remain the same:

1. Register a Phoenix client application with your IDP. If prompted to select an application type, select traditional web application or a similarly named application type that allows you to generate a client secret in addition to a client ID.
2. Find the well-known configuration endpoint for your IDP.
3. Deploy Phoenix with the environment variables described above, substituting <IDP> with your IDP name, e.g., AUTH0. If you have configured a root path via the PHOENIX_HOST_ROOT_PATH environment variable, ensure that the root path is included in the path of your callback URL.
4. Use the optional configuration variables documented above to customize behavior such as display names, sign-up policies, group-based access control, and more.

Configuring LDAP Authentication#

Phoenix supports authentication against LDAP directories, including:

• Microsoft Active Directory
• OpenLDAP
• 389 Directory Server
• Any LDAP v3 compliant directory

LDAP authentication allows users to log in with their corporate directory credentials, enabling centralized user management and integration with existing identity infrastructure.

Required LDAP Configuration#

To enable LDAP authentication, set the following environment variables in addition to PHOENIX_ENABLE_AUTH and PHOENIX_SECRET:

Optional LDAP Configuration#

# Example: LDAP without email (Active Directory)export PHOENIX_LDAP_ATTR_EMAIL=nullexport PHOENIX_LDAP_ATTR_UNIQUE_ID=objectGUIDexport PHOENIX_LDAP_ALLOW_SIGN_UP=trueexport PHOENIX_LDAP_GROUP_ROLE_MAPPINGS='[{"group_dn":"CN=Phoenix Admins,OU=Groups,DC=corp,DC=com","role":"ADMIN"},{"group_dn":"*","role":"MEMBER"}]'

# Example: LDAP without email (OpenLDAP)export PHOENIX_LDAP_ATTR_EMAIL=nullexport PHOENIX_LDAP_ATTR_UNIQUE_ID=entryUUIDexport PHOENIX_LDAP_ALLOW_SIGN_UP=trueexport PHOENIX_LDAP_GROUP_ROLE_MAPPINGS='[{"group_dn":"cn=admins,ou=groups,dc=example,dc=com","role":"ADMIN"},{"group_dn":"*","role":"MEMBER"}]'

Active Directory Configuration Example#

# Enable authenticationexport PHOENIX_ENABLE_AUTH=trueexport PHOENIX_SECRET=your-secret-key-at-least-32-chars# LDAP server connectionexport PHOENIX_LDAP_HOST=ldap.corp.example.comexport PHOENIX_LDAP_PORT=389export PHOENIX_LDAP_TLS_MODE=starttls# Service account for LDAP queriesexport PHOENIX_LDAP_BIND_DN="CN=svc-phoenix,OU=Service Accounts,DC=corp,DC=example,DC=com"export PHOENIX_LDAP_BIND_PASSWORD="service-account-password"# User search configurationexport PHOENIX_LDAP_USER_SEARCH_BASE_DNS='["OU=Users,DC=corp,DC=example,DC=com"]'export PHOENIX_LDAP_USER_SEARCH_FILTER="(&(objectClass=user)(sAMAccountName=%s))"# Attribute mappingexport PHOENIX_LDAP_ATTR_EMAIL=mailexport PHOENIX_LDAP_ATTR_DISPLAY_NAME=displayNameexport PHOENIX_LDAP_ATTR_MEMBER_OF=memberOf# Group to role mappingexport PHOENIX_LDAP_GROUP_ROLE_MAPPINGS='[{"group_dn":"CN=Phoenix Admins,OU=Groups,DC=corp,DC=example,DC=com","role":"ADMIN"},{"group_dn":"CN=Phoenix Users,OU=Groups,DC=corp,DC=example,DC=com","role":"MEMBER"},{"group_dn":"*","role":"VIEWER"}]'

OpenLDAP Configuration Example#

# Enable authenticationexport PHOENIX_ENABLE_AUTH=trueexport PHOENIX_SECRET=your-secret-key-at-least-32-chars# LDAP server connectionexport PHOENIX_LDAP_HOST=ldap.example.comexport PHOENIX_LDAP_PORT=636export PHOENIX_LDAP_TLS_MODE=ldaps# Service account for LDAP queriesexport PHOENIX_LDAP_BIND_DN="cn=readonly,dc=example,dc=com"export PHOENIX_LDAP_BIND_PASSWORD="readonly-password"# User search configurationexport PHOENIX_LDAP_USER_SEARCH_BASE_DNS='["ou=people,dc=example,dc=com"]'export PHOENIX_LDAP_USER_SEARCH_FILTER="(&(objectClass=inetOrgPerson)(uid=%s))"# Attribute mappingexport PHOENIX_LDAP_ATTR_EMAIL=mailexport PHOENIX_LDAP_ATTR_DISPLAY_NAME=cn# POSIX group search (when memberOf overlay is not available)# Setting PHOENIX_LDAP_GROUP_SEARCH_FILTER enables group search mode instead of reading memberOfexport PHOENIX_LDAP_GROUP_SEARCH_BASE_DNS='["ou=groups,dc=example,dc=com"]'export PHOENIX_LDAP_GROUP_SEARCH_FILTER="(&(objectClass=posixGroup)(memberUid=%s))"# PHOENIX_LDAP_GROUP_SEARCH_FILTER_USER_ATTR not set - uses login username by default# This works because POSIX memberUid contains usernames (e.g., "jdoe"), not full DNs# Group to role mappingexport PHOENIX_LDAP_GROUP_ROLE_MAPPINGS='[{"group_dn":"cn=admins,ou=groups,dc=example,dc=com","role":"ADMIN"},{"group_dn":"*","role":"MEMBER"}]'

Active Directory with Nested Groups#

For Active Directory environments using nested groups with the member attribute (which contains full DNs):

# Enable authenticationexport PHOENIX_ENABLE_AUTH=trueexport PHOENIX_SECRET=your-secret-key-at-least-32-chars# LDAP server connectionexport PHOENIX_LDAP_HOST=ldap.corp.example.comexport PHOENIX_LDAP_TLS_MODE=starttls# Service accountexport PHOENIX_LDAP_BIND_DN="CN=svc-phoenix,OU=Service Accounts,DC=corp,DC=example,DC=com"export PHOENIX_LDAP_BIND_PASSWORD="service-account-password"# User searchexport PHOENIX_LDAP_USER_SEARCH_BASE_DNS='["OU=Users,DC=corp,DC=example,DC=com"]'export PHOENIX_LDAP_USER_SEARCH_FILTER="(&(objectClass=user)(sAMAccountName=%s))"# Nested group search using LDAP_MATCHING_RULE_IN_CHAIN (AD-specific OID)# The member attribute contains full DNs, so we need distinguishedNameexport PHOENIX_LDAP_GROUP_SEARCH_BASE_DNS='["DC=corp,DC=example,DC=com"]'export PHOENIX_LDAP_GROUP_SEARCH_FILTER="(member:1.2.840.113556.1.4.1941:=%s)"export PHOENIX_LDAP_GROUP_SEARCH_FILTER_USER_ATTR="distinguishedName"# Group to role mappingexport PHOENIX_LDAP_GROUP_ROLE_MAPPINGS='[{"group_dn":"CN=Phoenix Admins,OU=Groups,DC=corp,DC=example,DC=com","role":"ADMIN"},{"group_dn":"*","role":"VIEWER"}]'

LDAP with Multiple Servers (Failover)#

For high availability, configure multiple LDAP servers:

export PHOENIX_LDAP_HOST="dc1.corp.com,dc2.corp.com,dc3.corp.com"

Phoenix will try each server in order until a successful connection is established.

LDAP with Custom CA Certificate#

When your LDAP server uses a certificate signed by an internal CA:

export PHOENIX_LDAP_TLS_CA_CERT_FILE=/etc/ssl/certs/internal-ca.pem

LDAP with Mutual TLS (Client Certificates)#

For environments requiring client certificate authentication:

export PHOENIX_LDAP_TLS_CLIENT_CERT_FILE=/etc/ssl/certs/phoenix-client.crtexport PHOENIX_LDAP_TLS_CLIENT_KEY_FILE=/etc/ssl/private/phoenix-client.key

Disabling Password Authentication (LDAP-Only)#

To require all users to authenticate via LDAP and disable local password authentication:

export PHOENIX_DISABLE_BASIC_AUTH=trueexport PHOENIX_LDAP_HOST=ldap.corp.example.comexport PHOENIX_LDAP_USER_SEARCH_BASE_DNS='["OU=Users,DC=corp,DC=example,DC=com"]'export PHOENIX_LDAP_ATTR_EMAIL=mailexport PHOENIX_LDAP_GROUP_ROLE_MAPPINGS='[{"group_dn":"*","role":"MEMBER"}]'# ... other LDAP settings

Advanced Authentication Configuration#

The following optional environment variables provide additional control over authentication behavior for advanced use cases: