You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Copy file name to clipboardExpand all lines: docs/section-self-hosting/features/authentication.md
+141Lines changed: 141 additions & 0 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -407,6 +407,147 @@ Phoenix can integrate with any OAuth2 IDP that supports OpenID Connect and has a
407
407
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.
408
408
4. Use the optional configuration variables documented above to customize behavior such as display names, sign-up policies, group-based access control, and more.
409
409
410
+
## Configuring LDAP Authentication
411
+
412
+
Phoenix supports authentication against LDAP directories, including:
413
+
414
+
* Microsoft Active Directory
415
+
* OpenLDAP
416
+
* 389 Directory Server
417
+
* Any LDAP v3 compliant directory
418
+
419
+
LDAP authentication allows users to log in with their corporate directory credentials, enabling centralized user management and integration with existing identity infrastructure.
420
+
421
+
{% hint style="info" %}
422
+
LDAP (Lightweight Directory Access Protocol) is the industry-standard protocol for accessing directory services. Phoenix uses LDAP to authenticate users against your corporate directory and optionally map directory groups to Phoenix roles.
423
+
{% endhint %}
424
+
425
+
### Required LDAP Configuration
426
+
427
+
To enable LDAP authentication, set the following environment variables in addition to `PHOENIX_ENABLE_AUTH` and `PHOENIX_SECRET`:
428
+
429
+
<tabledata-full-width="false"><thead><tr><thwidth="280">Environment Variable</th><th>Description</th></tr></thead><tbody><tr><td><strong>PHOENIX_LDAP_HOST</strong></td><td>LDAP server hostname or IP address. Comma-separated for multiple servers with automatic failover. (Required)<br><br>Examples:<br>• Single server: <code>ldap.corp.example.com</code><br>• Multiple servers: <code>dc1.corp.com,dc2.corp.com,dc3.corp.com</code></td></tr><tr><td><strong>PHOENIX_LDAP_USER_SEARCH_BASE</strong></td><td>Base DN (Distinguished Name) for user searches. This is where Phoenix looks for user accounts. (Required)<br><br>Examples:<br>• Active Directory: <code>OU=Users,DC=corp,DC=example,DC=com</code><br>• OpenLDAP: <code>ou=people,dc=example,dc=com</code></td></tr></tbody></table>
430
+
431
+
### Optional LDAP Configuration
432
+
433
+
<table data-full-width="false"><thead><tr><th width="280">Environment Variable</th><th>Description</th></tr></thead><tbody><tr><td><strong>PHOENIX_LDAP_PORT</strong></td><td>LDAP server port. Defaults to <code>389</code> for StartTLS or <code>636</code> for LDAPS based on <code>TLS_MODE</code>.</td></tr><tr><td><strong>PHOENIX_LDAP_USE_TLS</strong></td><td>Enable TLS encryption for LDAP connections. Defaults to <code>true</code>. Should always be <code>true</code> in production to protect credentials.</td></tr><tr><td><strong>PHOENIX_LDAP_TLS_MODE</strong></td><td>TLS connection mode. Options:<br>• <code>starttls</code> (default): Upgrade plaintext connection to TLS on port 389<br>• <code>ldaps</code>: TLS from connection start on port 636</td></tr><tr><td><strong>PHOENIX_LDAP_TLS_VERIFY</strong></td><td>Verify server TLS certificates. Defaults to <code>true</code>. Should always be <code>true</code> in production to prevent MITM attacks.</td></tr><tr><td><strong>PHOENIX_LDAP_TLS_CA_CERT_FILE</strong></td><td>Path to custom CA certificate file (PEM format) for TLS verification. Use when your LDAP server uses a private/internal CA not in the system trust store.<br><br>Example: <code>/etc/ssl/certs/internal-ca.pem</code></td></tr><tr><td><strong>PHOENIX_LDAP_TLS_CLIENT_CERT_FILE</strong></td><td>Path to client certificate file (PEM format) for mutual TLS authentication. Requires <code>TLS_CLIENT_KEY_FILE</code> to also be set.</td></tr><tr><td><strong>PHOENIX_LDAP_TLS_CLIENT_KEY_FILE</strong></td><td>Path to client private key file (PEM format) for mutual TLS authentication. Requires <code>TLS_CLIENT_CERT_FILE</code> to also be set.</td></tr><tr><td><strong>PHOENIX_LDAP_BIND_DN</strong></td><td>Service account DN for binding to the LDAP server. Required for search-then-bind authentication.<br><br>Example: <code>CN=svc-phoenix,OU=Service Accounts,DC=corp,DC=com</code></td></tr><tr><td><strong>PHOENIX_LDAP_BIND_PASSWORD</strong></td><td>Service account password for binding to the LDAP server. Should be stored securely (e.g., in a Kubernetes Secret).</td></tr><tr><td><strong>PHOENIX_LDAP_USER_SEARCH_FILTER</strong></td><td>LDAP filter for finding users. Use <code>%s</code> as placeholder for the username.<br><br>Defaults to Active Directory format: <code>(&(objectClass=user)(sAMAccountName=%s))</code><br><br>OpenLDAP example: <code>(&(objectClass=inetOrgPerson)(uid=%s))</code></td></tr><tr><td><strong>PHOENIX_LDAP_ATTR_EMAIL</strong></td><td>LDAP attribute containing user's email address. Defaults to <code>mail</code>. Must be present in LDAP for authentication to succeed.</td></tr><tr><td><strong>PHOENIX_LDAP_ATTR_DISPLAY_NAME</strong></td><td>LDAP attribute containing user's display name. Defaults to <code>displayName</code>.</td></tr><tr><td><strong>PHOENIX_LDAP_ATTR_MEMBER_OF</strong></td><td>LDAP attribute containing group memberships (for Active Directory). Defaults to <code>memberOf</code>. Leave empty for POSIX groups.</td></tr><tr><td><strong>PHOENIX_LDAP_ATTR_UNIQUE_ID</strong></td><td>LDAP attribute containing an immutable unique identifier. Only configure if you expect user emails to change frequently.<br><br>Options:<br>• Active Directory: <code>objectGUID</code><br>• OpenLDAP: <code>entryUUID</code><br>• 389 DS: <code>nsUniqueId</code></td></tr><tr><td><strong>PHOENIX_LDAP_GROUP_SEARCH_BASE</strong></td><td>Base DN for group searches. Required when using POSIX groups (when <code>ATTR_MEMBER_OF</code> is empty).<br><br>Example: <code>ou=groups,dc=example,dc=com</code></td></tr><tr><td><strong>PHOENIX_LDAP_GROUP_SEARCH_FILTER</strong></td><td>LDAP filter for finding groups. Use <code>%s</code> as placeholder for username. Required when using POSIX groups.<br><br>Example: <code>(&(objectClass=posixGroup)(memberUid=%s))</code></td></tr><tr><td><strong>PHOENIX_LDAP_GROUP_ROLE_MAPPINGS</strong></td><td>JSON array mapping LDAP groups to Phoenix roles.<br><br>Format: <code>[{"group_dn": "CN=Group,DC=corp,DC=com", "role": "ADMIN"}]</code><br><br>Supported roles: <code>ADMIN</code>, <code>MEMBER</code>, <code>VIEWER</code> (case-insensitive)<br><br>Special value <code>*</code> for group_dn matches all users (wildcard for default role).</td></tr><tr><td><strong>PHOENIX_LDAP_ALLOW_SIGN_UP</strong></td><td>Allow automatic user creation on first LDAP login. Defaults to <code>true</code>. Set to <code>false</code> to require pre-provisioned users (created via <code>PHOENIX_ADMINS</code> or the UI before first login).</td></tr></tbody></table>
* Always use TLS encryption (`PHOENIX_LDAP_USE_TLS=true`) in production
540
+
* Always verify TLS certificates (`PHOENIX_LDAP_TLS_VERIFY=true`) in production
541
+
* Store the bind password securely (e.g., Kubernetes Secrets, HashiCorp Vault)
542
+
* Use a dedicated service account with minimal read-only permissions
543
+
* Configure group role mappings to follow the principle of least privilege
544
+
{% endhint %}
545
+
546
+
{% hint style="info" %}
547
+
**User Identity:**
548
+
By default, Phoenix identifies LDAP users by their email address. If you expect user emails to change frequently (e.g., due to company rebranding or name changes), configure `PHOENIX_LDAP_ATTR_UNIQUE_ID` to use an immutable identifier like `objectGUID` (Active Directory) or `entryUUID` (OpenLDAP).
549
+
{% endhint %}
550
+
410
551
## Advanced Authentication Configuration
411
552
412
553
The following optional environment variables provide additional control over authentication behavior for advanced use cases:
Copy file name to clipboardExpand all lines: helm/README.md
+21Lines changed: 21 additions & 0 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -42,6 +42,27 @@ Phoenix is an open-source AI observability platform designed for experimentation
42
42
| auth.defaultAdminPassword | string |`"admin"`| Default password for the admin user on initial setup (PHOENIX_DEFAULT_ADMIN_INITIAL_PASSWORD) |
43
43
| auth.disableBasicAuth | bool |`false`| Disable password-based authentication (PHOENIX_DISABLE_BASIC_AUTH) When true, users can only authenticate via OAuth2/OIDC. Useful for SSO-only deployments. |
44
44
| auth.enableAuth | bool |`true`| Enable authentication and authorization for Phoenix (PHOENIX_ENABLE_AUTH) |
45
+
| auth.ldap.allowSignUp | bool |`true`| Allow automatic user creation on first LDAP login. Set to false to require pre-provisioned users. |
| auth.ldap.attrEmail | string |`"mail"`| LDAP attribute containing user's email address. Must be present in LDAP or login fails. |
48
+
| auth.ldap.attrMemberOf | string |`"memberOf"`| LDAP attribute containing group memberships (for Active Directory). Leave empty for POSIX groups (requires groupSearchBase and groupSearchFilter). |
49
+
| auth.ldap.attrUniqueId | string |`""`| LDAP attribute containing an immutable unique identifier (optional). Only configure if you expect user emails to change. Active Directory: "objectGUID", OpenLDAP: "entryUUID", 389 DS: "nsUniqueId" |
50
+
| auth.ldap.bindDn | string |`""`| Service account DN for binding to LDAP server. Example: "CN=svc-phoenix,OU=Service Accounts,DC=corp,DC=com" |
51
+
| auth.ldap.bindPassword | string |`""`| Service account password for binding to LDAP server. Can be set directly here or via auth.secret with key PHOENIX_LDAP_BIND_PASSWORD |
| auth.ldap.groupRoleMappings | string |`"[]"`| JSON array mapping LDAP groups to Phoenix roles. Format: [{"group_dn": "CN=Phoenix Admins,OU=Groups,DC=corp,DC=com", "role": "ADMIN"}] Supported roles: "ADMIN", "MEMBER", "VIEWER" (case-insensitive) Special group_dn value "*" matches all users (wildcard for default role) |
54
+
| auth.ldap.groupSearchBase | string |`""`| Base DN for group searches. Required if attrMemberOf is empty. Example: "ou=groups,dc=example,dc=com" |
55
+
| auth.ldap.groupSearchFilter | string |`""`| LDAP filter for finding groups. Use %s as placeholder for username. Required if attrMemberOf is empty. Example: "(&(objectClass=posixGroup)(memberUid=%s))" |
56
+
| auth.ldap.host | string |`""`| LDAP server hostname (required when enabled). Comma-separated for multiple servers with failover. Examples: "ldap.corp.com" or "dc1.corp.com,dc2.corp.com,dc3.corp.com" |
57
+
| auth.ldap.port | string |`""`| LDAP server port. Defaults to 389 for StartTLS, 636 for LDAPS. |
58
+
| auth.ldap.tlsCaCertFile | string |`""`| Path to custom CA certificate file (PEM format) for TLS verification. Use when LDAP server uses a private/internal CA not in the system trust store. |
59
+
| auth.ldap.tlsClientCertFile | string |`""`| Path to client certificate file (PEM format) for mutual TLS authentication. Requires tlsClientKeyFile to also be set. |
60
+
| auth.ldap.tlsClientKeyFile | string |`""`| Path to client private key file (PEM format) for mutual TLS authentication. Requires tlsClientCertFile to also be set. |
61
+
| auth.ldap.tlsMode | string |`"starttls"`| TLS connection mode: "starttls" (upgrade from plaintext on port 389) or "ldaps" (TLS from start on port 636) |
62
+
| auth.ldap.tlsVerify | bool |`true`| Verify TLS certificates. Should always be true in production. |
63
+
| auth.ldap.useTls | bool |`true`| Use TLS for LDAP connections. Should always be true in production. |
64
+
| auth.ldap.userSearchBase | string |`""`| Base DN for user searches (required when enabled). Comma-separated for multiple bases. Example: "OU=Users,DC=corp,DC=com" |
65
+
| auth.ldap.userSearchFilter | string |`"(&(objectClass=user)(sAMAccountName=%s))"`| LDAP filter for finding users. Use %s as placeholder for username. Default for Active Directory: "(&(objectClass=user)(sAMAccountName=%s))" OpenLDAP example: "(&(objectClass=inetOrgPerson)(uid=%s))" |
45
66
| auth.name | string |`"phoenix-secret"`| Name of the Kubernetes secret containing authentication credentials |
| auth.oauth2.providers | string |`nil`| List of OAuth2 identity providers to configure Each provider requires client_id, client_secret (unless token_endpoint_auth_method="none"), and oidc_config_url You can also define corresponding ENVs via auth.secrets[].valueFrom to use existing secrets ENVs: PHOENIX_OAUTH2_{{ $provider_upper }}_{{ setting }}, e.g. PHOENIX_OAUTH2_GOOGLE_CLIENT_SECRET |
0 commit comments