Skip to content

authentication.md

Latest commit

 

History

History
309 lines (209 loc) · 8.88 KB

authentication.md

File metadata and controls

309 lines (209 loc) · 8.88 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)

Credentials in URL userinfo, such as https://user:password@example.com, are also converted to Basic authentication and removed from the request URL. Explicit Authorization headers override URL userinfo. The --basic and --bearer options take precedence over an explicit header.

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 RFC 7616 digest and resends the request with an Authorization header:
Authorization: Digest username="...", realm="...", nonce="...", uri="...", response="..."

fetch supports MD5, MD5-sess, SHA-256, SHA-256-sess, SHA-512-256, and SHA-512-256-sess. It supports challenges with no qop and selects auth when it appears in a qop list. auth-int and unknown-only qop lists are rejected with a clear diagnostic. Quoted UTF-8 values and quoted-pair escapes are preserved. A challenge response can replay the request body, and a stale nonce is retried once; one-shot bodies such as stdin cannot be replayed for Digest authentication. This authentication replay is separate from transient --retry behavior: it can still resend an unsafe method without --retry-unsafe.

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

For temporary credentials, also set AWS_SESSION_TOKEN. fetch sends it as x-amz-security-token and includes that header in the signature. SigV4 keeps duplicate query parameters, sorts their AWS-encoded keys and values, and treats + as a literal plus sign.

When AWS signing is enabled, it generates the Authorization header. AWS credentials and signing headers are removed before a cross-origin redirect.

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
  • Encrypted private keys are not supported
  • Combined PEM files should have 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

For safety, automatic redirects with mTLS configured are allowed only within the initial HTTP origin. A redirect to a different scheme, host, or port is refused before the destination TLS handshake, so the client certificate cannot be presented to an unintended service.

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

Credential-bearing custom headers are removed before a redirected request is sent to a different scheme, host, or port. This includes the examples above and generated headers whose names identify authentication material. Header names are matched by complete components and case boundaries, including compound names such as X-ApiKey, rather than arbitrary substrings, so ordinary headers such as X-Keyboard-Layout and X-KeyboardLayout continue to follow redirects. Code that generates a credential header with an otherwise unclassified name must mark it with client.MarkCredentialHeaders. Credential headers are not restored if a later redirect returns to the original origin; ordinary non-credential headers continue to follow redirects.

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. Avoid embedding secrets in scripts - Use environment variables or secure vaults
  2. Protect configuration files - Set appropriate file permissions (chmod 600)
  3. Use HTTPS - Never send credentials over unencrypted HTTP
  4. Rotate credentials regularly - Especially 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
  • Ensure tokens haven't expired

403 Forbidden

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

Certificate Errors with mTLS

  • Verify certificate and key match: openssl x509 -noout -modulus -in cert.crt | openssl md5 should match openssl rsa -noout -modulus -in key.key | openssl md5
  • Check certificate expiration: openssl x509 -noout -dates -in cert.crt
  • Ensure 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
  • Ensure your credentials have the required IAM permissions
  • Verify system clock is accurate (signatures are time-sensitive)

See Also