Enhanced Digest Authentication, JWT & RFC Compliance

[mdaneri]

Overview

This pull request improves Pode’s authentication mechanisms by ensuring RFC compliance, fixing WWW-Authenticate headers on authentication failures, and improving request handling. Additionally, it enhances JWT authentication by supporting full RFC 7518 compliance and adds private key support for RSA and ECDSA algorithms. It also introduces support for bearer tokens in query parameters, following RFC 6750.

Key Enhancements & Fixes

JWT Authentication Updates (RFC 7518 Compliance)

• Full support for RFC 7518, expanding supported JWT algorithms:
  • NONE, HS256, HS384, HS512 (HMAC)
  • RS256, RS384, RS512 (RSA)
  • PS256, PS384, PS512 (RSA-PSS)
  • ES256, ES384, ES512 (ECDSA)
• New -PrivateKey parameter in New-PodeAuthScheme for RSA and ECDSA verification.
• Ensures JWT signature verification follows RFC 7518 standards.
• Improved JWT validation, including better error handling for expired or malformed tokens.

Bearer Token Support in Query Parameters (RFC 6750 Compliance)

• Pode now supports passing bearer tokens via query parameters in addition to the Authorization header.
• Example:

  GET /protected-resource?access_token=<jwt>
  

• Security Note: Query parameter usage is not recommended unless necessary, as tokens may be logged in URLs. The Authorization header remains the preferred method.
• Body-based token transmission (RFC 6750 Section 2.2) is not yet implemented.

Digest Authentication Updates (RFC 7616 Compliance)

• Support for multiple algorithms: MD5, SHA-1, SHA-256, SHA-384, SHA-512, and SHA-512/256.
• Quality of Protection (qop) enhancements: Implements auth-int to include message integrity verification.
• Algorithm negotiation: Allows clients to select the strongest supported algorithm.
• Fixes WWW-Authenticate header: Ensures the WWW-Authenticate header is always returned on authentication failure, per RFC 7616.

Fixes to WWW-Authenticate Header for All Authentication Methods

This update ensures that the WWW-Authenticate header is correctly returned when authentication fails, adhering to RFC standards:

• Basic Authentication (RFC 7617): Ensures WWW-Authenticate: Basic realm="ExampleRealm" is included.
• Bearer Authentication (RFC 6750): Returns WWW-Authenticate: Bearer error="invalid_token" when authentication fails.
• Client Certificate Authentication (RFC 5246): Ensures proper handling for TLS mutual authentication failures.
• Form Authentication: Ensures WWW-Authenticate consistency on failed login attempts.
• Digest Authentication (RFC 7616): Correctly formats WWW-Authenticate, even when authentication fails.

New $WebEvent.RawData Field

• Introduces $WebEvent.RawData, which captures the raw request body before parsing.
• Enables auth-int in Digest Authentication and custom authentication mechanisms.

Windows-Specific Limitations

• Windows' built-in Digest authentication only supports MD5.
• auth-int is not supported natively.
• Windows fails if multiple algorithms are listed in WWW-Authenticate.
• These features can still be implemented manually; see examples/Utilities/DigestClient.ps1 for reference.

Example Usage

Example: JWT Authentication with RSA

$privateKey = Get-Content 'C:\\path\\to\\private-key.pem' -Raw | ConvertTo-SecureString -AsPlainText -Force

New-PodeAuthScheme -Bearer -AsJWT -PrivateKey $privateKey | Add-PodeAuth -Name 'ExampleJWT' -Sessionless -ScriptBlock {
    param($payload)
    Write-Output "Authenticated user: $($payload.sub)"
}

Example: Bearer Token in Query Parameter

New-PodeAuthScheme -Bearer   -BearerLocation Query| Add-PodeAuth -Name 'ExampleQuery' -Sessionless -ScriptBlock {
    param($payload)
    Write-Output "Authenticated user: $($payload.sub)"
}

```plain
GET /protected-resource?access_token=eyJhbGciOiJSUzI1NiJ9.eyJleHAiOjE2MjI1NTMyMTQsIm5hbWUiOiJKb2huIERvZSIsInN1YiI6IjEyMyJ9.LP-O8OKwix91a-SZwVK35gEClLZQmsORbW0un2Z4RkY

Recommended Alternative:

Authorization: Bearer <jwt>

Example: Digest Authentication with SHA-256 and auth-int

$uri = "http://localhost:8081/users"
$username = "morty"
$password = "pickle"

$authScheme = New-PodeAuthScheme -Digest -Algorithm "SHA-256" -QualityOfProtection "auth-int"
Start-PodeServer -Auth $authScheme

Testing

• Verified compliance with RFC 7518, 7616, 7617, 6750, and 5246.
• Tested JWT authentication with HMAC, RSA, and ECDSA signatures.
• Verified bearer tokens work in both Authorization headers and query parameters.
• Tested Digest Authentication with auth and auth-int modes.
• Confirmed WWW-Authenticate is always present on authentication failure.
• Ensured $WebEvent.RawData correctly captures raw request body content.

References

• [[RFC 7518: JSON Web Algorithms](https://datatracker.ietf.org/doc/html/rfc7518)](https://datatracker.ietf.org/doc/html/rfc7518)
• [[RFC 7616: Digest Authentication](https://datatracker.ietf.org/doc/html/rfc7616)](https://datatracker.ietf.org/doc/html/rfc7616)
• [[RFC 7617: Basic Authentication](https://datatracker.ietf.org/doc/html/rfc7617)](https://datatracker.ietf.org/doc/html/rfc7617)
• [[RFC 6750: Bearer Authentication](https://datatracker.ietf.org/doc/html/rfc6750)](https://datatracker.ietf.org/doc/html/rfc6750)
• [[RFC 5246: TLS Client Certificate Authentication](https://datatracker.ietf.org/doc/html/rfc5246)](https://datatracker.ietf.org/doc/html/rfc5246)

---

PR Links:

• Feature Request: Improve Pode Authentication to Ensure RFC Compliance and Enhance Security #1475
• Enhancement Request: Expand JWT Algorithm Support (RFC 7518 Compliance) #1481
• Enhancement Request: Support Bearer Token in Query Parameters #1480
• Support for RS256 with JWT #1479