OIDC, LDAP and passkeys
Set up OpenID Connect and LDAP sign-in for FeatherPanel, how passkeys, e-mail codes and QR login work, and how to turn off local password login.
On this page
FeatherPanel can sign users in with a local password, passkeys, a one-time e-mail code, Discord, any number of
OpenID Connect providers and any number of LDAP directories. Two-factor authentication (TOTP) sits on top of the
password login. Admins manage the providers in the admin area under OIDC Providers and LDAP Providers;
both need admin.settings.edit.
OpenID Connect
Add a provider in Admin > OIDC Providers. The fields map to these columns:
| Field | Default | Meaning |
|---|---|---|
name | Label on the login button. | |
issuer_url | Issuer base URL. The panel reads <issuer_url>/.well-known/openid-configuration. | |
client_id, client_secret | From your provider. The secret is stored encrypted. | |
scopes | openid email profile | Scopes sent in the authorization request. |
subject_claim | sub | Claim that identifies the user. |
email_claim | email | Claim that holds the e-mail address. |
group_claim, group_value | empty | Optional gate: only users whose claim equals, or contains, this value may sign in. |
auto_provision | false | Create an account on first sign-in. |
require_email_verified | false | Refuse to link an existing account unless email_verified is true. |
enabled | true | Show and accept this provider. |
Register this redirect URI with the provider:
https://panel.example.com/api/user/auth/oidc/callbackHow a sign-in is matched
- The panel sends the user to the provider with a random
stateandnonce, valid for 10 minutes. - On the callback it exchanges the code, verifies the ID token and rejects a nonce mismatch.
- It looks the user up by provider and subject. If none is found and the provider says the e-mail is verified, it links the account with that e-mail.
- If there is still no account, it creates one when
auto_provisionis on. The username comes frompreferred_username, thenname, then the e-mail; first and last names come fromgiven_nameandfamily_name. Otherwise the user is sent back withoidc_user_not_found.
Signed-in users can link or unlink a provider from their account page (/api/user/auth/oidc/link and
/api/user/auth/oidc/unlink). The login page lists enabled providers from the public
/api/system/oidc/providers route.
LDAP and Active Directory
Add a directory in Admin > LDAP Providers and use Test to check the connection before you enable it.
| Field | Meaning |
|---|---|
host, port | Directory server. |
use_ssl | Connect with ldaps://. |
use_tls | Run StartTLS on a plain connection (ignored when use_ssl is on). |
bind_dn, bind_password | Service account. Leave empty for an anonymous bind. |
base_dn | Where user searches start. |
user_filter | Search filter with a {username} placeholder, for example (sAMAccountName={username}) on AD. |
username_attribute, email_attribute, first_name_attribute, last_name_attribute | Attribute mapping. |
required_group, group_attribute | Only members of this group may sign in, read from group_attribute (default memberOf). Empty allows everyone. |
auto_provision | Create the panel account on first LDAP sign-in. |
sync_attributes | Update e-mail and names on every sign-in. |
Users sign in with PUT /api/user/auth/ldap/login, and can link an existing account to their directory entry from
the account page.
Passkeys
Users add passkeys on their account page. The relying party ID is the host name of the panel’s app URL, and only
that origin is accepted, so the app URL setting has to match the address in the browser. Passkey sign-in uses the
public /api/user/auth/passkeys/authentication/options and /verify routes; registration and management live
under /api/user/passkeys.
E-mail codes, Discord and QR login
- E-mail codes: with
email_login_enabledon and SMTP configured, users can ask for a 6-digit code that is valid for 10 minutes. - Discord: set
discord_oauth_enabled,discord_oauth_client_idanddiscord_oauth_client_secret. Users can sign in, register or link Discord to an existing account. - QR login: with
auth_show_qr_loginon, the login page shows a QR code. A phone that is already signed in scans it and approves the desktop session. A QR challenge lasts 180 seconds.
Login page options
| Setting | Effect |
|---|---|
login_methods_order | Order of the methods: local, passkey, ldap, email_code, discord, oidc. |
login_hidden_methods | Methods to hide from the page. |
login_default_method | Method shown first. |
oidc_disable_local_login | Block password and passkey sign-in for everyone without admin.root. |
require_two_fa_admins | Require TOTP for admins. |
See the settings reference for every key.
Related
Frequently asked questions
Your panel URL followed by /api/user/auth/oidc/callback, for example https://panel.example.com/api/user/auth/oidc/callback. It is built from the app URL setting, so that setting must match the address users open.
Set oidc_disable_local_login to true. Password and passkey sign-in then return LOCAL_LOGIN_DISABLED for everyone except users with admin.root, so you cannot lock yourself out.
The WebAuthn relying party ID is the host name of the app URL. Passkeys registered for the old host do not work on a new one, so users have to add them again.