Authentication Providers

Homarr supports multiple authentication providers: credentials-based authentication, OIDC (OpenID Connect), and LDAP. You can enable multiple providers simultaneously.

Configuring Providers

Authentication providers are configured via the AUTH_PROVIDERS environment variable. Multiple providers can be enabled by separating them with commas.

.env

AUTH_PROVIDERS="credentials,oidc,ldap"

Supported values:

credentials - Username/password authentication (default)
oidc - OpenID Connect / OAuth2
ldap - LDAP directory authentication

If you disable the credentials provider, ensure you have at least one other provider configured, or you won’t be able to log in.

Credentials Authentication

The default authentication method using username and password stored in Homarr’s database.

Configuration

.env

AUTH_PROVIDERS="credentials"
AUTH_SESSION_EXPIRY_TIME="30d"

AUTH_PROVIDERS

string

required

Must include credentials to enable this provider.

AUTH_PROVIDERS="credentials"

AUTH_SESSION_EXPIRY_TIME

string

default:"30d"

How long user sessions remain valid. Accepts duration strings like 30d, 7d, 12h.

AUTH_SESSION_EXPIRY_TIME="30d"

Creating Users

Users are created through the Homarr web interface after initial setup. The first user created becomes an administrator.

Password Management

Passwords are securely hashed using bcrypt with individual salts. See CLI Commands for password reset options.

Security Features

Passwords hashed with bcrypt
Individual salts per user
Session-based authentication
Configurable session expiry
Usernames automatically converted to lowercase

OIDC (OpenID Connect)

Connect Homarr to your existing SSO provider like Authentik, Authelia, Keycloak, or any OIDC-compliant provider.

Configuration

Add oidc to AUTH_PROVIDERS and configure the following variables:

.env

AUTH_PROVIDERS="credentials,oidc"

# Required OIDC Configuration
AUTH_OIDC_ISSUER="https://auth.example.com"
AUTH_OIDC_CLIENT_ID="homarr"
AUTH_OIDC_CLIENT_SECRET="your-client-secret"
AUTH_OIDC_CLIENT_NAME="SSO Login"

# Optional Configuration
AUTH_OIDC_AUTO_LOGIN=false
AUTH_OIDC_SCOPE_OVERWRITE="openid email profile groups"
AUTH_OIDC_GROUPS_ATTRIBUTE="groups"
AUTH_OIDC_FORCE_USERINFO=false
AUTH_OIDC_ENABLE_DANGEROUS_ACCOUNT_LINKING=false

Required Parameters

AUTH_OIDC_ISSUER

string

required

The OIDC issuer URL. This is typically your identity provider’s base URL.

AUTH_OIDC_ISSUER="https://auth.example.com"

Examples:

Authentik: https://authentik.example.com/application/o/homarr/
Authelia: https://authelia.example.com
Keycloak: https://keycloak.example.com/realms/master

AUTH_OIDC_CLIENT_ID

string

required

The client ID registered with your OIDC provider.

AUTH_OIDC_CLIENT_ID="homarr"

AUTH_OIDC_CLIENT_SECRET

string

required

The client secret provided by your OIDC provider.

AUTH_OIDC_CLIENT_SECRET="your-secret-here"

AUTH_OIDC_CLIENT_NAME

string

default:"OIDC"

Display name for the OIDC login button.

AUTH_OIDC_CLIENT_NAME="Login with SSO"

Optional Parameters

Automatically redirect to OIDC provider on login page, skipping the provider selection.

AUTH_OIDC_AUTO_LOGIN=true

AUTH_OIDC_SCOPE_OVERWRITE

string

default:"openid email profile groups"

OAuth scopes to request from the provider.

AUTH_OIDC_SCOPE_OVERWRITE="openid email profile groups"

AUTH_OIDC_GROUPS_ATTRIBUTE

string

default:"groups"

The attribute name in the ID token that contains user groups.

AUTH_OIDC_GROUPS_ATTRIBUTE="groups"

AUTH_OIDC_NAME_ATTRIBUTE_OVERWRITE

string

Override which attribute to use for the username. By default, uses preferred_username or name.

AUTH_OIDC_NAME_ATTRIBUTE_OVERWRITE="nickname"

