Digest Authentication using Flatfile based storage

Here Apache HTTP Server makes use of Digest Authentication using flatfile storage for authentication files. Make sure to read Setting up Authentication and Authorization before proceeding.

Digest Authentication using Flatfile based storage involves the following steps.
1) Configuring Apache HTTP Server
2) Managing Apache Users
3) Managing Apache Groups
4) Examples

 

 

1) Configuring Apache HTTP Server
Open Apache HTTP Server‘s main configuration file httpd.conf.

Digest authentication requires the module mod_auth_digest.somod_auth_digest.so is compiled by default on an Apache HTTP Server installation unless we explicitly disable them using the configure option --enable-mods-shared=few or --disable-auth-digest. We need to enable it manually.
Look for the line containing mod_auth_digest.so. Uncomment the line so it looks as shown below.

LoadModule auth_digest_module modules/mod_auth_digest.so

Save and close the file.

Restart the apache service gracefully.

# service apache graceful

 

 

2) Managing Apache Users
Apache HTTP Server provides the htdigest utility for creating and managing authentication files that use Digest HTTP authentication.

Before proceeding further we must understand the usage of Realm in Digest Authentication. Realm is a concept in Digest Authentication defined by RFC2617.

Technically,
Realm value is a string, assigned by the origin server. It is required for the challenge issued by digest authentication scheme. It allows the protected resources on a server to be partitioned into a set of protection spaces, each with its own authentication schemes and/or authorization databases.
The realm value is also a part of the digested data stored in the password file. So if one Digest Authentication password file is compromised, it does not compromise other password files with same username and password.

For end users,
The realm value is a string to be displayed to users, so they know which username and password to use. An example might be [email protected].
For those thinking what is difference between Realms & Groups
Consider a company with two buildings. Each building can be considered as a realm. Let there be a specific worker who is friends with few other workers, whom together form a group. This group has access to first building, which means this group has access to the first realm. Again let this specific worker be allowed access to the second building, which means this worker has access to the second realm. Also, Realms in addition to Groups provide separate protection spaces and authentication schemes.

When defining a Realm value, the following points should be kept in mind.
• Realm string should be the same value used for AuthName directive.
• Realm string should be unique among all realms which any single user is likely to use.
• Realm string should contain at least the name of the host performing the authentication and might have additional semantics for end user to identify the realm.
• Realm string is case-insensitive.


Let us create an authentication file .htdigest in /usr/local/apache2/, with Apache user auser1 in realm [email protected]. Execute the below command in terminal. We will be asked to type a new password for the user. Type it and press Enter.

# htdigest -c /usr/local/apache2/.htdigest [email protected] auser1

NOTE: If there is an existing password file, the option -c will only work if the password file was created by or follows the exact format as expected by htdigest utility. Otherwise the new authentication details will be appended resulting in a corrupt authentication file.

OPTIONS EXPLAINED

-c
Create the passwdfile. If passwdfile already exists, it is deleted first.

passwdfile
Name of the file to contain the username, realm and password. If -c is given, this file is created if it does not already exist, or deleted and recreated if it does exist.

realm
The realm name to which the user name belongs. See http://tools.ietf.org/html/rfc2617#section-3.2.1 for more details.

username
The user name to create or update in passwdfile. If username does not exist is this file, an entry is added. If it does exist, the password is changed.


Let us also add three other Apache users auser2, auser3 and auser4 in realm [email protected] to the authentication file .htdigest.

# htdigest /usr/local/apache2/.htdigest [email protected] auser2
# htdigest /usr/local/apache2/.htdigest [email protected] auser3
# htdigest /usr/local/apache2/.htdigest [email protected] auser4
OPTIONS EXPLAINED

passwdfile
Name of the file to contain the username, realm and password. If -c is given, this file is created if it does not already exist, or deleted and recreated if it does exist.

realm
The realm name to which the user name belongs. See http://tools.ietf.org/html/rfc2617#section-3.2.1 for more details.

username
The user name to create or update in passwdfile. If username does not exist is this file, an entry is added. If it does exist, the password is changed.


The authentication file .htdigest is currently owned by root and is world readable. Let us set proper permissions for this file. Change the user and group ownership of .htdigest file to apache.

# chown apache:apache /usr/local/apache2/.htdigest


Remove read permissions of others for the .htdigest file.

# chmod o-r /usr/local/apache2/.htdigest
OPTIONS EXPLAINED

o-r
Unset read permission for other users who are not members of the file's group


Deleting a user

If we want to delete a user from the .htdigest file, we will have to do that manually by opening the file in a text editor and removing the corresponding entry.

 

 

