diff --git a/ci/vale/dictionary.txt b/ci/vale/dictionary.txt index 8d0ed4697d8..b3c2d9299fa 100644 --- a/ci/vale/dictionary.txt +++ b/ci/vale/dictionary.txt @@ -184,6 +184,7 @@ basename bashdoor bashrc bc +bcrypt bdd bellovin benchmarked diff --git a/docs/guides/web-servers/apache-tips-and-tricks/rulebased-access-control-for-apache/RBAC_Apache.jpg b/docs/guides/web-servers/apache-tips-and-tricks/rulebased-access-control-for-apache/RBAC_Apache.jpg deleted file mode 100644 index 58eb0843269..00000000000 Binary files a/docs/guides/web-servers/apache-tips-and-tricks/rulebased-access-control-for-apache/RBAC_Apache.jpg and /dev/null differ diff --git a/docs/guides/web-servers/apache-tips-and-tricks/rulebased-access-control-for-apache/index.md b/docs/guides/web-servers/apache-tips-and-tricks/rulebased-access-control-for-apache/index.md deleted file mode 100644 index c61d2ec67bd..00000000000 --- a/docs/guides/web-servers/apache-tips-and-tricks/rulebased-access-control-for-apache/index.md +++ /dev/null @@ -1,118 +0,0 @@ ---- -slug: rulebased-access-control-for-apache -title: 'Rule-based Access Control for Apache' -description: 'Deploying and configuring granular access control with the Apache web server.' -authors: ["Linode"] -contributors: ["Linode"] -published: 2009-12-07 -modified: 2017-08-30 -keywords: ["apache", "access control", "security", "http", "web server"] -license: '[CC BY-ND 4.0](https://creativecommons.org/licenses/by-nd/4.0)' -aliases: ['/web-servers/apache/configuration/rule-based-access-control/','/websites/apache-tips-and-tricks/rulebased-access-control-for-apache/','/web-servers/apache-tips-and-tricks/rulebased-access-control-for-apache/'] -external_resources: - - '[LAMP Stack Guides](/docs/lamp-guides/)' - - '[Apache Configuration and Administration](/docs/web-servers/apache/)' - - '[Apache Configuration Basics](/docs/guides/apache-configuration-basics/)' - - '[Apache Configuration Structure](/docs/guides/apache-configuration-structure/)' - - '[Auth-based Access Control](/docs/guides/apache-access-control/)' - - '[Apache Troubleshooting](/docs/guides/troubleshooting-common-apache-issues/)' - - '[Apache Documentation](http://httpd.apache.org/docs/2.2/sections.html)' - - '[Apache Access Control](http://httpd.apache.org/docs/2.0/mod/mod_access.html#allow)' -tags: ["web server","apache"] ---- - -![Rule-based Access Control for Apache](RBAC_Apache.jpg) -Apache provides a number of tools that allow administrators to control access to specific resources provided by servers. You may already be familiar with [authentication based access controls](/docs/guides/apache-configuration-structure/), which requires that visitors authenticate to the server before gaining access to resources. - - - Apache's rule-based access control allows you to specify which visitors have access to which resources on a very granular level. You can create rules which block a given range of IPs from your web server, or from accessing a particular resource, or even simply from accessing a particular virtual host. - -The most basic use of rule-based access control is to place firm limits on what resources are accessible over the network connection. In the default Apache configuration, the web server denies all users access to all files on the system. Then Apache permits administrators to allow access to specific resources. - -Additional uses for these access rules include blocking particular IP ranges that have been responsible for malicious traffic and limiting access to a given resource or set of resources to "internal users," among a number of other possibilities. - -We assume that you have a working installation of Apache and have access to modify configuration files. If you have not installed Apache, you might want to follow one of our [Apache installation guides](/docs/web-servers/apache/) or [LAMP stack installation guides](/docs/lamp-guides/). If you want a more thorough introduction to Apache configuration, please reference our [Apache HTTP server configuration basics](/docs/guides/apache-configuration-basics/) and [Apache configuration structure](/docs/guides/apache-configuration-structure/) guides. - -## Examples of Rule Based Access Control - -You may wish to consult our [Apache configuration structure](/docs/guides/apache-configuration-structure/) guide to see a number of examples of these directives in practice. - -Here is an example of a basic rule: - -{{< file "Apache Configuration Directive" apache >}} -Order Deny,Allow -Deny from all -Allow from 192.168.2.101 - -{{< /file >}} - - -To parse this in more simple terms: - -- The `Order Deny,Allow` directive tells the web server that "Deny" rules should be processed before Allow rules. -- The `Deny from all` directive tells the web server that all users should be denied access to the given resource. This rule is processed first. -- The `Allow from` directive tells the web server that requests originating at the IP address `192.168.2.101` should be allowed. This is processed last, and represents an exception to the `Deny from all` rule. - -In short, all hosts except for `192.168.2.101` are denied access to this resource. - -## Additional Access Control Rules - -You can specify granular access control rules for your resources by modifying and expanding the example above. The following notes and suggestions provide some insight into some of the more advanced functionality that is possible with these access control systems. - -### Controlling Access for a Range of IPs - -If you want to control access for a range of IP addresses rather than for a single address, Apache permits this with the following syntax: - -{{< file "Apache Configuration Directive" apache >}} -Order Deny,Allow -Deny from all -Allow from 192.168 -Allow from 10 - -{{< /file >}} - - -The above statements allow all addresses that begin with `192.168` and `10`. These IP ranges are typically reserved for Local networking and are not publicly routable addresses. If used, these access control rules will only allow traffic from "local sources" on the network. - -Here is an additional example of an access rule: - -{{< file "Apache Configuration Directive" apache >}} -Order Allow,Deny -Allow from all -Deny from 185.201.1 - -{{< /file >}} - - -This rule allows everyone access to the given resource, and then denies access to all IP addresses beginning with `185.201.1`. This statement would cover all traffic originating from the range of IP addresses from `185.201.1.0` to `185.201.1.255`. - -When creating access control rules, particularly ones that use the `Allow from all` directive, be very sure that these directives are situated in the proper context. - -### Advanced Access Control - -While IP address are by far the easiest way to control access using these access control rules, Apache provides a number of additional methods. - -Firstly, Apache permits administrators to allow or deny access based on the hostname of the requester. This forces Apache to do a reverse DNS (rDNS) lookup of the hostname performing the request, and then allow or deny access based on this information. Consider this example: - -{{< file "Apache Configuration File" apache >}} -Order Deny,Allow -Deny from all -Allow from hostname.example.com - -{{< /file >}} - - -Apache only allows requests from the machine with valid rDNS of `hostname.example.com` to access the resource in this configuration. - -Secondly, it's possible to build access rules around environment variables in the HTTP session. This allows you to allow and deny access to resources on the basis of variables such as browser (user agent) and referrer. Let us take the following example: - -{{< file "Apache Configuration File" apache >}} -SetEnvIf Referer searchenginez.com search_traffic -Order Deny,Allow -Deny from all -Allow from env=search_traffic - -{{< /file >}} - - -This access control rule works in conjunction with Apache's `mod_setenvif`. First, if a request's referrer matches `searchenginez.com` the environment variable `search_traffic` is set. Next, all hosts are denied access to the resource. Finally, requests that have the environment variable `search_traffic` set are allowed access to the resource. Please consult the official Apache documentation for [mod\_setenvif](http://httpd.apache.org/docs/2.2/mod/mod_setenvif.html) for more information about setting and using environment variables. diff --git a/docs/guides/web-servers/apache/apache-access-control/index.md b/docs/guides/web-servers/apache/apache-access-control/index.md index 3c6b8d74932..343d3da7507 100644 --- a/docs/guides/web-servers/apache/apache-access-control/index.md +++ b/docs/guides/web-servers/apache/apache-access-control/index.md @@ -1,144 +1,323 @@ --- slug: apache-access-control -title: 'Apache Access Control' -description: 'Using HTTP AUTH to limit and control access to resources hosted on websites.' -authors: ["Linode"] -contributors: ["Linode"] +title: "Access control in Apache" +description: "Learn how to configure rule-based access control in Apache using the modern Require directive introduced in Apache 2.4. This guide covers IP- and host-based restrictions, rule combinations, and migration from legacy Apache 2.2 configurations." +og_description: "Learn how to configure rule-based access control in Apache using the modern Require directive introduced in Apache 2.4. This guide covers IP- and host-based restrictions, rule combinations, and migration from legacy Apache 2.2 configurations." +authors: ["Akamai"] +contributors: ["Akamai"] published: 2009-12-07 -modified: 2015-11-20 -keywords: ["access control", "http auth", "mod_auth", "http", "apache", "web server", "security"] -tags: ["http","web server","apache","security"] +modified: 2026-05-26 +keywords: ['apache', 'apache 2.4', 'access control', 'require directive', 'web server security'] license: '[CC BY-ND 4.0](https://creativecommons.org/licenses/by-nd/4.0)' -aliases: ['/web-servers/apache/configuration/http-authentication/','/websites/apache/apache-access-control/','/web-servers/apache/apache-access-control/','/guides/authbased-access-control-with-apache/','/websites/apache/authbased-access-control-with-apache/','/web-servers/apache/authbased-access-control-with-apache/','/websites/authbased-access-control-with-apache/'] +aliases: ['/guides/rulebased-access-control-for-apache/','/web-servers/apache/configuration/rule-based-access-control/','/websites/apache-tips-and-tricks/rulebased-access-control-for-apache/','/web-servers/apache-tips-and-tricks/rulebased-access-control-for-apache/','/websites/apache/apache-access-control/','/web-servers/apache/apache-access-control/'] external_resources: - - '[Installation of the Apache web server](/docs/web-servers/apache/)' - - '[LAMP stack guides](/docs/web-servers/lamp/)' - - '[Authentication and Access Control](http://httpd.apache.org/docs/2.2/howto/auth.html)' - - '[Basic Authentication Module](http://httpd.apache.org/docs/2.2/mod/mod_auth_basic.html)' + - '[Apache authorization documentation](https://httpd.apache.org/docs/2.4/howto/access.html)' + - '[mod_authz_core documentation](https://httpd.apache.org/docs/2.4/mod/mod_authz_core.html)' +tags: ["web server","apache"] --- -While most web server content is created to be available to the public, you may want to restrict some or all of a website to specific users or groups. **HTTP Auth** lets you easily create these restrictions. +Rule-based access control in Apache determines which clients can access specific resources on your server. Apache 2.4 introduced a new authorization model based on the `Require` directive, replacing the deprecated `Order`, `Allow`, and `Deny` directives used in earlier versions. -This guide provides an overview of both credential-based and rule-based access control tools for Apache. +Access control is a fundamental part of securing web applications. By restricting access at the web server level, you can prevent unauthorized users from reaching sensitive resources before application logic is ever executed. Common use cases include limiting access to administrative interfaces, internal tools, staging environments, or API endpoints. -## Before You Begin +This guide demonstrates how to configure access control using modern Apache 2.4 directives. For password-protected resources and user authentication, see our [HTTP Basic authentication in Apache](/docs/guides/apache-http-basic-authentication/) guide. -1. If you have not already done so, create a Linode account and Compute Instance. See our [Getting Started with Linode](/docs/products/platform/get-started/) and [Creating a Compute Instance](/docs/products/compute/compute-instances/guides/create/) guides. +## Before you begin -1. Follow our [Setting Up and Securing a Compute Instance](/docs/products/compute/compute-instances/guides/set-up-and-secure/) guide to update your system and configure your hostname. You may also wish to set the timezone, create a limited user account, and harden SSH access. +1. If you do not already have a virtual machine to use, create a compute instance with at least 4 GB of memory. See our [Get started](https://techdocs.akamai.com/cloud-computing/docs/getting-started) and [Create a Linode](https://techdocs.akamai.com/cloud-computing/docs/create-a-compute-instance) guides. - To check your hostname run: +1. Follow our [Set up and secure a Linode](https://techdocs.akamai.com/cloud-computing/docs/set-up-and-secure-a-compute-instance) guide to update your system. You may also wish to set the timezone, configure your hostname, create a limited user account, and harden SSH access. - hostname - hostname -f +1. Install Apache HTTP Server 2.4 or later on your system: - The first command should show your short hostname, and the second should show your fully qualified domain name (FQDN) if you have one assigned. + ```command {title="Debian-based Linux distributions"} + sudo apt update + sudo apt install apache2 -y + ``` + + ```command {title="RHEL-based Linux distributions"} + sudo dnf install httpd -y + ``` + +1. Ensure that you have root or `sudo` privileges to edit configuration files. {{< note >}} This guide is written for a non-root user. Commands that require elevated privileges are prefixed with `sudo`. If you're not familiar with the `sudo` command, you can check our [Users and Groups](/docs/guides/linux-users-and-groups/) guide. - -This guide uses the same example file paths as our [Apache on Debian 8](/docs/guides/apache-web-server-debian-8/) guide. Be sure to adjust for your distribution. {{< /note >}} -## Apache Access Control +## Understanding rule-based access control in Apache 2.4 + +In Apache 2.4, authorization is explicit and rule-based. Instead of relying on evaluation order, each `Require` directive defines a condition that must be met. These conditions can be combined to create precise access policies without relying on implicit behavior. + +Access control rules are typically applied in `` and `` blocks within virtual host configuration files. + +The exact configuration file location depends on your Linux distribution and Apache deployment. Debian-based systems commonly use site-specific virtual host configuration files in `/etc/apache2/sites-available/`, such as `/etc/apache2/sites-available/000-default.conf`. RHEL-based systems often use `/etc/httpd/conf/httpd.conf` or site-specific files in `/etc/httpd/conf.d/`. + +Access control rules can also be applied via `.htaccess` files. + +Most access control functionality is provided by the `mod_authz_core` and `mod_authz_host` modules. These modules are enabled by default in most Apache installations. + +## Basic access control rules + +These directives are typically used to establish a default policy. For example, you might deny all access by default and then selectively allow specific clients. + +Use the `Require` directive to define access control rules. + +```file {title="Apache virtual host configuration file" lang="apache"} +Require all granted +``` + +```file {title="Apache virtual host configuration file" lang="apache"} +Require all denied +``` + +These rules are often used as a baseline before applying more specific restrictions. + +Restrict access to requests originating from the local system: + +```file {title="Apache virtual host configuration file" lang="apache"} +Require local +``` + +You can also negate a condition with `Require not` to exclude specific clients while allowing broader access: + +```file {title="Apache virtual host configuration file" lang="apache"} +Require all granted +Require not ip 192.168.1.50 +``` + +## Restricting access by IP address + +IP-based restrictions are the most common form of access control. They are fast, reliable, and do not depend on DNS resolution. + +Use `Require ip` to allow specific IP addresses or subnets. + +Allow a single IP: + +```file {title="Apache virtual host configuration file" lang="apache"} +Require ip 192.168.1.10 +``` + +Allow a subnet: + +```file {title="Apache virtual host configuration file" lang="apache"} +Require ip 192.168.1.0/24 +``` + +Allow an IPv6 subnet: + +```file {title="Apache virtual host configuration file" lang="apache"} +Require ip 2001:db8::/32 +``` + +Allow multiple networks: + +```file {title="Apache virtual host configuration file" lang="apache"} +Require ip 192.168.1.0/24 +Require ip 10.0.0.0/8 +``` + +## Restricting access by hostname + +Hostname-based rules can be useful in environments where clients are identified by domain rather than fixed IP addresses. + +Use `Require host` to match client hostnames: + +```file {title="Apache virtual host configuration file" lang="apache"} +Require host example.com +``` + +Hostname-based rules rely on reverse DNS lookups and can introduce latency or inconsistencies. Prefer IP-based rules when possible. + +## Combining access rules + +Combine rules using containers to express logical relationships between conditions. For example, requiring multiple conditions to be true, or allowing access if any one condition is satisfied. + +### RequireAll + +The `RequireAll` container allows access only if all of the enclosed conditions are met. This is useful for enforcing multiple requirements at the same time. + +```file {title="Apache virtual host configuration file" lang="apache"} + + Require ip 192.168.1.0/24 + Require not ip 192.168.1.50 + +``` + +### RequireAny + +The `RequireAny` container allows access if any of the enclosed conditions are met. This is useful when multiple independent conditions should grant access. + +```file {title="Apache virtual host configuration file" lang="apache"} + + Require ip 192.168.1.0/24 + Require ip 10.0.0.0/8 + +``` + +### RequireNone + +The `RequireNone` container excludes requests that match any of the enclosed conditions. Because `RequireNone` cannot grant access on its own, use it inside a broader rule such as `RequireAll`: + +```file {title="Apache virtual host configuration file" lang="apache"} + + Require all granted + + Require ip 203.0.113.10 + + +``` -To enable passwords for a directory, insert the following lines into the appropriate `` section of an Apache configuration file. You may also insert authentication information in an `.htaccess` file or in a virtual host configuration section. The required directives are: +In most cases, `Require not` is a simpler alternative, but `RequireNone` is useful when grouping multiple exclusion rules. -{{< file "Apache Configuration File" apache >}} -AuthType Basic -AuthUserFile /var/www/example.com/.htpasswd -AuthName "Sign In Here To Gain Access To the Site" -Require valid-user +## Applying access control rules -{{< /file >}} +The following example demonstrates how to apply an access control rule to a specific directory and verify the result. +1. Create a test directory and file: -* The `AuthType` directive specifies which authentication method Apache should use when connecting with clients. `Basic` requires that passwords be sent as **clear text** over the network. As a result we don't recommend using this to protect sensitive resources. + ```command + sudo mkdir -p /var/www/html/private + echo "private test" | sudo tee /var/www/html/private/index.html + ``` -* The `AuthUserFile` specifies the path (in full) to the password file where the passwords are stored. In this example we're using the path `/var/www/example.com/.htpassword`. This is one directory above the `public_html` folder, preventing accidental exposure of the file. By default, all files beginning with `.ht` are not web-accessible in most default configurations of Apache, but this should not be assumed. +1. Edit your Apache virtual host configuration file: + ```command {title="Debian-based Linux distributions"} + sudo nano /etc/apache2/sites-available/000-default.conf + ``` -* The `AuthName` directive contains the message browser uses to inform the user of what resource they're authenticating to. The value is arbitrary. + ```command {title="RHEL-based Linux distributions"} + sudo nano /etc/httpd/conf/httpd.conf + ``` -* The `Require valid-user` setting simply tells Apache that any valid user can authenticate. + Add a rule to restrict access to a directory: -At this point we need to create a password file. + ```file {title="Apache virtual host configuration file" lang="apache"} + + Require ip 192.168.1.0/24 + + ``` -## Generating HTTP AUTH Passwords + When done, press CTRL+X, followed by Y then Enter to save the file and exit `nano`. -To generate passwords, we need the `htpasswd` tool. For many distributions, this tool may have been installed when you installed Apache itself. Debian and Ubuntu users will have to install the `apache2-utils` package with the following commands: +1. Test the Apache configuration: - sudo apt-get install apache2-utils + ```command {title="Debian-based Linux distributions"} + sudo apachectl configtest + ``` -To create a new file with a single user, issue the following command: + ```command {title="RHEL-based Linux distributions"} + sudo httpd -t + ``` - htpasswd -c /var/www/example.com/.htpasswd username + ```output + Syntax OK + ``` -In this example, we create a new `AuthUserFile` with the `-c` option. The file is located at `/var/www/example.com/.htpasswd` and the user name is `username`. `htpasswd` will prompt you to enter a password and then confirm the password. If you have an existing file, omit the `-c` option. + {{< note type="primary" title="AH00558 warning" >}} + If you see an `AH00558` warning about the server's fully qualified domain name, Apache was unable to determine a global `ServerName`. This warning does not indicate a syntax error and does not prevent Apache from starting. + {{< /note >}} -The `-b` option allows you to enter the password as the last parameter of the command, as in this example : +1. Restart Apache to apply changes: - htpasswd -b /srv/auth/.htpasswd username 5t1ck6 + ```command {title="Debian-based Linux distributions"} + sudo systemctl restart apache2 + ``` -The `AuthUserFile` will, when populated look something like this: + ```command {title="RHEL-based Linux distributions"} + sudo systemctl restart httpd + ``` -{{< file "/var/www/example.com/.htpasswd" >}} -hobby:isiA3Q4djD/.Q -admin:{SHA}x9VvwHI6dmgk9VTE0A8o6hbCw2s= -username:\$apr1\$vVzQJxvX\$6EyHww61nnZr6IdQv0pVx/ +1. Verify access to the restricted directory from an allowed IP address: -{{< /file >}} + ```command + curl -I http://your-server-ip/private/ + ``` + ```output + HTTP/1.1 200 OK + ``` -Each user is specified on their own line. Each line follows the form `[username]:[hash]`, where the `[hash]` is a cryptographic hash of the users' password. This provides one-way encryption and some small measure of additional security. + {{< note type="primary" title="Testing from an external client" >}} + If you are testing from another system, ensure HTTP traffic on port 80 is allowed by any local firewall applications or Akamai Cloud Firewall. Otherwise, the request may time out before reaching Apache. + {{< /note >}} -In the above example, the first `hobby` user's password is hashed using the "CRYPT" method, which is the default. This is not considered a secure encryption mechanism. If you specify the `-s` option in the `htpasswd` command, the password will be hashed with the SHA algorithm as in the second line of the above example. Finally, if you specify the `-m` option, `htpasswd` will use the MD5 hash to store the password. We recommend using either the SHA or the MD5 hash. +1. Attempt to access the restricted directory from a blocked IP address: -Additionally, if you would prefer to organize and maintain the `AuthUserFile` yourself, you can still use the `htpasswd` tool to generate the user entries. By specifying the `-n` option the program will output the appropriate line in the terminal. In the following example, the `htpasswd` entry is followed by the output of the command: + ```command + curl -I http://your-server-ip/private/ + ``` - htpasswd -nbs user2 strongpassword - user2:{SHA}KuhoB50pPgoYXGcce82sUd8244U= + ```output + HTTP/1.1 403 Forbidden + ``` -You can now append the `user2:{SHA}KuhoB50pPgoYXGcce82sUd8244U=` line to your `AuthUserFile` manually. Once this line is in the password file, the `betty` user credentials will be able to authenticate the HTTP server. +### Using `.htaccess` -## Access Control Lists with Groups +You can apply rules in a `.htaccess` file when you cannot modify the main configuration: -In the `Require` directive above we specified the `valid-user`. This told Apache that any user who could authenticate against one of the users specified in the `AuthUserFile` could gain access to the site. While you can maintain separate password files for different resources, this is difficult to maintain for deployments with complex authentication needs. +```file {title="/var/www/html/.htaccess"} +Require all denied +``` -To address this need, Apache allows you to use a single `AuthUserFile`, containing all users that will need to authenticate to the server. To limit the set of valid credentials to a specific subset of the users listed in the `.htpasswd` file, we must specify users in the `Require` directive. Only users specified after the `Require user` directive will be permitted to access the specified resource. For example: +`.htaccess` files introduce performance overhead and should only be used when necessary. -{{< file "Apache configuration option" >}} -Require user username admin +## Migrating from Apache 2.2 -{{< /file >}} +Apache 2.2 used a different access control model based on `Order`, `Allow`, and `Deny`. +Because the underlying authorization model changed significantly, older configurations may not behave as expected when copied directly into Apache 2.4 without modification. -Given this directive, the users `username` and `admin` will be able to log into the resource. Any subset of users can be specified on the `Require` line. Apache also provides the ability to organize users into groups, and then permit access to resources based on group membership. The configuration directives for this setup would look like this: +| Apache 2.2 Directive | Apache 2.4 Equivalent | +|---------------------|----------------------| +| `Allow from all` | `Require all granted` | +| `Deny from all` | `Require all denied` | +| `Allow from 192.168.1.0/24` | `Require ip 192.168.1.0/24` | +| `Deny from 192.168.1.10` | `Require not ip 192.168.1.10` | -{{< file "Apache configuration file" apache >}} -AuthType Basic -AuthUserFile /srv/auth/.htpasswd -AuthGroupFile /srv/auth/.htgroup -Require group Authorized +Example conversion: -{{< /file >}} +```file {title="Apache virtual host configuration file" lang="apache"} +# Apache 2.2 +Order deny,allow +Deny from all +Allow from 192.168.1.0/24 +``` +```file {title="Apache virtual host configuration file" lang="apache"} +# Apache 2.4 +Require ip 192.168.1.0/24 +``` -In this example, we cite the same `AuthUserFile`, but we add an `AuthGroupFile` that specifies user groups. The group file contains a list of user groups and the usernames associated with each group. The `htgroup` file, like the `htpasswd` file, can be located anywhere on the file system. For clarity's sake, we recommend that `htgroup` be in the same directory as the `htpasswd` file. Here is an example of an `htgroup` file: +Apache 2.4 includes the `mod_access_compat` module for backward compatibility. Avoid using it in new configurations. -{{< file "/var/www/example.com/.htgroup" >}} -Authorized: username username2 -Team: admin hobby +## Common access control patterns -{{< /file >}} +The following examples demonstrate common real-world use cases for access control in Apache. +Restrict an admin directory: -Given this `htgroup` file, only the users `username` and `username2` will have access to the above listed resource. The syntax of the group file follows a simple `[groupname]: [username 1] [username 2] [...]`. You can put as many usernames from your `AuthUserFile` into a group entry as you need for the particular resource. +```file {title="Apache virtual host configuration file" lang="apache"} + + Require ip 192.168.1.0/24 + +``` -## The Caveats of HTTP Authentication +Block a specific IP: -- The `AuthType Basic` directive means credentials are sent unencrypted, which makes HTTP AUTH particularly subject to "man-in-the-middle" attacks. As a result, this authentication method shouldn't be used for protecting sensitive information without first encrypting the traffic over SSL. +```file {title="Apache virtual host configuration file" lang="apache"} + + Require all granted + Require not ip 203.0.113.10 + +``` -- In HTTP AUTH session authentication credentials must be exchanged between the client and the server for every request. While most client software can cache this information so that the user only has to enter the username and password once, the authentication credentials must be passed for every request. This can add additional network overhead. +Allow multiple trusted networks: -- When Apache processes an HTTP AUTH request it must parse through the entire `htpasswd` file. When the file only stores a few passwords the processing time is negligible, but when password files grow, requests can longer to process. +```file {title="Apache virtual host configuration file" lang="apache"} + + Require ip 192.168.1.0/24 + Require ip 10.0.0.0/8 + +``` \ No newline at end of file diff --git a/docs/guides/web-servers/apache/apache-http-basic-authentication/index.md b/docs/guides/web-servers/apache/apache-http-basic-authentication/index.md new file mode 100644 index 00000000000..9bd6c108275 --- /dev/null +++ b/docs/guides/web-servers/apache/apache-http-basic-authentication/index.md @@ -0,0 +1,132 @@ +--- +slug: apache-http-basic-authentication +title: 'HTTP Basic authentication in Apache' +description: "Configure HTTP Basic authentication in Apache using password files, authenticated users, and group-based access restrictions." +og_description: "Configure HTTP Basic authentication in Apache using password files, authenticated users, and group-based access restrictions." +authors: ["Linode"] +contributors: ["Linode"] +published: 2009-12-07 +modified: 2026-05-28 +keywords: ["apache", "http authentication", "basic authentication", "htpasswd", "web server security"] +tags: ["http","web server","apache","security"] +license: '[CC BY-ND 4.0](https://creativecommons.org/licenses/by-nd/4.0)' +aliases: ['/web-servers/apache/configuration/http-authentication/','/guides/authbased-access-control-with-apache/','/websites/apache/authbased-access-control-with-apache/','/web-servers/apache/authbased-access-control-with-apache/','/websites/authbased-access-control-with-apache/'] +external_resources: + - '[Apache authentication and authorization](https://httpd.apache.org/docs/2.4/howto/auth.html)' + - '[mod_auth_basic documentation](https://httpd.apache.org/docs/2.4/mod/mod_auth_basic.html)' +--- + +While most web server content is created to be available to the public, you may want to restrict some or all of a website to specific users or groups. Apache HTTP authentication lets you easily create these restrictions. HTTP authentication verifies a user's identity before Apache grants access to protected resources. + +This guide explains how to configure HTTP Basic authentication in Apache using password files, authenticated users, and group-based access restrictions. For IP- and host-based restrictions, see our [Access control in Apache](/docs/guides/apache-access-control/) guide. + +## Before you begin + +1. If you do not already have a virtual machine to use, create a compute instance with at least 4 GB of memory. See our [Get started](https://techdocs.akamai.com/cloud-computing/docs/getting-started) and [Create a Linode](https://techdocs.akamai.com/cloud-computing/docs/create-a-compute-instance) guides. + +1. Follow our [Set up and secure a Linode](https://techdocs.akamai.com/cloud-computing/docs/set-up-and-secure-a-compute-instance) guide to update your system. You may also wish to set the timezone, configure your hostname, create a limited user account, and harden SSH access. + +{{< note >}} +This guide is written for a non-root user. Commands that require elevated privileges are prefixed with `sudo`. If you're not familiar with the `sudo` command, you can check our [Users and Groups](/docs/guides/linux-users-and-groups/) guide. +{{< /note >}} + +## Configure HTTP Basic authentication + +To require users to authenticate before accessing a directory, add the following directives to the appropriate `` block, virtual host configuration, or `.htaccess` file. In most cases, prefer the main Apache configuration files over `.htaccess` files because they avoid per-request filesystem lookups and provide better performance: + +```file {title="Apache configuration file" lang="apache"} +AuthType Basic +AuthUserFile /var/www/example.com/.htpasswd +AuthName "Authentication Required" +Require valid-user +``` + +- The `AuthType` directive specifies which authentication method Apache should use when connecting with clients. Basic authentication sends credentials encoded but not encrypted over the network. As a result, you should always use HTTPS when protecting resources with Basic authentication. +- The `AuthUserFile` directive specifies the full path to the password file where passwords are stored. In this example we're using the path `/var/www/example.com/.htpasswd`. This is one directory above the `public_html` folder, preventing accidental exposure of the file. By default, all files beginning with `.ht` are not web-accessible in most default configurations of Apache, but this should not be assumed. +- The `AuthName` directive contains the message the browser uses to inform the user of what resource they're authenticating to. The value is arbitrary. +- The `Require valid-user` setting simply tells Apache that any valid user can authenticate. + +At this point you must create a password file. + +## Generating passwords for HTTP Basic authentication + +To generate passwords, we need the `htpasswd` tool. In some distributions, this tool is installed alongside Apache automatically. Debian and Ubuntu users will have to install the `apache2-utils` package with the following commands: + +```command {title="Debian-based Linux distributions"} +sudo apt install apache2-utils +``` + +```command {title="RHEL-based Linux distributions"} +sudo dnf install httpd-tools +``` + +To create a new file with a single user, issue the following command: + +```command +htpasswd -c /var/www/example.com/.htpasswd username +``` + +In this example, we create a new `AuthUserFile` with the `-c` option. The file is located at `/var/www/example.com/.htpasswd` and the user name is `username`. `htpasswd` will prompt you to enter a password and then confirm the password. If you have an existing file, omit the `-c` option. + +The `-b` option allows you to enter the password as the last parameter of the command, as in this example: + +```command +htpasswd -b /srv/auth/.htpasswd username 5t1ck6 +``` + +When populated, the `AuthUserFile` looks something like this: + +```file {title="/var/www/example.com/.htpasswd"} +hobby:isiA3Q4djD/.Q +admin:{SHA}x9VvwHI6dmgk9VTE0A8o6hbCw2s= +username:\$apr1\$vVzQJxvX\$6EyHww61nnZr6IdQv0pVx/ +``` + +Each user is specified on their own line. Each line follows the form `[username]:[hash]`, where the `[hash]` is a cryptographic hash of the user's password. This stores passwords as one-way hashes rather than plaintext values. + +The `htpasswd` utility supports multiple hashing formats, including APR1-MD5, SHA-1, and Bcrypt depending on the Apache version and platform. + +In the above example, the first `hobby` user's password is hashed using the "CRYPT" method, which is the default. This is not considered a secure hashing method. If you specify the `-s` option in the `htpasswd` command, the password will be hashed with the SHA-1 algorithm as in the second line of the above example. The `-m` option uses the APR1-MD5 hashing format, which remains common in Apache environments but is considered legacy compared to newer hashing methods. + +Additionally, if you would prefer to organize and maintain the `AuthUserFile` yourself, you can still use the `htpasswd` tool to generate the user entries. By specifying the `-n` option the program will output the appropriate line in the terminal. In the following example, the `htpasswd` entry is followed by the output of the command: + +```command +htpasswd -nbs user2 strongpassword +user2:{SHA}KuhoB50pPgoYXGcce82sUd8244U= +``` + +You can now append the `user2:{SHA}KuhoB50pPgoYXGcce82sUd8244U=` line to your `AuthUserFile` manually. After adding this line to the password file, the `user2` credentials can authenticate with the HTTP server. + +## Access control lists with groups + +In the `Require` directive above we specified the `valid-user`. This told Apache that any user who could authenticate against one of the users specified in the `AuthUserFile` could gain access to the site. While you can maintain separate password files for different resources, this is difficult to maintain for deployments with complex authentication needs. + +To address this need, Apache allows you to use a single `AuthUserFile`, containing all users that will need to authenticate to the server. To limit the set of valid credentials to a specific subset of the users listed in the `.htpasswd` file, we must specify users in the `Require` directive. Only users specified in the `Require user` directive are permitted to access the resource. + +```file {title="Apache configuration file"} +Require user username admin +``` + +With this directive, the users `username` and `admin` will be able to log into the resource. Any subset of users can be specified on the `Require` line. Apache also provides the ability to organize users into groups, and then permit access to resources based on group membership. The configuration directives for this setup would look like this: + +```file {title="Apache configuration file"} +AuthType Basic +AuthUserFile /srv/auth/.htpasswd +AuthGroupFile /srv/auth/.htgroup +Require group Authorized +``` + +In this example, we cite the same `AuthUserFile`, but we add an `AuthGroupFile` that specifies user groups. The group file contains a list of user groups and the usernames associated with each group. The `htgroup` file, like the `htpasswd` file, can be located anywhere on the file system. For simplicity, we recommend that `htgroup` be in the same directory as the `htpasswd` file. Here is an example of an `htgroup` file: + +```file {title="/var/www/example.com/.htgroup"} +Authorized: username username2 +Team: admin hobby +``` + +With this `htgroup` file, only the users `username` and `username2` can access the listed resource. The syntax of the group file follows a simple `[groupname]: [username 1] [username 2] [...]`. You can put as many usernames from your `AuthUserFile` into a group entry as you need for the particular resource. + +## Caveats of HTTP Basic authentication + +- The `AuthType Basic` directive sends credentials encoded but not encrypted. Always use HTTPS when protecting resources with HTTP authentication. +- With HTTP Basic authentication, credentials must be exchanged between the client and server for every request. While most client software can cache this information so that the user only has to enter the username and password once, the authentication credentials must still be passed with each request. This can add additional network overhead. +- When Apache processes an HTTP Basic authentication request it must parse through the entire `htpasswd` file. When the file only stores a few passwords the processing time is negligible, but when password files grow, requests can take longer to process. \ No newline at end of file