AUTH_OIDC_FORCE_USERINFO

boolean

default:"false"

Force the use of the userinfo endpoint instead of the ID token.

AUTH_OIDC_FORCE_USERINFO=true

Required for Authelia v4.39+. See GitHub Issue #2635

AUTH_OIDC_ENABLE_DANGEROUS_ACCOUNT_LINKING

boolean

default:"false"

Allow linking OIDC accounts to existing accounts with the same email address.

AUTH_OIDC_ENABLE_DANGEROUS_ACCOUNT_LINKING=true

This can be a security risk. Only enable if your OIDC provider verifies email addresses.

Provider-Specific Examples

Authentik
Authelia
Keycloak

.env

AUTH_PROVIDERS="credentials,oidc"
AUTH_OIDC_ISSUER="https://authentik.example.com/application/o/homarr/"
AUTH_OIDC_CLIENT_ID="homarr"
AUTH_OIDC_CLIENT_SECRET="your-client-secret"
AUTH_OIDC_CLIENT_NAME="Authentik"
AUTH_OIDC_SCOPE_OVERWRITE="openid email profile groups"

Authentik Setup:

Create a new OAuth2/OpenID Provider
Set Redirect URI: https://homarr.example.com/api/auth/callback/oidc
Add scopes: openid, email, profile, groups
Copy Client ID and Secret to your .env

.env

AUTH_PROVIDERS="credentials,oidc"
AUTH_OIDC_ISSUER="https://authelia.example.com"
AUTH_OIDC_CLIENT_ID="homarr"
AUTH_OIDC_CLIENT_SECRET="your-client-secret"
AUTH_OIDC_CLIENT_NAME="Authelia"
AUTH_OIDC_FORCE_USERINFO=true

Authelia Setup (v4.39+):

Add client to configuration.yml:

identity_providers:
  oidc:
    clients:
      - id: homarr
        secret: your-client-secret
        redirect_uris:
          - https://homarr.example.com/api/auth/callback/oidc
        scopes:
          - openid
          - email
          - profile
          - groups

Set AUTH_OIDC_FORCE_USERINFO=true (required for v4.39+)

.env

AUTH_PROVIDERS="credentials,oidc"
AUTH_OIDC_ISSUER="https://keycloak.example.com/realms/master"
AUTH_OIDC_CLIENT_ID="homarr"
AUTH_OIDC_CLIENT_SECRET="your-client-secret"
AUTH_OIDC_CLIENT_NAME="Keycloak"

Keycloak Setup:

Create a new OpenID Connect client
Set Valid Redirect URIs: https://homarr.example.com/api/auth/callback/oidc
Enable Client Authentication
Copy Client ID and Secret

Troubleshooting OIDC

www-authenticate error with FusionAuth

This is a known issue with some providers. The error is automatically handled in Homarr.See: GitHub Issue #2690

Groups not syncing

Verify AUTH_OIDC_GROUPS_ATTRIBUTE matches your provider’s group claim name:

Check your ID token structure
Common values: groups, roles, memberOf
Update the environment variable to match

Redirect URI mismatch

Ensure your OIDC provider has the correct redirect URI registered:

https://your-homarr-domain.com/api/auth/callback/oidc

LDAP Authentication

Integrate with existing LDAP directories like Active Directory, OpenLDAP, or FreeIPA.

Configuration

Add ldap to AUTH_PROVIDERS and configure the following:

.env

AUTH_PROVIDERS="credentials,ldap"

# Required LDAP Configuration
AUTH_LDAP_URI="ldap://ldap.example.com:389"
AUTH_LDAP_BIND_DN="cn=admin,dc=example,dc=com"
AUTH_LDAP_BIND_PASSWORD="admin_password"
AUTH_LDAP_BASE="dc=example,dc=com"

# Optional Configuration
AUTH_LDAP_SEARCH_SCOPE="base"
AUTH_LDAP_USERNAME_ATTRIBUTE="uid"
AUTH_LDAP_USER_MAIL_ATTRIBUTE="mail"
AUTH_LDAP_GROUP_CLASS="groupOfUniqueNames"
AUTH_LDAP_GROUP_MEMBER_ATTRIBUTE="member"
AUTH_LDAP_GROUP_MEMBER_USER_ATTRIBUTE="dn"

