Single Sign On

Homarr supports multiple authentication options, from internal userbase (credentials), to LDAP (with Active directory support), and OIDC.

Auth configuration common variables

Environment Variable	Description	Default Value
AUTH_PROVIDERS	Select Which provider to use between credentials, ldap and oidc. Multiple providers can be enabled with by separating them with ,, (ex. AUTH_PROVIDERS=credentials,oidc, it is highly recommended to just enable one provider).	credentials
AUTH_LOGOUT_REDIRECT_URL	URL to redirect to after clicking logging out.	---
AUTH_SESSION_EXPIRY_TIME	Time for the session to time out. Can be set as pure number, which will automatically be used in seconds, or followed by s, m, h or d for seconds, minutes, hours or days. (ex: "30m")	"30d"

Credentials Provider

This is the default provider.

First user is created using the onboarding process and the rest can be created by this user (see user management)

LDAP provider

This provider authenticates against an LDAP server.

Any user in LDAP server that signs in gets created in Homarr database.

Roles are fetched from LDAP groups. Groups with the same name of Homarr will be used to synchronize them.

Example Setup

In this setup we are using lldap. Install your server using docker or as a service.

Minimal configuration requires 4 env variables, LDAP URI, base, user and password for querying data.

There's more variables, but all have defaults corresponding to lldap defaults. These might need to be changed if you have different LDAP provider.

docker run ...
AUTH_PROVIDERS="ldap"
AUTH_LDAP_URI="ldap://example.com:3890"
AUTH_LDAP_BASE="dc=example,dc=com" // Same as LLDAP_LDAP_BASE_DN
AUTH_LDAP_BIND_DN="uid=admin,ou=People,dc=example,dc=com"
AUTH_LDAP_BIND_PASSWORD="adminpass" // Same as LLDAP_LDAP_USER_PASS

#Docker compose
version: x
services:
  homarr:
    environment:
      AUTH_PROVIDERS: ldap
      AUTH_LDAP_URI: ldap://example.com:3890
      AUTH_LDAP_BASE: dc=example,dc=com #Same as LLDAP_LDAP_BASE_DN
      AUTH_LDAP_BIND_DN: uid=admin,ou=People,dc=example,dc=com
      AUTH_LDAP_BIND_PASSWORD: adminpass #Same as LLDAP_LDAP_USER_PASS

In lldap, create a user and admin group, assign this user to the external admin group configured during onboarding. You can log in using this user and he will be in the group.

Here is another example for Active Directory:

AUTH_LDAP_URI="ldap://ldap.abc.xyz:389
AUTH_LDAP_BASE="DC=abc,DC=xyz"
AUTH_LDAP_BIND_DN="CN=Administrator,CN=Users,DC=abc,DC=xyz"
AUTH_LDAP_BIND_PASSWORD="YourAdministratorPassword"
AUTH_LDAP_USERNAME_ATTRIBUTE="sAMAccountName"
AUTH_LDAP_USER_MAIL_ATTRIBUTE="userPrincipalName"
AUTH_LDAP_GROUP_CLASS="group"
AUTH_LDAP_GROUP_MEMBER_ATTRIBUTE="member"
AUTH_LDAP_GROUP_MEMBER_USER_ATTRIBUTE="dn"
AUTH_LDAP_SEARCH_SCOPE="sub"
AUTH_LDAP_USERNAME_FILTER_EXTRA_ARG="(sAMAccountType=805306368)"

User mail attribute is set to userPrincipalName as it follows the right schema, but it is recommended to use real emails and the default 'mail' value.

Configuration

