Chapter 4. Access Controls

Access to resources can be restricted by authorization rules based on an authenticated user and by non-user-based access controls. If non-user-based access controls are specified, they are applied first. Authentication is only performed if needed to evaluate authorization rules specified with Require directives. Access controls and authorization rules can be restricted to particular HTTP methods by enclosing them in <Limit> or <LimitExcept> blocks.

Access controls can also be implemented with mod_rewrite, and the mod_ssl module provides SSL-based access control features.

Non-User-Based Access Controls

The mod_authz_host module implements non-user-based access controls. These are usually host-based but can also be tied to environment variables. Hosts are specified by full or partial domain names, full or partial IP addresses, network/netmask pairs, or network/prefix-length pairs.

If authorization rules and non-user-based access controls are specified, the Satisfy directive determines whether requests have to satisfy either or both; authentication and authorization will be skipped if, having evaluated the access controls, Apache can determine definitively whether access is allowed or denied.

Allow

DH* (Limit)

mod_authz_host (B)

Allow from  { all | { host | env=var } ... }

Allows requests to a resource from the specified hosts or with the specified environment variable set.

Deny

DH* (Limit)

mod_authz_host (B)

Deny from  { all | { host | env=var } ... }

Denies requests to a resource from the specified hosts or with the specified environment variable set.

Order

DH (Limit)

mod_authz_host (B)

deny,allow

Order { allow,deny | deny,allow | mutual-failure }

Specifies the order in which Allow and Deny directives are evaluated.

allow,deny

Allow directives are applied before Deny directives. Any unmatched requests are denied.

deny,allow

Deny directives are applied before Allow directives. Any unmatched requests are allowed.

mutual-failure

Only requests that match an Allow directive and are not forbidden by a Deny directive are allowed.

Satisfy

DH (AuthConfig)

core

All

Satisfy { All | Any }

Policy applied if both authorization rules and non-user-based access controls are specified for a resource. All means that both sets of rules must be satisfied, whereas Any means that only one or the other needs to be satisfied, which can be used to allow nonauthenticated access from machines on a secure network while requiring accesses from other hosts to be authenticated.

Authentication

Authentication is the process of verifying that the client credentials required for authorization are valid. Authentication is skipped if no authorization is specified.

Authentication Setup

There are two schemes specified for HTTP authentication in RFC 2617: Basic and Digest. As of Apache 2.1, the handling of each scheme is implemented in a separate module, selected with the AuthType directive. Both schemes use realms to differentiate between protection spaces, and this is set with AuthName.

The mechanism for storing user credentials is delegated to authentication provider modules, selected with either AuthBasicProvider or AuthDigestProvider.

AuthDefaultAuthoritative

DH (AuthConfig)

mod_authn_default (B)

ON

AuthDefaultAuthoritative { ON | OFF }

mod_authn_default is an authentication fallback module that just rejects all credentials. If this directive is set to OFF, authentication will be passed to other modules; this may be useful in conjunction with third-party modules.

AuthName

DH (AuthConfig)

core

AuthName realm-name

Authentication realm for documents matched by the enclosing section. A realm identifies a set of resources residing on the same server and protected by the same set of passwords. Note that Apache does not prevent different, inconsistent authentication databases from being used within the same realm, which can lead to unpredictable results.

AuthType

DH (AuthConfig)

core

AuthType { Basic | Digest }

The authentication scheme to use.

HTTP Basic Authentication

The mod_auth_basic module implements HTTP Basic authentication. This scheme passes usernames and passwords across the network without encryption and cannot be not considered a secure method of authentication unless used in conjunction with SSL/TLS.

AuthBasicAuthoritative

DH (AuthConfig)

mod_auth_basic (E)

ON

AuthBasicAuthoritative { ON | OFF }

Normally, if none of the provider modules indicates successful authentication, mod_auth_basic will deny access with a 401 (Unauthorized) response. If this directive is set to OFF, authentication will fall back to other non-provider-based modules; this should only be necessary with third-party modules.

