Skip to content

authentication.md

Latest commit

 

History

History
290 lines (194 loc) · 7.37 KB

authentication.md

File metadata and controls

290 lines (194 loc) · 7.37 KB
Raw

Authentication

fetch supports multiple authentication methods for accessing protected resources.

HTTP Basic Authentication

Basic Authentication sends credentials as a base64-encoded Authorization header.

Command Line

fetch --basic username:password example.com

How It Works

The --basic flag sets the Authorization header:

Authorization: Basic base64(username:password)

HTTP Digest Authentication

Digest Authentication uses a challenge-response mechanism that is more secure than Basic Authentication because credentials are never sent in plain text.

Command Line

fetch --digest username:password example.com

How It Works

The --digest flag performs a two-step handshake:

  1. Challenge: The server responds with 401 Unauthorized and a WWW-Authenticate: Digest ... header containing a nonce and realm.
  2. Response: fetch computes the digest from the credentials, nonce, algorithm, and request details, then resends the request with an Authorization header:
Authorization: Digest username="...", realm="...", nonce="...", uri="...", response="..."

fetch supports challenges without qop and challenges with qop=auth using MD5, MD5-SESS, SHA-256, SHA-256-SESS, SHA-512-256, or SHA-512-256-SESS. If the server only offers unsupported parameters such as qop=auth-int, fetch exits with a diagnostic instead of treating it as an ordinary 401 Unauthorized.

Compatibility with curl

fetch supports curl's --digest flag when using --from-curl:

fetch --from-curl 'curl --digest -u username:password example.com'

Bearer Token Authentication

Bearer tokens are commonly used with OAuth 2.0 and JWT-based authentication.

Command Line

fetch --bearer mytoken123 example.com

How It Works

The --bearer flag sets the Authorization header:

Authorization: Bearer mytoken123

Using Environment Variables

For security, avoid putting tokens directly in commands:

fetch --bearer "$API_TOKEN" example.com

Or read from a file:

fetch -H "Authorization: Bearer $(cat ~/.api-token)" example.com

AWS Signature V4

Sign requests for AWS services using AWS Signature V4.

Prerequisites

Set the required environment variables:

export AWS_ACCESS_KEY_ID="your-access-key"
export AWS_SECRET_ACCESS_KEY="your-secret-key"

Command Line

fetch --aws-sigv4 REGION/SERVICE url

Examples

# S3 request
fetch --aws-sigv4 us-east-1/s3 https://my-bucket.s3.amazonaws.com/key

# API Gateway
fetch --aws-sigv4 us-west-2/execute-api https://abc123.execute-api.us-west-2.amazonaws.com/prod/resource

# Lambda function URL
fetch --aws-sigv4 eu-west-1/lambda https://xyz.lambda-url.eu-west-1.on.aws/

How It Works

AWS SigV4 signs the request by:

  1. Creating a canonical request from the HTTP method, path, query string, headers, and body
  2. Generating a signing key from your secret key, date, region, and service
  3. Computing an HMAC-SHA256 signature
  4. Adding the signature to the Authorization header

When AWS_SESSION_TOKEN is set for temporary STS or role credentials, fetch adds it as x-amz-security-token before signing so AWS can validate the temporary credential scope.

Mutual TLS (mTLS)

mTLS provides two-way authentication where both client and server present certificates.

Basic Usage

fetch --cert client.crt --key client.key example.com

Combined Certificate and Key

If your PEM file contains both the certificate and private key:

fetch --cert client.pem example.com

With Custom CA Certificate

When the server uses a private CA:

fetch --cert client.crt --key client.key --ca-cert ca.crt example.com

Configuration File

# Global mTLS settings
cert = /path/to/client.crt
key = /path/to/client.key

# Host-specific mTLS
[api.secure.example.com]
cert = /path/to/api-client.crt
key = /path/to/api-client.key
ca-cert = /path/to/api-ca.crt

Certificate Formats

  • Certificates and keys must be in PEM format
  • TLS requests reject a private key without a client certificate, including values from config files or --from-curl
  • Encrypted private keys are not supported
  • In a combined PEM file, put the certificate before the key.

Example: Self-Signed Certificates

Generate test certificates:

# Generate CA
openssl genrsa -out ca.key 4096
openssl req -new -x509 -days 365 -key ca.key -out ca.crt -subj "/CN=Test CA"

# Generate client certificate
openssl genrsa -out client.key 4096
openssl req -new -key client.key -out client.csr -subj "/CN=client"
openssl x509 -req -days 365 -in client.csr -CA ca.crt -CAkey ca.key -CAcreateserial -out client.crt

Use with fetch:

fetch --cert client.crt --key client.key --ca-cert ca.crt https://mtls.example.com

Custom Headers

For authentication methods not directly supported, use custom headers:

# API Key in header
fetch -H "X-API-Key: your-api-key" example.com

# Custom token format
fetch -H "X-Auth-Token: custom-token" example.com

# Multiple auth headers
fetch -H "X-API-Key: key" -H "X-Signature: sig" example.com

Configuration File

[api.example.com]
header = X-API-Key: your-api-key
header = X-Client-ID: client123

Authentication Precedence

Authentication options are mutually exclusive. You cannot combine:

  • --basic
  • --digest
  • --bearer
  • --aws-sigv4

If you need multiple authentication headers, use -H for additional headers.

Security Considerations

  1. Do not put secrets in scripts. Use environment variables or secure vaults.
  2. Protect configuration files. Set applicable file permissions, such as chmod 600.
  3. Use HTTPS. Do not send credentials over unencrypted HTTP.
  4. Replace credentials regularly. This is especially important for API keys and tokens.

Secure Credential Handling

# Using environment variables
export API_TOKEN="$(vault read -field=token secret/api)"
fetch --bearer "$API_TOKEN" example.com

# Using password manager
fetch --basic "$(pass show api/credentials)" example.com

# Reading from secure file
fetch --bearer "$(cat /run/secrets/api-token)" example.com

Troubleshooting

401 Unauthorized

  • Verify credentials are correct
  • Check if the authentication method matches what the server expects
  • Make sure that the tokens are not expired.

403 Forbidden

  • Authentication succeeded but authorization failed
  • Check if your credentials have the required permissions

Certificate Errors with mTLS

  • Make sure that the certificate and key match. The output of openssl x509 -noout -modulus -in cert.crt | openssl md5 must match the output of openssl rsa -noout -modulus -in key.key | openssl md5.
  • Check the certificate expiration: openssl x509 -noout -dates -in cert.crt.
  • Make sure that the CA certificate is correct for the server.

AWS SigV4 Errors

  • Verify AWS_ACCESS_KEY_ID and AWS_SECRET_ACCESS_KEY are set
  • Check the region and service name are correct
  • Make sure that your credentials have the necessary IAM permissions.
  • Verify system clock is accurate (signatures are time-sensitive)

See Also