Authentication Enhancements: Invoke-PodeAuth & -NoMiddlewareAuthentication

[mdaneri]

Summary

This pull request introduces improvements to Pode's authentication handling by adding a new Invoke-PodeAuth function and a -NoMiddlewareAuthentication parameter for Add-PodeRoute. These changes provide greater flexibility and control over authentication processing within routes.

Changes Introduced

1. Invoke-PodeAuth Function

• A new function that directly invokes authentication methods and returns the result from Add-PodeAuth.
• This function is adding to the existing Test-PodeAuth, which was not suitable for handling authentication logic in this context.
• Provides a streamlined approach for manually handling authentication within routes.

2. -NoMiddlewareAuthentication Parameter for Add-PodeRoute

• Allows routes to bypass automatic authentication middleware processing.
• Enables manual authentication checks within route script blocks, giving developers more control over authentication flow.

Motivation

The existing approach using Test-PodeAuth did not provide sufficient flexibility for manual authentication handling within routes. These changes allow developers to handle authentication responses directly, improving customization and control over the authentication process.

Usage Example

New-PodeAuthScheme -ApiKey | Add-PodeAuth -Name 'APIKey' -Sessionless -ScriptBlock {
    param($key)

    # Handle missing API key
    if (!$key) {
        return @{ Success = $false; Reason = 'No X-API-KEY Header found' }
    }

    # Validate API key
    if ($key -eq 'test_user') {
        return @{ Success = $true; User = 'test_user'; UserId = 1 }
    }

    # Return failure for invalid users
    return @{ Success = $false; User = $key; UserId = -1; Reason = 'Not existing user' }
}
    
Add-PodeRoute -Method 'Get' -Path '/api/v3/' -Authentication 'APIKey' -NoMiddlewareAuthentication -ScriptBlock {
    $auth = Invoke-PodeAuth -Name 'APIKey'

    if ($auth.Success) {
        Write-PodeJsonResponse -Value @{ Username = $auth.User }
    } else {
        Write-PodeJsonResponse -Value @{ message = $auth.Reason; user = $auth.User } -StatusCode 401
    }
}