AuthBasicProvider

DH (AuthConfig)

mod_auth_basic (E)

file

AuthBasicProvider provider ...

Specifies the provider modules to be used to authenticate users when using Basic authentication; each module is called in turn until one indicates successful authentication or the list is exhausted. The modules, specified using the identifiers listed in Table 4-1, must be present in the server.

HTTP Digest Authentication

The mod_auth_digest module implements HTTP Digest authentication. Digest authentication addresses the serious security flaws in Basic authentication. Browser support for the scheme was once an issue, but that is less the case now; and although it is still marked as experimental, it is currently used in production environments.

AuthDigestAlgorithm

DH (AuthConfig)

mod_auth_digest (X)

MD5

AuthDigestAlgorithm { MD5 | MD5-sess }

Specifies the digest algorithm to be used. As of version 2.2.9, only the MD5 algorithm is working.

AuthDigestDomain

DH* (AuthConfig)

mod_auth_digest (X)

AuthDigestDomain uri ...

Specifies one or more URIs that are in the same protection space, i.e., that share the same realm, usernames, and passwords.

AuthDigestNcCheck

S

mod_auth_digest (X)

OFF

AuthDigestNcCheck { ON | OFF }

Documented as controlling whether checking of the server-generated nonce count is enabled; but as of version 2.2.9, the directive does nothing.

AuthDigestNonceFormat

DH (AuthConfig)

mod_auth_digest (X)

AuthDigestNonceFormat format

Documented as specifying the format of generated nonces; but as of version 2.2.9, the directive does nothing.

AuthDigestNonceLifetime

DH (AuthConfig)

mod_auth_digest (X)

300 seconds, i.e., 5 minutes

AuthDigestNonceLifetime secs

Specifies how long the server nonce is valid.

AuthDigestProvider

DH (AuthConfig)

mod_auth_digest (X)

file

AuthDigestProvider provider ...

Specifies the provider module to be used to authenticate users when using Digest authentication (see Table 4-1).

AuthDigestQop

DH* (AuthConfig)

mod_auth_digest (X)

auth

AuthDigestQop { none | auth | auth-int } [auth | auth-int ] ...

Specifies the quality of protection options to be used. auth provides authentication checking of username and password; auth-int provides authentication and integrity checking (but is not implemented as of version 2.2.9); none causes Apache to use the older RFC2069 standard, which does not include quality of protection options in the server response.

AuthDigestShmemSize

DH (AuthConfig)

mod_auth_digest (X)

1,000

AuthDigestShmemSize nbytes

The amount of shared memory to use to keep track of clients. nbytes may be suffixed with the letters K or M to specify values in kilobytes or megabytes respectively.

Authentication Providers

Authentication provider modules are responsible for managing authentication credentials using flat files, databases, or other storage mechanisms. The standard authentication providers are listed in Table 4-1.

Warning

Access control files and databases should be stored outside the document tree and adequately protected.

Table 4-1. Authentication provider identifiers

Identifier

Authentication source

anon

Anonymous authentication (mod_authn_dbm)

dbd

Relational database (mod_authn_dbd)

dbm

Embedded database file (mod_authn_dbm)

file

Plain text file (mod_authn_file)

ldap

LDAP server (mod_authnz_ldap)

user defined

Extended provider (mod_authn_alias)

Credentials Stored in Plain Text Files

Authentication against plain text password files is supported by the mod_authn_file provider module, which is identified as file. It is the default provider. This is the simplest mechanism to set up; however, searching through text files is inefficient for large numbers of users.

Password files used for Basic authentication files can be managed with the htpasswd utility. MD5, crypt(), and SHA password encryption methods are supported. For Digest authentication, the htdigest utility is used to manage password files.

AuthUserFile

DH (AuthConfig)

mod_authn_file (B)

AuthUserFile filename

The path to the plain text password file.

Credentials Stored in DBM Files

