Introduction
HTTP authentication is the process of identifying and verifying users' credentials to make sure they are permitted to access a web resource. To prevent unauthorized access to your PHP web application, you can protect sensitive files or endpoints using a username and a password. One common way of achieving this is by using basic HTTP authentication. In this security design pattern, every user making a request to a resource on your server must submit an Authorization
header containing Base64 encoded credentials.
The Base64 algorithm used in this context is for encoding non-HTTP compatible characters submitted by users to accepted values, and you should not use it as an encryption alternative. You would force your users to pass their credentials via secure HTTPS in a production environment.
In this guide, you'll create a password-protected PHP web resource on Ubuntu 20.04 server. This endpoint will return data for the available products in a JSON (JavaScript Object Notation) format when the user is authenticated. However, users submitting empty or invalid credentials will get an error.
Prerequisites
To follow along with this tutorial, make sure you have the following:
- An Rcs Ubuntu 20.04 server.
- A sudo user.
- A LAMP Stack. You can also follow this tutorial on a Rcs One-Click LAMP server.
Edit the Apache Configuration File
SSH to your server and start by editing the Apache configuration file. For HTTP authentication to work, Apache should allow the .htaccess
file to override main settings.
Open the /etc/apache2/apache2.conf
file.
$ sudo nano /etc/apache2/apache2.conf
Find the content below.
<Directory /var/www/>
Options Indexes FollowSymLinks
AllowOverride None
Require all granted
</Directory>
Change the AllowOverride None
directive to AllowOverride All
as shown below.
<Directory /var/www/>
Options Indexes FollowSymLinks
AllowOverride All
Require all granted
</Directory>
Save and close the file.
Enable Apache mod_rewrite
Module
Enable Apache mod_rewrite
module. This is a rule-based engine that rewrites incoming requests to the server. You'll require this module to retrieve the values of the HTTP_AUTHORIZATION
header in your PHP files.
$ sudo a2enmod rewrite
Restart the Apache web server to refresh the settings that you've changed.
$ sudo systemctl restart apache2
Create a Password Protected PHP File
The next step is creating a PHP web resource that displays data in JSON format for authenticated users. Open a new /var/www/html/sample.php
file at the root directory of your web server.
$ sudo nano /var/www/html/sample.php
Enter the information below into the file. Remember to replace EXAMPLE_PASSWORD
with a strong value.
<?php
header('Content-Type: application/json');
list($username, $password) = explode(':', base64_decode(substr($_SERVER['HTTP_AUTHORIZATION'], 6)));
if ($username != 'john' || $password != 'EXAMPLE_PASSWORD') {
header("HTTP/1.1 401 Unauthorized");
$error = [
'title' => 'Authentication failed',
'message' => 'Invalid username or password',
'error_code' => '401',
];
echo json_encode($error , JSON_PRETTY_PRINT);
} else {
$products = [];
$products[] = [
'product_id' => 1,
'product_name' => 'WIRELESS KEYBOARD',
'retail_price' => '44.80',
];
$products[] = [
'product_id' => 2,
'product_name' => 'LAPTOP BAG',
'retail_price' => '28.70',
];
$products[] = [
'product_id' => 3,
'product_name' => 'MOUSE PAD',
'retail_price' => '5.67',
];
echo json_encode($products, JSON_PRETTY_PRINT);
}
Save and close the file.
The PHP code explained:
header('Content-Type: application/json');
The above line sends a header to a browser to format the data in the expected JSON format.
list($username, $password) = explode(':', base64_decode(substr($_SERVER['HTTP_AUTHORIZATION'], 6)));
The code snippet above decodes the Base64 encoded credentials submitted by users to two variables($username
and $password
).
...
if ($username != 'john' || $password != 'EXAMPLE_PASSWORD') {
header("HTTP/1.1 401 Unauthorized");
$error = [
'title' => 'Authentication failed',
'message' => 'Invalid username or password',
'error_code' => '401',
];
echo json_encode($error , JSON_PRETTY_PRINT);
} else {
...
}
...
In the above code, you've used the PHP logical if (...) {...} else {...}
statement to check if the user is submitting the required username and password combination. In this case, the correct user will be authenticated by the username john
and EXAMPLE_PASSWORD
as the password. In case those values don't match, you're throwing a JSON encoded error and a 401
header informing the user that authentication has failed.
...
if ($username != 'john' && $password != 'EXAMPLE_PASSWORD') {
...
} else {
$products = [];
$products[] = [
'product_id' => 1,
'product_name' => 'WIRELESS KEYBOARD',
'retail_price' => '44.80',
];
...
echo json_encode($products, JSON_PRETTY_PRINT);
...
}
In the code above, you're creating an array of products and displaying them as a JSON encoded string for the authenticated users.
Modify the .htaccess
File
Modify the .htaccess
file for the HTTP authentication to work. Open the /var/www/html/.htaccess
file.
$ sudo nano /var/www/html/.htaccess
Add the line below into the file.
SetEnvIf Authorization "(.*)" HTTP_AUTHORIZATION=$1
Save and close the file. The rewrite rule above instructs Apache to copy the value of $_ENV['HTTP_AUTHORIZATION']
into the $_SERVER['HTTP_AUTHORIZATION']
variable. Remember, you are retrieving this value in the /var/www/html/sample.php
file to get encoded users' credentials.
Test HTTP Authentication
After you've modified the Apache settings, created a password-protected resource, and modified the .htaccess
file, the next step is testing if everything is working as expected.
Use Linux curl
command to request the resource as shown below. In the first attempt, don't submit any credentials to check if you'll get an error. The -i
option instructs curl
to include the HTTP response headers when displaying the output.
$ curl -i -H 'Accept:application/json' localhost/sample.php
You should get an output similar to the one shown below confirming that you're not authenticated.
HTTP/1.1 401 Unauthorized
Date: Tue, 26 Jan 2021 09:27:19 GMT
Server: Apache/2.4.41 (Ubuntu)
Content-Length: 121
Content-Type: application/json
{
"title": "Unauthorized",
"message": "You are not authorized to access this resource",
"error_code": "401"
}
Try to access the resource with the correct credentials. The -u
option converts the username
and password
to a Base64 encoded string under the hood when submitting the request to the server.
$ curl -u john:EXAMPLE_PASSWORD -i -H 'Accept:application/json' localhost/sample.php
With the correct credentials, you should now get a list of products, as shown below.
HTTP/1.1 200 OK
Date: Tue, 26 Jan 2021 09:30:50 GMT
Server: Apache/2.4.41 (Ubuntu)
Content-Length: 331
Content-Type: application/json
[
{
"product_id": 1,
"product_name": "WIRELESS KEYBOARD",
"retail_price": "44.80"
},
{
"product_id": 2,
"product_name": "LAPTOP BAG",
"retail_price": "28.70"
},
{
"product_id": 3,
"product_name": "MOUSE PAD",
"retail_price": "5.67"
}
]
Repeat the same process with some incorrect credentials and see if you get an error.
$ curl -u john:WRONG_PASSWORD -i -H 'Accept:application/json' localhost/sample.php
$ curl -u wrong_username:EXAMPLE_PASSWORD -i -H 'Accept:application/json' localhost/sample.php
You should get an error in both cases.
HTTP/1.1 401 Unauthorized
Date: Tue, 26 Jan 2021 09:27:19 GMT
Server: Apache/2.4.41 (Ubuntu)
Content-Length: 121
Content-Type: application/json
{
"title": "Unauthorized",
"message": "You are not authorized to access this resource",
"error_code": "401"
}
Conclusion
In this tutorial, you've secured a PHP web resource with HTTP Authentication on Ubuntu 20.04 server. To take your web server security even a step further, consider securing Apache with TLS/SSL Certificate.