Configuration Overview

Important

This page deals with configuring nginx-ldap-auth-service. For configuring nginx to use nginx-ldap-auth-service, see Configuring nginx.

nginx-ldap-auth-service reads configuration from three places, in decreasing order of precedence:

Command line options for nginx-ldap-auth start
Headers set in the location blocks of the nginx config file
Environment variables

Not all configuration options are available in all places.

Note

To print your resolved configuration when using the command line, you can run the following command:

$ nginx-ldap-auth settings

Note

Active Directory works somewhat differently than other LDAP servers.

See the “Active Directory” section in Environment for more information.

Command Line

If an option is specified on the command line, it overrides all other values that may have been specified in the app specific environment variables. configuration file. Not all nginx-ldap-auth-service settings are available to be set from the command line. To see the full list of command line settings you can do the usual:

$ nginx-ldap-auth start --help

nginx Header Configuration

If an option is specified in the nginx configuration file, it overrides the associated setting in nginx-ldap-auth-service.

You can set the following headers in your nginx configuration to configure nginx-ldap-auth-service on a per nginx server basis. You might do this if you have multiple nginx servers all using the same nginx-ldap-auth-service instance, but want to configure them differently.

Note

You can only set the following headers in the location blocks that proxy to nginx-ldap-auth-service. If you set them in the server block, they will be ignored.

Mandatory Headers

The following headers are mandatory and must be set in the /auth location:

X-Proto-Scheme
X-Host
Cookie

In the /check-auth location, you must set the X-Cookie-Name header. See nginx Header Configuration for more details on how to set these headers.

Cookie

The Cookies from the user’s browser. This is a mandatory header that is used to pass the session cookie and CSRF cookie to the auth service. It should be set like so in the /auth and /check-auth locations:
location /auth {
    proxy_pass http://nginx-ldap-auth-service:8888/auth;
    proxy_set_header Cookie $http_cookie;
}

X-Proto-Scheme

The protocol scheme to use for the auth service. This is a mandatory header that is used to build the redirect_uri for Duo MFA, and to validate the URL requested by the user before auth. It should be set like so in the /auth location:
location /auth {
    proxy_pass http://nginx-ldap-auth-service:8888/auth;
    proxy_set_header X-Proto-Scheme $scheme;
}

X-Host

The real hostname of the site that is requesting authentication. This is a mandatory header that is used to validate the URL requested by the user before auth. It should be set like so in the /auth location:

We’re using X-Host instead of Host because the Host header is ALWAYS set. If you don’t pass in the real hostname of the site, then Host will be set to the hostname from the proxy_pass line.
location /auth {
    proxy_pass http://nginx-ldap-auth-service:8888/auth;
    proxy_set_header X-Host $host;
}
Note

You may need to set this to a specific hostname if you are using a proxy or load balancer.

Example:
location /auth {
    proxy_pass http://nginx-ldap-auth-service:8888/auth;
    proxy_set_header X-Host "www.example.com";
}

Optional Headers

The following headers are optional and can be set in the /auth and /check-auth locations:

X-Cookie-Name
X-Cookie-Domain
X-Auth-Realm
X-Authenticated-User
X-Authorization-Filter

Or they can be set in the environment variables if you have a single backend.

X-Cookie-Name

The name of the session cookie. Either set this header or set the COOKIE_NAME environment variable. If X-Cookie-Name is set, it will override the value of COOKIE_NAME.

The proxy_set_header X-Cookie-Name line goes in the location block for the /auth and /check-auth locations.

Important

Whether or not you change the cookie name from its default of nginxauth, you’ll need the proxy_set_header Cookie and proxy_cache_key lines below. Change “mycookie” to whatever you set COOKIE_NAME to in all the places it occurs.

Example:
location /auth {
    proxy_pass http://nginx-ldap-auth-service:8888/auth;
    proxy_set_header X-Cookie-Name "mycookie";

    # other lines omitted for brevity
}

