Call an HTTP API with curl: Authenticating with Basic Auth and Bearer Tokens

Most HTTP APIs require authentication, and two schemes are the most common:

Basic authentication - the client sends a username and a password with every request.
Bearer tokens - the client first obtains a token, often in exchange for a username and password, and then sends the token with every request.

Both approaches rely on the same Authorization request header, and curl knows how to set one from the passed credentials.

In this challenge, you will authenticate to an internal HTTP API from workstation-01 using both schemes, reuse a credential that another tool stored on disk, and learn how to keep a password out of your shell history.

The API is the Artifact Inventory service at http://api.corp.internal:8080, and its private part lives under /api/v1/private:

GET /api/v1/private/whoami - the identity and session of the caller
GET /api/v1/token?scope=<scope> - the issues a short-lived token for the given scope
GET /api/v1/private/deployments - current deployments, available to token holders only

Your credentials for the service are the username ops and the password winter-owl-42.

Task 1: Read the Authentication Challenge

Request the whoami endpoint without any credentials. What status code does the server answer with?

Hint 1

The -i option makes curl print the status line and the headers. Look at the WWW-Authenticate header of this response as well: it names the authentication scheme the server expects and a realm.

Task 2: Send a Username and Password

The above 4xx code means the server wants credentials. Call the whoami endpoint again, this time as ops. The response will include the session the server opens for you. What is the value of its session field?

Hint 2

The -u <user>:<password> option makes curl send the credentials with the Basic scheme. If you omit the password part, curl prompts for it, which keeps the password out of the shell history.

Task 3: Use a Stored Credential

The IT department set up an automation on your workstation that talks to the Artifact Inventory API under its own account. The automation keeps its credential in ~/.config/inventory/credentials.json. Call the whoami endpoint the way the automation does, with the stored credential as it is in the file, and submit the session value from the response.

Hint 3

The -u option is only a shortcut. It encodes username:password with base64 and puts the result into an Authorization: Basic <encoded> request header. The auth value in the file is such an encoded string, so it can go straight into the header, and request headers are set with the -H option.

Important

Base64 is an encoding (not an encryption), so anyone who can read such a file can read the credentials in it.

Task 4: Obtain and Use a Bearer Token

The deployments endpoint accepts only bearer tokens. The token endpoint issues a token to a caller that authenticates with Basic credentials and asks for the scope deployments:read.

Obtain a token, use it to call the deployments endpoint, and submit the value of the releaseKey field of the response.

Hint 4

The flow has two requests:

Call the token endpoint with the ops credentials (the -u option from Task 2) and the scope in the query string: /api/v1/token?scope=deployments:read. The response is a JSON body with the token in its token field.
Call the deployments endpoint with the token in a request header. The header is Authorization: Bearer <token>, and request headers are set with the -H option of curl. The response is a JSON body with the releaseKey field.

The two requests use different Authorization headers: Basic with the credentials in the first one, Bearer with the token in the second one.

Tip

Tokens are long and error-prone to copy by hand. Store the token in a shell variable and use the variable in the next task.

Task 5: Keep the Password Out of the Command Line

A password typed on the command line can leak to the shell history and/or become visible to other processes on the machine while the command runs. The curl command can read credentials from a ~/.netrc file instead.

Create ~/.netrc on workstation-01 with an entry for api.corp.internal holding the ops credentials. The file must be readable by its owner only. Once the file is in place, the following command should return the identity of ops without any credentials on the command line:

curl -n http://api.corp.internal:8080/api/v1/private/whoami

Hint 5

A .netrc entry is a single line with three keyword and value pairs: machine <host>, login <user>, and password <secret>. The host is the bare name, without a scheme or a port:

machine api.example.com login alice password s3cret

The chmod command sets the file mode. Owner-only read and write is mode 600.