3) Managing Apache Groups
We have four Apache users auser1, auser2, auser3 and auser4. Let us create a group agroup12 consisting of users auser1 and auser2, and another group agroup34 consisting of users auser3 and auser4.
Create a new file named .htgroups in /usr/local/apache2/ directory with the below content.

agroup12: auser1 auser2
agroup34: auser3 auser4


The group file .htgroups is currently owned by root and is world readable. Let us set proper permissions for this file. Change the user and group ownership of .htgroups file to apache.

# chown apache:apache apache /usr/local/apache2/.htgroups


Remove read permissions of others for the .htgroups file.

# chmod o-r /usr/local/apache2/.htgroups
OPTIONS EXPLAINED

o-r
Unset read permission for other users who are not members of the file's group


Deleting a group

If we want to delete a group from the .htgroups file, we will have to do that manually by opening the file in a text editor and removing the corresponding entry.

 

 

4) Examples
The sample configurations provided in the below examples should be placed inside the <Directory> or <Location> block of Apache HTTP Server‘s configuration files or inside .htaccess files
Make sure to read Setting up Authentication and Authorization before proceeding.

TIP: Read about htaccess directives.
WARNING: The authentication files should never be accessible to the outside world. If possible they should not be placed within the webserver's URI space. Even if they are placed, Access Control must be implemented denying any access to them.

Apache HTTP Server's main configuration file httpd.conf contains the following lines, that denies access to any files having a filename starting with .ht.
    <Files ".ht*">
         Require all denied
    </Files>
Follow the naming of your authentication files according to this configuration.



EXAMPLE 1: To password protect a directory, with access to only selected users in a specific realm, add the below content to configuration file.

AuthName		"[email protected]"
AuthType		Digest
AuthDigestDomain 	/
AuthUserFile		/usr/local/apache2/.htdigest
Require			user auser1 auser2

This will present the user with a Username & Password prompt when they try to access the specified directory. Only users auser1 and auser2 in the realm [email protected] are authorized to access.


EXAMPLE 2: To password protect a directory, with access to all users in a specific realm, add the below content to configuration file.

AuthName		"[email protected]"
AuthType		Digest
AuthDigestDomain 	/
AuthUserFile		/usr/local/apache2/.htdigest
Require			valid-user

This will present the user with a Username & Password prompt when they try to access the specified directory. All users in the realm [email protected] are authorized to access.


EXAMPLE 3: To password protect a directory, with access to only selected groups in a specific realm, add the below content to configuration file.

AuthName		"[email protected]"
AuthType		Digest
AuthDigestDomain 	/
AuthUserFile		/usr/local/apache2/.htdigest
AuthGroupFile		/usr/local/apache2/.htgroup
Require			group agroup12

This will present the user with a Username & Password prompt when they try to access the specified directory. Only users in the group agroup12 and realm [email protected] are authorized to access.


EXAMPLE 4: To password protect a file, with access to all users in a specific realm, add the below content to configuration file.

AuthName		"[email protected]"
AuthType		Digest
AuthDigestDomain 	/
AuthUserFile		/usr/local/apache2/.htdigest
<Files "file1.jpg">
  Require valid-user
</Files>

This will present the user with a Username & Password prompt when they try to access the specified file file1.jpg. All users in the realm [email protected] are authorized to access.


EXAMPLE 5: To password protect multiple files, with access to all users in a specific realm, add the below content to configuration file.

AuthName		"[email protected]"
AuthType		Digest
AuthDigestDomain 	/
AuthUserFile		/usr/local/apache2/.htdigest
<FilesMatch "(file1.jpg)|(file2.zip)|(file3)">
  Require valid-user
</FilesMatch>

This will present the user with a Username & Password prompt when they try to access the specified files file1.jpg, file2.zip, file3. All users in the realm [email protected] are authorized to access.


EXAMPLE 6: To password protect a filetype, with access to all users in a specific realm, add the below content to configuration file.

AuthName		"[email protected]"
AuthType		Digest
AuthDigestDomain 	/
AuthUserFile		/usr/local/apache2/.htdigest
<FilesMatch ".jpg">
  Require valid-user
</FilesMatch>

This will present the user with a Username & Password prompt when they try to access the files with extension .jpg. All users in the realm [email protected] are authorized to access.


EXAMPLE 7: To password protect multiple filetypes, with access to all users in a specific realm, add the below content to configuration file.

AuthName		"[email protected]"
AuthType		Digest
AuthDigestDomain 	/
AuthUserFile		/usr/local/apache2/.htdigest
<FilesMatch ".(jpg|pdf|zip|rar)$">
  Require valid-user