location /check-auth {
    proxy_pass http://nginx-ldap-auth-service:8888/check;

    # Cache our auth responses for 10 minutes so that we're not
    # hitting the auth service on every request.
    proxy_cache auth_cache;
    proxy_cache_valid 200 10m;

    # other lines omitted for brevity

    proxy_set_header X-Cookie-Name "mycookie";
    proxy_set_header Cookie mycookie=$cookie_mycookie;
    proxy_cache_key "$http_authorization$cookie_mycookie";
}
If you’re not doing any caching, you can ignore the cache related lines above.

X-Cookie-Domain

The domain for the session cookie. This goes in the location block for the /auth and /check-auth locations. If you don’t specify this header, the value of the domain will be that set for COOKIE_DOMAIN. If X-Cookie-Domain is set, it will override the value of COOKIE_DOMAIN.

Example:
location /auth {
    proxy_pass http://nginx-ldap-auth-service:8888/auth;
    proxy_set_header X-Cookie-Domain ".example.com";

    # other lines omitted for brevity
}

location /check-auth {
    proxy_pass http://nginx-ldap-auth-service:8888/check;

    # other lines omitted for brevity

    proxy_set_header X-Cookie-Domain ".example.com";
}

X-Auth-Realm

The title for the login form. This goes in the location block for the /auth location. Defaults to the value of nginx_ldap_auth.settings.Settings.auth_realm for the nginx-ldap-auth-service instance. You should either set it here in nginx.conf or with the AUTH_REALM environment variable, but not both.

Example:
location /auth {
    proxy_pass http://nginx-ldap-auth-service:8888/auth;
    proxy_set_header X-Auth-Realm "My Login Form";
}

X-Authenticated-User

The username of the authenticated user from nginx-ldap-auth-service. This goes in the location block for your app’s location. This is used to pass the authenticated username back to your application so that it can be used for provisioning users or other purposes. This is not required. be used for authorization checks.

Example:
location / {
    auth_request /check-auth;
    auth_request_set $auth_user $upstream_http_x_authenticated_user;
    proxy_set_header X-Authenticated-User $auth_user;
}

X-Authorization-Filter

An optional header to specify the LDAP authorization filter to use for the request. The proxy_set_header X-Authorization-Filter line goes in the location block for the /auth and /check-auth locations.

If X-Authorization-Filter is set, then it will override nginx_ldap_auth.settings.Settings.ldap_authorization_filter for the nginx-ldap-auth-service instance.

Important

Since this is a per-user authorization filter, the filter must use the {username} placeholder, and must be a valid LDAP search filter.

This header can be used if multiple services with different LDAP filter requirements use the same nginx-ldap-auth-service instance (e.g different AD groups).
Warning

This header is only respected when ALLOW_AUTHORIZATION_FILTER_HEADER is True (the default).

Security Risk: If this setting is enabled and your NGINX configuration does not explicitly set or clear the X-Authorization-Filter header, malicious clients could send a permissive filter (e.g., (objectClass=*)) to bypass group-based authorization restrictions.

For secure deployments, either:
Set ALLOW_AUTHORIZATION_FILTER_HEADER to False and use only the LDAP_AUTHORIZATION_FILTER environment variable, or
Ensure your NGINX configuration explicitly sets or clears this header using proxy_set_header before forwarding requests. Like so:
location /auth {
  proxy_pass http://nginx-ldap-auth-service:8888/auth;
  proxy_set_header X-Authorization-Filter "";
}

Environment

You can either export the appropriate variables directly into your shell environment, or you can use an environment file and specify it with the --env-file option to nginx-ldap-auth start.

The following environment variables are available to configure nginx-ldap-auth-service:

Important

You must set at least these variables to localize to your organization:

LDAP_URI
LDAP_BINDDN
LDAP_PASSWORD,
LDAP_BASEDN
SECRET_KEY.
CSRF_SECRET_KEY.

You should also look at these variables to see whether their defaults work for you:

LDAP_USERNAME_ATTRIBUTE
LDAP_FULL_NAME_ATTRIBUTE
LDAP_GET_USER_FILTER
LDAP_AUTHORIZATION_FILTER
AUTH_REALM
SESSION_MAX_AGE
COOKIE_NAME
COOKIE_DOMAIN
CSRF_COOKIE_NAME
SESSION_MAX_AGE
USE_ROLLING_SESSIONS
SESSION_BACKEND
REDIS_URL
REDIS_PREFIX
DUO_ENABLED
DUO_HOST
DUO_IKEY
DUO_SKEY

