Curl Basic Auth - How Does It Work?

Introduction

Servers using HTTP authentication send a 401 unauthorized response if a client tries to access a protected resource. The response includes one or more WWW-Authenticate headers that indicate what authentication methods the server accepts for that resource. 

Basic Authentication (Basic Auth) is not entirely secure, but it is a fast and convenient way to implement access control for noncritical web resources.  

Find out how to use the curl command-line utility to streamline Basic Auth requests. 

What Is Basic Authentication? 

Basic Authentication is an HTTP authentication method where the server declares that the client must submit a username and password to access a resource. The server validates the provided credentials against a database of authorized users and serves the resources. 

Basic Auth includes the following steps: 

1. A web client, for example, a browser, requests access to a protected resource.
2. The web server returns a challenge, typically a dialog box that asks the web client to provide valid credentials. 
3. The client submits the username and password. 
4. The server authenticates the user and returns the requested resource. 

The client sends authentication credentials in the Authorization header field. The header field is structured as follows:  

• The username and password are paired using a single colon (:). The username can contain any special character except for a colon. 
• The username:password pair is encoded using Base64 encoding. 
• The authorization method (Basic) and white space are inserted before the encoded string. 

For example, the username Mjolnir and password Valhalla are joined using a colon: 

Mjolnir:Valhalla

The value is encoded using the Base64 scheme, which results in the following string:  

TWpvbG5pcjpWYWxoYWxsYTRldmVy  

The complete Authorization header field appears as: 

Authorization: Basic TWpvbG5pcjpWYWxoYWxsYTRldmVy

Basic Auth is ideal for preventing unintentional access from non-malicious parties, but it is not a comprehensive authentication method. It does not authenticate target servers, while the Base64 encoded text can easily be intercepted and decoded. This makes Basic Auth especially vulnerable to man-in-the-middle and replay attacks. 

Basic Auth can be strengthened with encryption technology, like SSL certificates. However, that does not mean that Basic Auth is suitable for protecting critical resources. 

Note: Bearer-token authentication is considered a much safer authentication method, especially if working with an API and delicate information. 

How to Use curl Basic Auth 

The curl command line tool is used to transfer data to and from a server for resources specified as URLs, such as API endpoints. Both curl and the libcurl transfer library are part of the Open Source cURL (client URL) project for facilitating data transfers using various network protocols. 

The most common use cases for curl are endpoint testing, retrieving resources, logging errors, and debugging. 

Users can communicate with web and application servers by sending requests directly from the terminal or incorporating curl requests in an automated script. 

Basic curl syntax is straightforward: 

curl [options/URLs]

Curl has built-in support for basic HTTP authentication. 

Send Credentials with -u Argument 

Use the -u option to send Basic Auth username:password pairs: 

curl -u username:password [URL]

The username in this example is Mjolnir, and the password Valhalla: 

curl -u Mjolnir:Valhalla https://someurl.com/protectedresource 

Curl automatically encodes the provided Mjolnir:Valhalla pair using Base64 encryption and adds the Authorization: Basic [token] HTTP header to the request: 

Authorization: BasicTWpvbG5pcjpWYWxoYWxsYTRldmVy

Note: If your username or password contains a special character (i.e., @,#, white space), place the credentials in single quotes. 

Test Authentication Header 

You can use curl to test if a server requires HTTP authentication with the --anyauth option. Curl automatically tries to make an unauthenticated request and then attempts the safest available method if needed:  

curl --anyauth -u Mjolnir:Valhalla https://someurl.com/protectedresource 

Pass Authorization Header 

The curl -H 'Authorization: Basic [token] ' option also allows users to pass Basic Auth credentials. Clients can encode the username:password pair in advance and place it into the Authorization header: 

curl -H 'Authorization: Basic TWpvbG5pcjpWYWxoYWxsYTRldmVy' https://someurl.com/protectedresource 

The -H option passes the authorization header to curl as a custom header. 

Make curl Prompt for the Password 

To make curl prompt for a password, use the -u option and only pass the username: 

curl -u 'username' [URL] 

This request will succeed if the server allows users to access resources without a password. Otherwise, it will fail, and the user is going to be prompted to enter their password. 

Conclusion

You know how basic authentication works and how to use curl to send authorization headers for different use cases. 

Web resources that deliver sensitive information should not use Basic Auth as an authentication method. Payment APIs and other web services that deal with sensitive and personally identifiable information use bearer tokens and OAuth authentication to secure data transfers.