Required Parameters

AUTH_LDAP_URI

string

required

LDAP server URI. Use ldap:// for unencrypted or ldaps:// for TLS.

AUTH_LDAP_URI="ldap://ldap.example.com:389"
# Or with TLS:
AUTH_LDAP_URI="ldaps://ldap.example.com:636"

AUTH_LDAP_BIND_DN

string

required

Distinguished Name (DN) of the service account used for LDAP bind operations.

AUTH_LDAP_BIND_DN="cn=admin,dc=example,dc=com"

AUTH_LDAP_BIND_PASSWORD

string

required

Password for the LDAP bind DN.

AUTH_LDAP_BIND_PASSWORD="admin_password"

AUTH_LDAP_BASE

string

required

Base DN for user and group searches.

AUTH_LDAP_BASE="dc=example,dc=com"

Optional Parameters

AUTH_LDAP_SEARCH_SCOPE

string

default:"base"

LDAP search scope. Options: base, one, sub.

AUTH_LDAP_SEARCH_SCOPE="sub"

base - Only the base DN
one - One level below base DN
sub - Full subtree search

AUTH_LDAP_USERNAME_ATTRIBUTE

string

default:"uid"

LDAP attribute containing the username.

AUTH_LDAP_USERNAME_ATTRIBUTE="uid"
# For Active Directory:
AUTH_LDAP_USERNAME_ATTRIBUTE="sAMAccountName"

AUTH_LDAP_USER_MAIL_ATTRIBUTE

string

default:"mail"

LDAP attribute containing the user’s email address.

AUTH_LDAP_USER_MAIL_ATTRIBUTE="mail"

AUTH_LDAP_USERNAME_FILTER_EXTRA_ARG

string

Additional LDAP filter for user searches.

AUTH_LDAP_USERNAME_FILTER_EXTRA_ARG="(objectClass=person)"

AUTH_LDAP_GROUP_CLASS

string

default:"groupOfUniqueNames"

LDAP object class for groups.

AUTH_LDAP_GROUP_CLASS="groupOfUniqueNames"
# For Active Directory:
AUTH_LDAP_GROUP_CLASS="group"

AUTH_LDAP_GROUP_MEMBER_ATTRIBUTE

string

default:"member"

Attribute in group objects that lists members.

AUTH_LDAP_GROUP_MEMBER_ATTRIBUTE="member"
# For some LDAP servers:
AUTH_LDAP_GROUP_MEMBER_ATTRIBUTE="uniqueMember"

AUTH_LDAP_GROUP_MEMBER_USER_ATTRIBUTE

string

default:"dn"

User attribute that matches the group member attribute.

AUTH_LDAP_GROUP_MEMBER_USER_ATTRIBUTE="dn"

AUTH_LDAP_GROUP_FILTER_EXTRA_ARG

string

Additional LDAP filter for group searches.

AUTH_LDAP_GROUP_FILTER_EXTRA_ARG="(objectClass=groupOfNames)"

Provider-Specific Examples

OpenLDAP
Active Directory
FreeIPA

.env

AUTH_PROVIDERS="credentials,ldap"
AUTH_LDAP_URI="ldap://ldap.example.com:389"
AUTH_LDAP_BIND_DN="cn=admin,dc=example,dc=com"
AUTH_LDAP_BIND_PASSWORD="admin_password"
AUTH_LDAP_BASE="dc=example,dc=com"
AUTH_LDAP_SEARCH_SCOPE="sub"
AUTH_LDAP_USERNAME_ATTRIBUTE="uid"
AUTH_LDAP_USER_MAIL_ATTRIBUTE="mail"
AUTH_LDAP_GROUP_CLASS="groupOfUniqueNames"
AUTH_LDAP_GROUP_MEMBER_ATTRIBUTE="member"

.env