The mod_auth_dbm module is an authentication provider, identified as dbd, that supports storage of user credentials in DBM files. Depending on how it is built, a number of different DBM formats are supported. The files can be managed with the dbmmanage utility. The files can include group membership and encrypted passwords, so they can be used for authorization as well as authentication.

AuthDBMType

DH

mod_authn_dbm (E)

default

AuthDBMType { default | SDBM | GDBM | NDBM | DB }

Indicates the database file format for the user DBM file. The available formats are determined at compile time, as is the default type.

AuthDBMUserFile

DH (AuthConfig)

mod_authn_dbm (E)

AuthDBMUserFile filename

The path to the DBM file containing usernames and passwords for authentication.

Credentials Stored in a Relational Database

The mod_auth_dbd module is an authentication provider, identified as dbd, that allows usernames and passwords to be stored in a relational database. It relies on the mod_dbd module to access the underlying database.

AuthDBDUserPWQuery

D (AuthConfig)

mod_authn_dbd (E)

AuthDBDUserPWQuery query

The SQL query that is run to look up the password for a user. The query string should include the specifier %s, which will be replaced with the user’s ID.

AuthDBDUserRealmQuery

D (AuthConfig)

mod_authn_dbd (E)

AuthDBDUserRealmQuery query

The SQL query to be run to look up a user’s password. The user’s ID and realm are denoted in the query, in that order, by %s specifiers.

Anonymous Authentication

The mod_auth_anon module is an authentication provider, identified as anon, that allows anonymous authentication in a manner similar to anonymous FTP.

Anonymous

DH* (AuthConfig)

mod_authn_anon (E)

Anonymous username ...

List of magic usernames that are allowed access without password verification. Note that the usernames are case-insensitive and, if enclosed in double or single quotes, may include spaces.

Anonymous_LogEmail

DH (AuthConfig)

mod_authn_anon (E)

ON

Anonymous_LogEmail { ON | OFF }

If set to ON, the client’s password is logged to the error log.

Anonymous_MustGiveEmail

DH (AuthConfig)

mod_authn_anon (E)

ON

Anonymous_MustGiveEmail { ON | OFF }

If set to ON, the client must supply a nonblank password.

Anonymous_NoUserId

DH (AuthConfig)

mod_authn_anon (E)

OFF

Anonymous_NoUserId { ON | OFF }

If set to ON, an empty username is acceptable.

Anonymous_VerifyEmail

DH (AuthConfig)

mod_authn_anon (E)

OFF

Anonymous_VerifyEmail { ON | OFF }

If set to ON, the password is checked to ensure it contains an at sign (@) and a period (.), that is, that it looks at least vaguely like an email address.

Extended Authentication Providers

The mod_authn_alias allows extended authentication providers to be defined. These can then be referenced in multiple locations.

<AuthnProviderAlias>

S* (AuthConfig)

mod_authn_alias (E)

<AuthnProviderAlias base-provider alias >
    ...
</AuthnProviderAlias>

Compatibility: 2.1 and later

Defines alias as an extended authentication provider based on a base provider, with settings specified by the authentication directives enclosed in the container.

Authorization

Authorization is the process of verifying that an authenticated user is permitted to access a particular resource.

Authorization Setup

Each authorization rule is specified with a Require directive. The rules themselves are implemented by individual authorization modules.

AuthzDefaultAuthoritative

DH (AuthConfig)

mod_authz_default (E)

ON

AuthzDefaultAuthoritative { ON | OFF }

mod_authn_default is an authorization fallback module that just rejects any authorization request. If this directive is set to OFF, authorization will be passed to other modules; this may be useful in conjunction with third-party modules.

Require

DH* (AuthConfig)

core

Require requirement  [arg ...]

Authorization requirement for an authenticated user to be allowed access to a resource. The requirements implemented by standard authorization modules are as follows, with the modules implementing the requirement in parentheses:

file-group filename

The authenticated username must be a member of an authorization group that matches the name of the system group that owns the specified file (mod_authz_owner, and mod_authz_dbm or mod_authz_groupfile).

