LDAP Auth provider

Description

This auth provider checks for user credentials in LDAP, and and then issues an access token.

All requests to backend should be made with passing this access token. If token is expired, then new auth token should be issued.

After successful auth, username is saved to backend database. It is then used for creating audit records for any object change, see changed_by field.

Warning

Until token is valid, no requests will be made to LDAP to check if user exists and not locked. So do not set access token expiration time for too long (e.g. longer than a day).

Strategies

Note

Basic LDAP terminology is explained here: LDAP Overview

There are 2 strategies to check for user in LDAP:

• Try to call bind request in LDAP with DN (DistinguishedName) and user password. DN is generated using bind_dn_template

• First try to lookup for user (search request) in LDAP to get user’s DN using some query, and then try to call bind using this DN. See lookup settings

By default, lookup strategy is used, as it can find user in a complex LDAP/ActiveDirectory environment. For example:

• you can search for user by uid, e.g. (uid={login}) or (sAMAccountName={login})

• you can search for user by several attributes, e.g. (|(uid={login})(mail={login}@domain.com))

• you can filter for entries, like (&(uid={login})(objectClass=person)

• you can filter for users matching a specific group or some other condition, like (&(uid={login})(memberOf=cn=MyPrettyGroup,ou=Groups,dc=mycompany,dc=com))

After user is found in LDAP, its uid_attribute is used for audit records.

Interaction schema

No lookup

With lookup

Basic configuration

pydantic model horizon.backend.settings.auth.ldap.LDAPAuthProviderSettings

Settings for LDAPAuthProvider.

Examples

HORIZON__AUTH__PROVIDER=horizon.backend.providers.auth.ldap.LDAPAuthProvider
HORIZON__AUTH__ACCESS_KEY__SECRET_KEY=secret
HORIZON__AUTH__LDAP__URL=ldap://ldap.domain.com:389
HORIZON__AUTH__LDAP__LOOKUP__ENABLED=True
HORIZON__AUTH__LDAP__LOOKUP__POOL__ENABLED=True
HORIZON__AUTH__LDAP__LOOKUP__CREDENTIALS__USER=uid=techuser,ou=users,dc=example,dc=com
HORIZON__AUTH__LDAP__LOOKUP__CREDENTIALS__PASSWORD=somepassword

Fields:

• access_token (horizon.backend.settings.auth.jwt.JWTSettings)

• ldap (horizon.backend.settings.auth.ldap.LDAPSettings)

field access_token: JWTSettings [Required]

Access-token related settings

field ldap: LDAPSettings [Required]

LDAP related settings

pydantic model horizon.backend.settings.auth.ldap.LDAPSettings

Settings related to LDAP interaction.

Examples

HORIZON__AUTH__LDAP__URL=ldap://ldap.domain.com:389
HORIZON__AUTH__LDAP__UID_ATTRIBUTE=sAMAccountName

Fields:

• auth_mechanism (Literal['SIMPLE', 'DIGEST-MD5'])

• base_dn (str)

• bind_dn_template (str)

• lookup (horizon.backend.settings.auth.ldap.LDAPLookupSettings)

• timeout_seconds (int | None)

• uid_attribute (str)

• url (pydantic.networks.AnyUrl)

field url: Annotated[AnyUrl, UrlConstraints(max_length=None, allowed_schemes=['ldap', 'ldaps'], host_required=True, default_host=None, default_port=None, default_path=None, preserve_empty_path=None)] [Required]

LDAP URL to connect to

Constraints:

• allowed_schemes = [‘ldap’, ‘ldaps’]

• host_required = True

field timeout_seconds: int | None = 10

LDAP request timeout, in seconds. None means no timeout

field auth_mechanism: Literal['SIMPLE', 'DIGEST-MD5'] = 'SIMPLE'

LDAP auth mechanism, used for bind request

field base_dn: str [Required]

Organization DN, e.g. ou=users,dc=example,dc=com

field uid_attribute: str = 'uid'

Attribute containing username.

Usually uid (LDAP) or sAMAccountName (ActiveDirectory).

field bind_dn_template: str = '{uid_attribute}={login},{base_dn}'

Template for building DN string, used for checking credentials in LDAP. You can pass any DN value supported by LDAP.

Supported substitution values:

• {login}

• {uid_attribute} (see uid_attribute)

• {base_dn} (see base_dn)

field lookup: LDAPLookupSettings [Optional]

LDAP search options

pydantic model horizon.backend.settings.auth.jwt.JWTSettings

Settings related to JWT tokens.

Examples

HORIZON__AUTH__ACCESS_KEY__SECRET_KEY=somesecret
HORIZON__AUTH__ACCESS_KEY__EXPIRE_SECONDS=3600  # 1 hour

Fields:

• expire_seconds (int)

• secret_key (pydantic.types.SecretStr)

• security_algorithm (str)

field secret_key: SecretStr [Required]

Secret key for signing JWT tokens.

Can be any string. It is recommended to generate random value for every application instance.

field security_algorithm: str = 'HS256'

Algorithm used for signing JWT tokens.

See authlib documentation.

field expire_seconds: int = 36000

Token expiration time, in seconds

pydantic model horizon.backend.settings.auth.ldap.LDAPConnectionPoolSettings

Settings related to LDAP connection pool.

Examples

HORIZON__AUTH__LDAP__LOOKUP__POOL__ENABLED=True
HORIZON__AUTH__LDAP__LOOKUP__POOL__MAX=10
HORIZON__AUTH__LDAP__LOOKUP__POOL__CHECK_ON_STARTUP=True

Fields:

• enabled (bool)

• initial (int)

• max (int)

field enabled: bool = True

Set to True to enable connection pool

field initial: int = 1

Initial size of connection pool

field max: int = 10

Maximum size of connection pool

Lookup-related configuration

pydantic model horizon.backend.settings.auth.ldap.LDAPLookupSettings

Settings related to LDAP lookup.

Examples

HORIZON__AUTH__LDAP__LOOKUP__ENABLED=True
HORIZON__AUTH__LDAP__LOOKUP__POOL__ENABLED=True
HORIZON__AUTH__LDAP__LOOKUP__CREDENTIALS__USER=uid=techuser,ou=users,dc=example,dc=com
HORIZON__AUTH__LDAP__LOOKUP__CREDENTIALS__PASSWORD=somepassword
HORIZON__AUTH__LDAP__LOOKUP__QUERY=(uid={login})

Fields:

• check_on_startup (bool)

• credentials (horizon.backend.settings.auth.ldap.LDAPCredentials | None)

• enabled (bool)

• pool (horizon.backend.settings.auth.ldap.LDAPConnectionPoolSettings)

• query_template (str)

• scope (bonsai.ldapconnection.LDAPSearchScope)

field enabled: bool = True

Set to True to enable lookup

field check_on_startup: bool = True

If True, and LDAP is not available during application start, abort application startup

field pool: LDAPConnectionPoolSettings [Optional]

LDAP connection pool settings

field credentials: LDAPCredentials | None = None

Credentials used for connecting to LDAP while performing user lookup

field query_template: str = '({uid_attribute}={login})'

LDAP query send in lookup request.

Usually lookup is performed against attributes uid (LDAP) or sAMAccountName (ActiveDirectory). You can also pass any query string supported by LDAP. See Bonsai documentation.

Supported substitution values (see horizon.backend.settings.auth.ldap.LDAPSettings.):

• {uid_attribute}

• {login}

field scope: LDAPSearchScope = LDAPSearchScope.ONELEVEL

Lookup scope. Use SUBTREE for ActiveDirectory.

See Bonsai documentation.

pydantic model horizon.backend.settings.auth.ldap.LDAPCredentials

LDAP lookup query is executed using this credentials (instead of login and password provided by user).

Examples

HORIZON__AUTH__LDAP__LOOKUP__CREDENTIALS__USER=uid=techuser,ou=users,dc=example,dc=com
HORIZON__AUTH__LDAP__LOOKUP__CREDENTIALS__PASSWORD=somepassword

Fields:

• password (pydantic.types.SecretStr)

• user (str)

field user: str [Required]

DN of user which is used for calling lookup query in LDAP

field password: SecretStr [Required]

This user password