Basic auth in cURL: a complete guide

Introducing cURL

cURL (or curl) is a command-line tool that lets you transfer data over various protocols, including HTTP. When accessing protected resources, such as a web page behind a login, you often need to send your credentials.

The scope and purpose of this guide

This guide aims to provide you with comprehensive knowledge and practical skills for using cURL for basic authentication. We'll cover the syntax for sending credentials, explore secure best practices, and troubleshoot common issues so you can securely access protected resources.

A brief introduction to data transfer with cURL

At its core, cURL excels at executing HTTP requests - the lifeblood of web communication. It demonstrates remarkable proficiency in effortlessly handling a wide array of request types, ranging from the commonly used GET requests to the more advanced and versatile POST and PUT requests. Doing this ensures seamless and comprehensive web communication capabilities.

Basic authentication and authorization in cURL

Basic authentication is a simple HTTP authentication mechanism where the client transmits a username and password in plain text, encoded with Base64, in the Authorization header. While not the most secure method, it's still widely used for basic access control.

To use basic auth, include the --user username:password option in your curl command. cURL will encode these credentials in Base64 and append an Authorization header to the HTTP request. This header helps the server identify the username and password for verification. Further practical examples illustrating this process will be provided later in this guide.

The limitations of basic authentication & authorization headers

Basic auth has several notable limitations.

• Security: Credentials are sent in the request reader, making them susceptible to interception.
• Caching: Browsers often cache credentials, potentially exposing them to unauthorized access.
• Replay attacks: Credentials intercepted by hackers can be reused.
• Limited granularity: Basic auth grants or denies access to entire resources, not specific actions.

Sending basic auth credentials with cURL

While basic authentication remains a common method for cURL commands, it's important to understand that a variety of options for sending basic auth credentials, especially with its inherent security limitations. Let's explore three approaches:

1. Using the --user or -u flag

This is the classic cURL method for basic auth. Simply append --user username:password (replacing "username" and "password" with your actual user credentials) to your cURL command. cURL automatically Base64 encodes this information and adds an Authorization header to the request. However, remember that credentials are included in plain text unless using HTTPS, making them vulnerable to interception - as stated in the previous section.

curl --user username:password [<https://example-protected-resource.com>](<https://example-protected-resource.com/>)

💡 Using the -u shortcut

In addition to --user, cURL provides the -u shortcut, which serves the same purpose for specifying the username and password for basic authentication. The syntax for using the -u shortcut is as follows:

curl -u username:password [<https://example-protected-resource.com>](<https://example-protected-resource.com/>)

2. Using environment variables

For improved security and convenience, consider storing your credentials in environment variables. Define them outside your cURL command like this:

• For Linux/MacOS

export USERNAME="your_username"
export PASSWORD="your_password"

• For Windows

setx /M USERNAME "your_username"
setx /M PASSWORD "your_password"

Then, within your cURL command, replace username and password in the -u flag with $USERNAME and $PASSWORD. This keeps your credentials hidden in the command itself.

curl -u $USERNAME:$PASSWORD <https://example.com/protected-resource>

3. Beyond basic auth: Using OAuth and token-based methods

For stronger security and flexibility, consider moving beyond basic auth. OAuth, for example, uses tokens for authentication to eliminate the need to transmit actual credentials. Protocols like OAuth2 can be integrated with cURL to handle token negotiation seamlessly. Similarly, many APIs implement token-based authentication where you specify a pre-generated token in the request headers instead of username and password. Here's an example of a token-based auth:

curl <https://example.com/protected-resource> \\
-H "Authorization: Basic $(echo -n "username:password" | base64)"
-H "X-API-Token: your_api_token"

💡 the -H option

Using the -H option, you can include custom headers in your curl requests, giving you precise control over the request headers.

OAuth uses a multi-step "token dance" where your application and the user collaborate to obtain access tokens. This eliminates the need for transmitting raw credentials. This negotiation makes it ideal for sensitive data or production environments. Exploring OAuth and token-based methods unlocks flexibility and safeguards valuable data.

Here's a simplified example using OAuth2:

curl <https://example.com/protected-resource> \\
-H "Authorization: Bearer $(oauth2_access_token)"

Handling server response codes

When using cURL for requests with basic authentication, it's advisable to handle response codes properly. A successful request will return a status code of 200, indicating that the request was processed successfully and the server responded with the expected data. If the credentials are invalid or authentication fails, you might receive a status code of 401 (Unauthorized) or a different error code.

To capture and handle response codes in cURL requests, use the -w option to specify a format string for output. This allows you to extract and process the status code from the HTTP response.

Here's an example of using the -w option to capture the response code while sending a cURL request with basic authentication:

response_code=$(curl -s -o /dev/null -w "%{http_code}" --user username:p@s5w0rd <https://example.com/protected-resource>)
if [ $response_code -eq 200 ]; then
    echo "Request was successful"
else
    echo "Request failed with status code $response_code"
fi

In this example, the -s flag is used to silence progress meters and informational messages. The -o /dev/null flag is used to prevent the response body from being saved, while the -w option captures the status code into the response_code variable. You can then use this variable to conditionally handle different response codes.

Using cURL with authorization headers

You can manually construct the Authorization header and include it in your cURL requests. This method provides greater flexibility, allowing you to customize the header as needed. For example, you can specify additional parameters in the header to provide more detailed authentication information.

By constructing the header manually, you can include other custom headers in your requests, such as User-Agent or Content-Type. This gives you more control over the request and allows you to tailor it to your specific requirements. It will also let you switch easily between different authentication methods, such as Basic Auth or OAuth, depending on your needs.

Example: Sending basic authentication credentials with authorization headers

You can manually set the Authorization header in a cURL request, as shown in the following example:

curl -H "Authorization: Basic $(echo -n 'username:p@s5w0rd' | base64)" <https://example.com/protected-resource>

In this example, the $(echo -n 'username:p@s5w0rd' | base64) command is used to encode the username and password in base64 format, as required by the Authorization header for basic authentication.

Let's sum up what you've learned about cURL

In this guide, you've learned how to use cURL to send credentials using basic authentication. Whether you're accessing web resources, testing APIs, or integrating with web services, cURL provides a straightforward and efficient way to handle basic authentication with username and password. By using the --user option, the -u shortcut and custom headers, you have the flexibility to incorporate basic authentication into your cURL requests with ease.