file-owner filename

The authenticated username must match the name of the system user that owns the specified file (mod_authz_owner).

group group ...

The authenticated username must be a member of one of the specified authorization groups (mod_authz_groupfile or mod_authz_dbm).

user user ...

The authenticated user must be one of the specified users (mod_authz_user).

valid-user

All authenticated users are authorized (mod_authz_user).

Explicit User Authorization

The mod_authz_user module implements two authorization rules: user to check the authenticated username against a specified list of usernames, and valid-user to treat all authenticated users as authorized.

AuthzUserAuthoritative

DH (AuthConfig)

mod_authz_user (E)

ON

AuthzUserAuthoritative { ON | OFF }

Specifies whether the mod_authz_user module is authoritative for authorization, or should fall back to other modules on failure.

Group Membership Stored in Plain Text Files

The mod_authz_groupfile module implements the group authorization rule, which checks the authenticated username against a list of groups stored in a plain text file. Each line consists of a group name followed by a colon and a space-separated list of the usernames of the members of the group. The module also provides support for the file-group rule.

AuthGroupFile

DH (AuthConfig)

mod_authz_groupfile (B)

AuthGroupFile filename

The name of the plain text file defining group membership.

AuthzGroupFileAuthoritative

DH (AuthConfig)

mod_authz_groupfile (E)

ON

AuthzGroupFileAuthoritative { ON | OFF }

Specifies whether the mod_authz_groupfile module is authoritative for authorization or should fall back to other modules on failure.

Group Membership Stored in DBM Files

The mod_authz_dbm module implements the group authorization rule, which checks the authenticated username against a DBM file. The key is the username, and the value contains a comma-separated list of groups to which the user belongs. Group membership may be stored in the user file by setting the group DBM file to be the same as the user DBM file, and by storing a comma-separated list of groups in the value for each user, separated from the password by a colon. The module also provides support for the file-group rule.

AuthDBMGroupFile

DH (AuthConfig)

mod_authz_dbm (E)

AuthDBMGroupFile filename

The path to the DBM file containing group membership lists for authentication.

AuthzDBMAuthoritative

DH (AuthConfig)

mod_authz_dbm (E)

ON

AuthzDBMAuthoritative { ON | OFF }

Specifies whether the mod_authz_dbm module is authoritative for authorization or should fall back to other modules on failure.

AuthzDBMType

SVDH* (AuthConfig)

mod_authz_dbm (E)

default

AuthzDBMType { default | SDBM | GDBM | NDBM | DB }

Specifies the database file format used for the group DBM file. The available formats are determined at compile time, as is the default type.

Authorization Based on File Ownership

The mod_authz_owner module implements the file-owner authorization rule, which checks the authenticated username against the name of the system owner who owns the file, and the file-group rule, which checks that the username is a member of the group owning the file. The latter rule requires a group authorization module.

AuthzOwnerAuthoritative

DH (AuthConfig)

mod_authz_owner (E)

ON

AuthzOwnerAuthoritative { ON | OFF }

Specifies whether the mod_authz_owner module is authoritative for authorization or should fall back to other modules on failure.

LDAP Authentication and Authorization

The mod_authnz_ldap module is both an authentication provider, named ldap, and an authorization module that authenticates against an LDAP server. It relies on the services of the mod_ldap module to access LDAP servers.

The module adds a number of authorization rules to the Require directive:

ldap-attribute attribute=value ...

The attributes of the user must match any of the attributes specified.

ldap-dn distinguished-name

The DN found in the search phase must match the specified value. Note that everything after ldap-group is regarded as a single argument and does not require quoting.

ldap-filter filter

The DN returned by the filter search must match the DN of the authenticated user.

ldap-group group-dn

The user must be a member of the specified LDAP group. Note that everything after ldap-group is regarded as a single argument and does not require quoting.

ldap-user user ...

Space-separated list of usernames. If the names contain spaces, they must be enclosed in quotes.

