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,denyAllowdirectives are applied beforeDenydirectives. Any unmatched requests are denied.deny,allowDenydirectives are applied beforeAllowdirectives. Any unmatched requests are allowed.mutual-failureOnly requests that match an
Allowdirective and are not forbidden by aDenydirective 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-nameAuthentication 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.
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 formatDocumented as specifying the format of generated nonces; but as of version 2.2.9, the directive does nothing.
AuthDigestNonceLifetime
mod_auth_digest (X)
300 seconds, i.e., 5 minutes
AuthDigestNonceLifetime secsSpecifies 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.
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.
Identifier | Authentication source |
| Anonymous authentication (mod_authn_dbm) |
| Relational database (mod_authn_dbd) |
| Embedded database file (mod_authn_dbm) |
| Plain text file (mod_authn_file) |
| 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.
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.
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.
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_MustGiveEmail
DH (AuthConfig)
mod_authn_anon (E)
ON
Anonymous_MustGiveEmail { ON | OFF }
If set to ON, the client must supply a nonblank password.
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-groupfilenameThe 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-ownerfilenameThe authenticated username must match the name of the system user that owns the specified file (mod_authz_owner).
groupgroup...The authenticated username must be a member of one of the specified authorization groups (mod_authz_groupfile or mod_authz_dbm).
useruser...The authenticated user must be one of the specified users (mod_authz_user).
valid-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.
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.
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 filenameThe path to the DBM file containing group membership lists for authentication.
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.
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-attributeattribute=value...The attributes of the user must match any of the attributes specified.
ldap-dndistinguished-nameThe DN found in the search phase must match the specified value. Note that everything after
ldap-groupis regarded as a single argument and does not require quoting.ldap-filterfilterThe DN returned by the filter search must match the DN of the authenticated user.
ldap-groupgroup-dnThe user must be a member of the specified LDAP group. Note that everything after
ldap-groupis regarded as a single argument and does not require quoting.ldap-useruser...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 filenamePathname 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 attributeThe 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
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.
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.
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.