Environment Variable	Description	Default value
AUTH_LDAP_URI	URI of your LDAP server	---
AUTH_LDAP_BASE	Base dn of your LDAP server	---
AUTH_LDAP_BIND_DN	User used for finding users and groups	---
AUTH_LDAP_BIND_PASSWORD	Password for bind user	---
AUTH_LDAP_USERNAME_ATTRIBUTE	Attribute used for username	uid
AUTH_LDAP_USER_MAIL_ATTRIBUTE	Attribute used for mail field	mail
AUTH_LDAP_GROUP_CLASS	Class used for querying groups	groupOfUniqueNames
AUTH_LDAP_GROUP_MEMBER_ATTRIBUTE	Attribute used for querying group member	member
AUTH_LDAP_GROUP_MEMBER_USER_ATTRIBUTE	User attribute used for comparing with group member	dn
AUTH_LDAP_SEARCH_SCOPE	Serach scopes between base, one and sub	base
AUTH_LDAP_USERNAME_FILTER_EXTRA_ARG	Extra arguments for user search filter (& based)	---
AUTH_LDAP_GROUP_FILTER_EXTRA_ARG	Extra arguments for user's groups search filter (& based)	---

OIDC provider

This provider authenticates using OIDC protocol.

Users signed in using OIDC are created in Homarr.

Roles are fetched from group claims. This can also be changed to roles for example added to a azure app registration by using the AUTH_OIDC_GROUPS_ATTRIBUTE.

Example Setup

In this example we will be using Authelia.

You can use any setup, but the simplest is local.

You also have to enable OIDC in Authelia.

Create a client for homarr. To generate client secret you can use authelia. This is an example config:

identity_providers:
oidc:
...
clients:
- id: homarr
secret: <secret_hash>
public: false
authorization_policy: one_factor
redirect_uris:
- https://example.com/api/auth/callback/oidc
- http://localhost:3000/api/auth/callback/oidc
scopes:
- openid
- groups
- profile
- email
userinfo_signing_algorithm: none
consent_mode: implicit # self hosted

In Homarr use following env variables.

AUTH_PROVIDERS="oidc"
AUTH_OIDC_ISSUER="https://auth.example.com"
AUTH_OIDC_CLIENT_SECRET="client_secret"
AUTH_OIDC_CLIENT_ID="homarr"
AUTH_OIDC_CLIENT_NAME="Authelia"
AUTH_OIDC_FORCE_USERINFO="true" --> from v4.39 of authelia and above this is required

For an azure app registration the setup could look like this:

AUTH_PROVIDERS="oidc"
AUTH_OIDC_ISSUER="https://login.microsoftonline.com/<teanant-id>/v2.0"
AUTH_OIDC_CLIENT_SECRET="<client-secret>"
AUTH_OIDC_CLIENT_ID="<client-id>"
AUTH_OIDC_CLIENT_NAME="Azure"
AUTH_OIDC_SCOPE_OVERWRITE="openid email profile" # Groups scope does not exist in azure
AUTH_OIDC_GROUPS_ATTRIBUTE="roles" # We use the roles of the app registration so that we don't need to use uuids as our groups

Configuration

Environment Variable	Description	Default value
AUTH_OIDC_ISSUER	Issuer URI of OIDC provider. This has generally to be without trailing slash except for Authentik	---
AUTH_OIDC_CLIENT_ID	ID of OIDC client (application)	---
AUTH_OIDC_CLIENT_SECRET	Secret of OIDC client (application)	---
AUTH_OIDC_CLIENT_NAME	Display name of provider (in login screen)	OIDC
AUTH_OIDC_AUTO_LOGIN	Automatically redirect to OIDC login	false
AUTH_OIDC_SCOPE_OVERWRITE	Overwrite default scopes (openid, profile, email)	openid email profile groups
AUTH_OIDC_GROUPS_ATTRIBUTE	Attribute used for groups (roles) claim	groups
AUTH_OIDC_NAME_ATTRIBUTE_OVERWRITE	Overwrite name attribute. By default it will use preferred_username if it does not contain a @ and otherwise name.	---
AUTH_OIDC_FORCE_USERINFO	Force userinfo endpoint to be used for user information.	false

Permission System

To give a user special permissions, first create a new group in homarr and assign the permission desired. For example if the group on homarr is called homarr-admins a new group on the oidc provider, for example authentik needs to be created with the same name, that would be homarr-admins. After assigning the group on the oidc provider to the user, and logging again into homarr, the user should automatically get placed in that group and inherit the permissions defined.