Other Require rules, such as valid-user, may be used with LDAP authentication. The appropriate authorization module must be present in the server, and AuthzLDAPAuthoritative must be set to OFF.

LDAP Configuration Directives

AuthLDAPCharsetConfig

S (AuthConfig)

mod_authnz_ldap (E)

AuthLDAPCharsetConfig filename

Pathname of the language to charset conversion configuration files.

AuthLDAPDereferenceAliases

DH (AuthConfig)

mod_authnz_ldap (E)

Always

AuthLDAPDereferenceAliases {Always|Searching|Finding|Never}

Specifies when mod_authnz_ldap should dereference aliases.

AuthLDAPRemoteUserAttribute

DH (AuthConfig)

mod_authnz_ldap (E)

AuthLDAPRemoteUserAttribute attribute

The value of the specified attribute will be used to set the REMOTE_USER environment variable. This directive takes precedence over the AuthLDAPRemoteUserIsDN directive.

AuthLDAPRemoteUserIsDN

DH (AuthConfig)

mod_authnz_ldap (E)

OFF

AuthLDAPRemoteUserIsDN { ON | OFF }

If set to ON, the value of the REMOTE_USER environment variable is set to the full DN of the authenticated user, rather than to the username supplied by the client.

AuthLDAPUrl

DH (AuthConfig)

mod_authnz_ldap (E)

AuthLDAPUrl scheme:host:port/basedn?attr?scope?filter  [ctype]

RFC2255 URL specifying the LDAP search parameters and an optional connection type; scheme is either ldap or ldaps; port defaults to 389 for ldap and 636 for ldaps. Although LDAP allows multiple attributes to be specified in a URL and separated by commas, only the first one is used, and it defaults to uid. scope is either one or sub, defaulting to sub. The default filter is objectClass=*.

The optional ctype parameter overrides the connection type. It may be NONE for an unsecure connection, SSL for a secure connection on the default ldaps port, or TLS or STARTTLS for an upgraded secure connection on the default LDAP port.

Authentication Phase Directives

This phase is also called the search/bind phase, as mod_authnz_ldap searches for the username supplied by the HTTP client and attempts to bind to the LDAP server with the resulting DN and the password supplied by the client.

AuthLDAPBindDN

DH (AuthConfig)

mod_authnz_ldap (E)

AuthLDAPBindDN DN

Optional DN to use when binding to the LDAP server for the search. If not specified, an anonymous bind is used.

AuthLDAPBindPassword

DH (AuthConfig)

mod_authnz_ldap (E)

AuthLDAPBindPassword password

Password to use in conjunction with AuthLDAPBindDB.

Authentication Phase Directives

This is also known as the compare phase, as many of the authorization rules require LDAP comparisons.

AuthzLDAPAuthoritative

DH (AuthConfig)

mod_authnz_ldap (E)

ON

AuthzLDAPAuthoritative { ON | OFF }

Specifies whether the mod_authnz_ldap module is authoritative for authorization or should fall back to other modules on failure.

AuthLDAPCompareDNOnServer

DH (AuthConfig)

mod_authnz_ldap (E)

ON

AuthLDAPCompareDNOnServer { ON | OFF }

If set to ON, DNs are compared on the LDAP server; otherwise, a simple string comparison is done.

AuthLDAPGroupAttribute

DH* (AuthConfig)

mod_authnz_ldap (E)

AuthLDAPGroupAttribute attribute ...

Specifies the LDAP attributes that are used to check for group membership. If this directive is not included, then the member and uniquemember attributes are used.

AuthLDAPGroupAttributeIsDN

DH (AuthConfig)

mod_authnz_ldap (E)

ON

AuthLDAPGroupAttributeIsDN { ON | OFF }

If set to ON, the DN of the client is used when checking for group membership; otherwise, the username is used.

Get Apache 2 Pocket Reference now with the O’Reilly learning platform.

O’Reilly members experience books, live events, courses curated by job role, and more from O’Reilly and nearly 200 top publishers.