LDAP (389, openldap, etc.)

If you’re using an LDAP server that’s not Active Directory, and you’re using posixAccount objects, the LDAP_USERNAME_ATTRIBUTE and LDAP_FULL_NAME_ATTRIBUTE defaults will probably just work for you. You will still need to set/look at the other LDAP settings.

Active Directory

If you use Active Directory as your LDAP server, you should set the LDAP_USERNAME_ATTRIBUTE to sAMAccountName and the LDAP_FULL_NAME_ATTRIBUTE to cn. You will probably also need to set LDAP_USER_BASEDN to the base DN of your users which is probably not the same as your LDAP_BASEDN. Auth for normal users in AD is sometimes done with the userPrincipalName attribute which is the user’s email address, thus you would set LDAP_USER_BASEDN to @{__YOUR_EMAIL_DOMAIN__}, (e.g. @example.com) and the bare username will be prepended to that to form the bind DN for the user.

Web Server

These settings configure the web server that nginx-ldap-auth-service runs, uvicorn.

HOSTNAME: The hostname to listen on. Defaults to 0.0.0.0.

PORT: The port to listen on. Defaults to 8888.

SSL_KEYFILE: The path to the SSL key file. Defaults to /certs/server.key.

SSL_CERTFILE: The path to the SSL certificate file. Defaults to /certs/server.crt.

WORKERS: The number of worker processes to spawn. Defaults to 1.

DEBUG: Set to 1 or True to enable debug mode. Defaults to False.

INSECURE: Set to True to run our auth service web server over HTTP instead of HTTPS. Defaults to False.

Login form and sessions

These settings configure the login form and session handling.

AUTH_REALM: The title for the login form. Defaults to Restricted.

COOKIE_NAME: The name of the cookie to use for the session. Defaults to nginxauth.

CSRF_COOKIE_NAME: The name of the cookie to use for the CSRF cookie. Defaults to whatever you set COOKIE_NAME to with _csrf appended.

COOKIE_DOMAIN: The domain for the cookie to use for the session. Defaults to no domain.

SESSION_MAX_AGE: How many seconds a session should last after first login. Defaults to 0, no expiry. If USE_ROLLING_SESSIONS is True, this value is used to reset the session lifetime on every request.

USE_ROLLING_SESSIONS: If True, session lifetime will be reset to SESSION_MAX_AGE on every request. Defaults to False.

SECRET_KEY: Required The secret key to use for the session.

CSRF_SECRET_KEY: Required The secret key to use for the CSRF cookie.

SESSION_BACKEND: The session backend to use. Defaults to memory. Valid options are memory and redis. If you choose redis, you must also set REDIS_URL.

REDIS_URL

The DSN to the Redis server. See nginx_ldap_auth.settings.Settings.redis_url for details on the format of the DSN.

Defaults to None

REDIS_PREFIX: The prefix to use for Redis keys. Defaults to nginx_ldap_auth.

Duo MFA

These settings configure the Duo MFA workflow.

DUO_ENABLED: Set to True to enable Duo MFA. Defaults to False.

DUO_HOST: Required if DUO_ENABLED is True. The Duo API hostname.

DUO_IKEY: Required if DUO_ENABLED is True. The Duo integration key.

DUO_SKEY: Required if DUO_ENABLED is True. The Duo secret key.

Important

When enabling Duo MFA, see nginx Header Configuration for how to set the required X-Proto-Scheme and Host headers in the nginx configuration file so that the Duo MFA workflow can build the Duo callback URL correctly.

LDAP

These settings configure the LDAP server to use for authentication.

LDAP_URI: Required. The URL to the LDAP server. Defaults to ldap://localhost.

LDAP_BINDDN: Required. The DN of a privileged user in your LDAP/AD server that can be used to to bind to the LDAP server for doing our user and authorization searches.

