Single Sign On
Homarr supports multiple authentication options, namely credentials, ldap and oidc.
Enabled authentication methods can be specified in env variable AUTH_PROVIDER.
Multiple providers can be enabled with by separating them with ,
, (ex. AUTH_PROVIDER=credentials,oidc
, it is highly recommended to just enable one provider).
- Credentials Provider
- LDAP provider
- OIDC 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)
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. For this, you have to specify groups for admin and owner users.
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_PROVIDER="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_PROVIDER: 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 admin group. You can log in using this user and he will be admin and owner.
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_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_ADMIN_GROUP | Admin group | admin |
AUTH_LDAP_OWNER_GROUP | Owner group | admin |
This provider authenticates using OIDC protocol.
Users sign in using OIDC are created in Homarr.
Roles are fetched from group claims. For this, you have to specify groups for admin and owner users.
Example Setup
In this example we will be using Authelia.
You can use any setup, but the simplest is local. If using this configuration, note that by default user does have group admins but Homarr is looking for admin. You can fix it either in users_database.yml file or by setting AUTH_OIDC_ADMIN_GROUP in Homarr.
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_PROVIDER="oidc"
AUTH_OIDC_URI="https://auth.example.com"
AUTH_OIDC_CLIENT_SECRET="client_secret"
AUTH_OIDC_CLIENT_ID="homarr"
AUTH_OIDC_CLIENT_NAME="Authelia"
Configuration
Environment Variable | Description | Default value |
---|---|---|
AUTH_OIDC_URI | URI of OIDC provider | --- |
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_ADMIN_GROUP | Admin group | admin |
AUTH_OIDC_OWNER_GROUP | Owner group | admin |
AUTH_OIDC_TIMEOUT | Timeout in milliseconds | 3500 |