AUTH_PROVIDERS="credentials,ldap"
AUTH_LDAP_URI="ldap://dc.example.com:389"
AUTH_LDAP_BIND_DN="cn=Service Account,ou=Users,dc=example,dc=com"
AUTH_LDAP_BIND_PASSWORD="service_password"
AUTH_LDAP_BASE="dc=example,dc=com"
AUTH_LDAP_SEARCH_SCOPE="sub"
AUTH_LDAP_USERNAME_ATTRIBUTE="sAMAccountName"
AUTH_LDAP_USER_MAIL_ATTRIBUTE="mail"
AUTH_LDAP_GROUP_CLASS="group"
AUTH_LDAP_GROUP_MEMBER_ATTRIBUTE="member"
AUTH_LDAP_GROUP_MEMBER_USER_ATTRIBUTE="dn"

.env

AUTH_PROVIDERS="credentials,ldap"
AUTH_LDAP_URI="ldap://ipa.example.com:389"
AUTH_LDAP_BIND_DN="uid=admin,cn=users,cn=accounts,dc=example,dc=com"
AUTH_LDAP_BIND_PASSWORD="admin_password"
AUTH_LDAP_BASE="cn=accounts,dc=example,dc=com"
AUTH_LDAP_SEARCH_SCOPE="sub"
AUTH_LDAP_USERNAME_ATTRIBUTE="uid"
AUTH_LDAP_USER_MAIL_ATTRIBUTE="mail"
AUTH_LDAP_GROUP_CLASS="groupOfNames"
AUTH_LDAP_GROUP_MEMBER_ATTRIBUTE="member"

Troubleshooting LDAP

Connection refused

Verify LDAP server is reachable: telnet ldap.example.com 389
Check firewall rules
Ensure correct URI format: ldap:// or ldaps://

Bind failed

Verify bind DN is correct
Test credentials manually:

ldapsearch -x -H ldap://ldap.example.com -D "cn=admin,dc=example,dc=com" -W

Check for special characters in password (escape if needed)

User not found

Verify username attribute matches your LDAP schema
Check search base is correct
Increase search scope to sub if users are in nested OUs
Test search manually:

ldapsearch -x -H ldap://ldap.example.com -D "cn=admin,dc=example,dc=com" -W -b "dc=example,dc=com" "(uid=username)"

Multiple Providers

You can enable multiple authentication providers simultaneously:

.env

AUTH_PROVIDERS="credentials,oidc,ldap"

Users will see all enabled login options on the login page.

Session Management

AUTH_SESSION_EXPIRY_TIME

string

default:"30d"

Session duration for all authentication providers.

AUTH_SESSION_EXPIRY_TIME="30d"

AUTH_LOGOUT_REDIRECT_URL

string

URL to redirect users after logout.

AUTH_LOGOUT_REDIRECT_URL="https://example.com/goodbye"

Next Steps

CLI Commands - Manage users and reset passwords
Environment Variables - Complete variable reference
Database Configuration - Set up your database

Get Started

Core Features

Configuration

Integrations

Guides

Authentication Providers

Configuring Providers

Credentials Authentication

Configuration

Creating Users

Password Management

Security Features

OIDC (OpenID Connect)

Configuration

Required Parameters

Optional Parameters

Provider-Specific Examples

Troubleshooting OIDC

LDAP Authentication

Configuration

Required Parameters

Optional Parameters

Provider-Specific Examples

Troubleshooting LDAP

Multiple Providers

Session Management

Next Steps

Build docs developers (and LLMs) love

Get Started

Core Features

Configuration

Integrations

Guides

​Configuring Providers

​Credentials Authentication

​Configuration

​Creating Users

​Password Management

​Security Features

​OIDC (OpenID Connect)

​Configuration

​Required Parameters

​Optional Parameters

​Provider-Specific Examples

​Troubleshooting OIDC

​LDAP Authentication

​Configuration

​Required Parameters

​Optional Parameters

​Provider-Specific Examples

​Troubleshooting LDAP

​Multiple Providers

​Session Management

​Next Steps

Build docs developers (and LLMs) love

Configuring Providers

Credentials Authentication

Configuration

Creating Users

Password Management

Security Features

OIDC (OpenID Connect)

Configuration

Required Parameters

Optional Parameters

Provider-Specific Examples

Troubleshooting OIDC

LDAP Authentication

Configuration

Required Parameters

Optional Parameters

Provider-Specific Examples

Troubleshooting LDAP

Multiple Providers

Session Management

Next Steps