Basic Access Authentication is an HTTP authentication scheme, which consists in a client providing a username and a password when making a request to a server, to prove who they claim to be in order to access protected resources. Note that performing Basic Access Authentication with cURL differs from the idea of authorization in the sense that the latter is performed by the server in order to determine users' access rights - i.e. authorization is what happens after authentication.
Using curl -u/--user to send credentials
The short answer To perform Basic Access Authentication with cURL, you can use the -u option flag (short for --user) as follows: Where the username and the password are separated by a colon character (:).
Alternatively, if you only specify the username, cURL will prompt you for a password. cURL will encode the username:password string using the Base64URL encoding scheme and include this value in the Basic authorization header of the HTTP request. For example, the johndoe:password string will be converted by cURL into the following HTTP header:
The -u/--user approach is the most common way to pass credentials with curl. This method results in an Authorization header like: Basic base64(username:password).
Escaping and shell considerations
Escaping special characters in curl (such as your password) When using cURL for authentication, you may need to escape certain characters in your username or password. To escape special characters, you can either use a backslash character (\). Or you can wrap your string in single quotes, which will cause all special characters to lose their meaning and prevent the shell from performing expansions.
Here are some characters that should be escaped: Colon (:), Ampersand (&), Percent (%), Space. The colon separates the username and the password; note that this character shouldn't exist in your username, and should be escaped if it exists in your password. The ampersand is used by the shell to send a process to the background. The percent sign is used to encode special characters in URLs. The space character is used by the shell to separate command-line arguments and options.
You NEED to know how to use CURL!
Always use HTTPS for credentials
Use HTTPS (not HTTP) with your curl requests Generally speaking, it is never a good idea to pass your credentials in clear text over the network using an unsecured protocol such as HTTP. When available, you should always use the HTTPS endpoint of the service you are trying to authenticate to, by specifying the https scheme in the target URL as follow: This will add a strong layer of encryption on top of HTTP that guarantees that your credentials are safe even if they were to fall into the wrong hands.
Security and storage of credentials
Secure your curl credentials in a .netrc file In general, performing an authentication by typing your credentials in clear text in the command-line constitutes a significant security risk. The reason for that lies in the fact that, just like your browser saves the searches you perform, the shell keeps an internal history list of all the commands you run. These commands are temporarily stored in the RAM until you log out of your current shell session, which will cause the history list to be physically written to the disk in a file located in your home directory.
What is Curl? Curl (Client URL) is a command-line tool that can transfer data to/from a server using a number of network protocols, including HTTP, HTTPS, SCP, SFTP, FTP, and works on almost any platform, including Linux, Windows, and macOS. Curl is used for API testing, has built-in support for proxies, SSL, HTTP Cookies, certificate validation, user authentication.
What is Basic Authentication?
What is Basic Authentication? Basic Authentication is an authentication method built into the HTTP protocol. Basic Authentication is based on base64 encoded text and sends the username and password obfuscated but utterly readable by anyone listening on the network between you and the remote server. For security reasons, Basic Authentication should only be used in conjunction with other security mechanisms such as HTTPS and SSL.
Credentials used in authentication are digital documents that associate a user's identity with some form of proof of identities, such as a certificate or password.
How to make a Curl request with Credentials
To tell Curl to send a request with HTTP authentication, you need to pass the credentials using the -u/-user command-line option and separate the username and password with a colon. The command automatically encodes these credentials in Base64 and appends an Authorization header to the HTTP request.
Other authentication options with curl
What is Proxy Authentication? Proxy Authentication is a built-in HTTP mechanism that prevents unauthorized use of the proxy server. To Authenticate Proxies with Curl, you need to use the -U/--proxy-user command-line options and provide credentials, separated by colons. Cookie-based authentication: what does it entail? A cookie is a data string sent from a web server to a browser and stored on a user's device. Curl Cookie Based Authentication Syntax curl --cookie "authCookie=my_auth_cookie"
You NEED to know how to use CURL!
Additional approaches and best practices
Beyond basic auth: Using OAuth and token-based methods For stronger security and flexibility, consider moving beyond basic auth. 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. The -H option allows including custom headers in curl requests, giving precise control over the request headers.
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. If the credentials are invalid, you might receive 401 (Unauthorized) or a different error code. Use the -w option to capture the status code for conditional handling.
Manually constructing the Authorization header This method provides greater flexibility, allowing you to customize the header as needed. By constructing the header manually, you can include other custom headers such as User-Agent or Content-Type.
Proper practices for production Always use HTTPS over HTTP. Do not hardcode credentials in scripts or version control. Consider environment variables or secrets managers, and opt for API keys or Bearer tokens when possible. In the realm of web development and API integration, securing communication between clients and servers is paramount.
Practical synthesis: three main approaches to send credentials with curl
- Using the classic --user/-u flag: curl -u username:password http://example.com
- Using environment variables: curl -u "$USERNAME:$PASSWORD" http://example.com
- Using custom headers or tokens (Advanced): curl -H "Authorization: Basic base64(username:password)" http://example.com
In the above script you can see that -u value in quotes is safer when passwords contain spaces or shell-special characters such as $, !, or &. Using an environment variable is safer than putting the password directly in the command, though not a complete secret-management solution.