LDAP_PASSWORD: Required. The password to use to with LDAP_BINDDN to bind to the LDAP server for doing our user and authorization searches.

LDAP_STARTTLS: Set to 0 or False to disable STARTTLS on our LDAP connections. Defaults to True.

LDAP_VALIDATE_CERT: Set to 0 or False to disable certificate validation on our LDAP connections. Defaults to True.

LDAP_CA_CERT_NAME: The name of the CA certificate file to use for validating the LDAP certificate. Defaults to None.

LDAP_CA_CERT_DIR: The path to the directory containing CA certificate to use for validating the LDAP certificate. Defaults to None.

LDAP_DISABLE_REFERRALS: Set to 1 or True to disable LDAP referrals. Defaults to False.

LDAP_BASEDN: Required The base DN to use for our LDAP searches that find users, and to construct the DN for the user to bind with, unless LDAP_USER_BASEDN is also set (see below). For authentication, the user’s DN will be constructed as {LDAP_USERNAME_ATTRIBUTE}={username},{LDAP_BASEDN}.

LDAP_USER_BASEDN

The base DN to append to the user’s username when binding. This is only important for Active Directory, where we may need to use the value of userPrincipalName (typically the user’s email address) as the username intead of the usual LDAP style dn which would be constructed as sAMAccountName=user,{LDAP_BASEDN}. Include the @ at the beginning of the value. The resulting bind DN will be {username}{LDAP_USER_BASEDN}.

Defaults to None.

Example:

export LDAP_USER_BASEDN="@example.com"

This will cause the bind DN to be user@example.com

This envvar is normally unset, and if so, the bind DN will be constructed as {LDAP_USERNAME_ATTRIBUTE}={username},{LDAP_BASEDN}.

LDAP_USERNAME_ATTRIBUTE: The LDAP attribute to use for the username. Defaults to uid.

LDAP_FULL_NAME_ATTRIBUTE: The LDAP attribute to use for the full name. Defaults to cn.

LDAP_GET_USER_FILTER

The LDAP search filter to use when searching for users. Defaults to {username_attribute}={username}, where {username_attribute} is the value of LDAP_USERNAME_ATTRIBUTE and {username} is the username provided by the user. See nginx_ldap_auth.settings.Settings.ldap_get_user_filter for more details.

The filter will within the base DN given by LDAP_BASEDN and with scope of SUBTREE.

LDAP_AUTHORIZATION_FILTER

The LDAP search filter to use when determining if a user is authorized to login. for authorizations. Defaults to no filter, meaning all users are authorized if they exist in LDAP. See nginx_ldap_auth.settings.Settings.ldap_authorization_filter for more details.

The filter will within the base DN given by LDAP_BASEDN and with scope of SUBTREE.

ALLOW_AUTHORIZATION_FILTER_HEADER

Whether to allow the X-Authorization-Filter HTTP header to override LDAP_AUTHORIZATION_FILTER. Defaults to True for backwards compatibility.

Warning

Setting this to True without properly configuring NGINX to control the X-Authorization-Filter header is a security risk. Malicious clients could send a permissive filter (e.g., (objectClass=*)) to bypass group-based authorization restrictions.

For secure deployments, set this to False and use only the LDAP_AUTHORIZATION_FILTER environment variable, or ensure your NGINX configuration explicitly sets or clears the header using proxy_set_header before forwarding requests.

Note

The default is True for backwards compatibility. Future versions may change the default to False for improved security.

See nginx_ldap_auth.settings.Settings.allow_authorization_filter_header for more details.

LDAP_TIMEOUT: The maximum number of seconds to wait when acquiring a connection to the LDAP server. Defaults to 15.

LDAP_MIN_POOL_SIZE: The minimum number of connections to keep in the LDAP connection pool. Defaults to 1.

LDAP_MAX_POOL_SIZE: The maximum number of connections to keep in the LDAP connection pool. Defaults to 30.

LDAP_POOL_CONNECTION_LIFETIME_SECONDS: The maximum number of seconds to keep a connection in the LDAP connection pool. Defaults to 20.