</FilesMatch>

This will present the user with a Username & Password prompt when they try to access the files with extensions .jpg, .pdf, .zip, .rar. All users in the realm [email protected] are authorized to access.


EXAMPLE 8: To password protect multiple files/filetypes, with access to all users in a specific realm, add the below content to configuration file.

AuthName		"[email protected]"
AuthType		Digest
AuthDigestDomain 	/
AuthUserFile		/usr/local/apache2/.htdigest
<FilesMatch "file*">
  Require valid-user
</FilesMatch>

This will present the user with a Username & Password prompt when they try to access all files whose filename starts with file. All users in the realm [email protected] are authorized to access.
OR

AuthName		"[email protected]"
AuthType		Digest
AuthDigestDomain 	/
AuthUserFile		/usr/local/apache2/.htdigest
<FilesMatch "(file[1-2].jpg)|(file3)">
  Require valid-user
</FilesMatch>

This will present the user with a Username & Password prompt when they try to access the files file1.jpg, file2.jpg and file3. All users in the realm [email protected] are authorized to access.


EXAMPLE 9: To password protect everything in a directory, except a single file, with access to all users in a specific realm, add the below content to configuration file.

AuthName		"[email protected]"
AuthType		Digest
AuthDigestDomain 	/
AuthUserFile		/usr/local/apache2/.htdigest
Require			valid-user
<Files "file1.jpg">
  Require all granted
</Files>

This will present the user with a Username & Password prompt when they try to access anything in the directory except the file file1.jpg. All users in the realm [email protected] are authorized to access.


EXAMPLE 10: To password protect everything in a directory, except multiple files, with access to all users in a specific realm, add the below content to configuration file.

AuthName		"[email protected]"
AuthType		Digest
AuthDigestDomain 	/
AuthUserFile		/usr/local/apache2/.htdigest
Require			valid-user
<FilesMatch "(file1.jpg)|(file2.zip)|(file3)">
  Require all granted
</FilesMatch>

This will present the user with a Username & Password prompt when they try to access anything in the directory except the files file1.jpg, file2.zip, file3. All users in the realm [email protected] are authorized to access.


EXAMPLE 11: To password protect everything in a directory, except a specific filetype, with access to all users in a specific realm, add the below content to configuration file.

AuthName		"[email protected]"
AuthType		Digest
AuthDigestDomain 	/
AuthUserFile		/usr/local/apache2/.htdigest
Require			valid-user
<FilesMatch ".jpg">
  Require all granted
</FilesMatch>

This will present the user with a Username & Password prompt when they try to access anything in the directory except the files with extension .jpg. All users in the realm [email protected] are authorized to access.


EXAMPLE 12: To password protect everything in a directory, except multiple filetypes, with access to all users in a specific realm, add the below content to configuration file.

AuthName		"[email protected]"
AuthType		Digest
AuthDigestDomain 	/
AuthUserFile		/usr/local/apache2/.htdigest
Require			valid-user
<FilesMatch ".(jpg|pdf|zip|rar)$">
  Require all granted
</FilesMatch>

This will present the user with a Username & Password prompt when they try to access anything in the directory except the files with extensions .jpg, .pdf, .zip and .rar. All users in the realm [email protected] are authorized to access.


EXAMPLE 13: To password protect everything in a directory, except multiple files/filetypes, with access to all users in a specific realm, add the below content to configuration file.

AuthName		"[email protected]"
AuthType		Digest
AuthDigestDomain 	/
AuthUserFile		/usr/local/apache2/.htdigest
Require			valid-user
<FilesMatch "file*">
  Require all granted
</FilesMatch>

This will present the user with a Username & Password prompt when they try to access anything in the directory except the files whose filename starts with file. All users in the realm [email protected] are authorized to access.
OR

AuthName		"[email protected]"
AuthType		Digest
AuthDigestDomain 	/
AuthUserFile		/usr/local/apache2/.htdigest
Require			valid-user
<FilesMatch "(file[1-2].jpg)|(file3)">
  Require all granted
</FilesMatch>

This will present the user with a Username & Password prompt when they try to access anything in the directory except the files file1.jpg, file2.jpg and file3. All users in the realm [email protected] are authorized to access.


EXAMPLE 14: If we want to disable password protection for a specific directory, add the below content to configuration file.

Require all granted

This will not present the user with the Username & Password prompt when they try to access that directory.

 

 

 

It is recommended to view the following sections.
Basic Authentication using Flatfile based storage
Basic Authentication using DBM based storage
Digest Authentication using DBM based storage

OR

You may go back to the following section.
Securing Apache HTTP Server