< Summary - Kestrun — Combined Coverage

Information
Class: Public.Authentication.Add-KrApiKeyAuthentication
Assembly: Kestrun.PowerShell.Public
File(s): /home/runner/work/Kestrun/Kestrun/src/PowerShell/Kestrun/Public/Authentication/Add-KrApiKeyAuthentication.ps1
Tag: Kestrun/Kestrun@9d3a582b2d63930269564a7591aa77ef297cadeb
Line coverage
54%
Covered lines: 33
Uncovered lines: 28
Coverable lines: 61
Total lines: 390
Line coverage: 54%
Branch coverage
N/A
Covered branches: 0
Total branches: 0
Branch coverage: N/A
Method coverage

Feature is only available for sponsors

Upgrade to PRO version

Coverage history

Coverage history 0 25 50 75 100

Metrics

Method
Add-KrApiKeyAuthentication()

File(s)

/home/runner/work/Kestrun/Kestrun/src/PowerShell/Kestrun/Public/Authentication/Add-KrApiKeyAuthentication.ps1

#LineLine coverage
 1<#
 2    .SYNOPSIS
 3        Adds API key authentication to the Kestrun server.
 4    .DESCRIPTION
 5        Configures the Kestrun server to use API key authentication for incoming requests.
 6    .PARAMETER Server
 7        The Kestrun server instance to configure.
 8    .PARAMETER Name
 9        The name of the API key authentication scheme.
 10    .PARAMETER Options
 11        The options to configure the API key authentication.
 12    .PARAMETER ScriptBlock
 13        A script block that contains the logic for validating the API key.
 14    .PARAMETER Code
 15        C# or VBNet code that contains the logic for validating the API key.
 16    .PARAMETER CodeLanguage
 17        The scripting language of the code used for validating the API key.
 18    .PARAMETER CodeFilePath
 19        Path to a file containing C# code that contains the logic for validating the API key.
 20    .PARAMETER ExpectedKey
 21        The expected API key to validate against.
 22    .PARAMETER HeaderName
 23        The name of the header to look for the API key.
 24    .PARAMETER AdditionalHeaderNames
 25        Additional headers to check for the API key.
 26    .PARAMETER AllowQueryStringFallback
 27        If specified, allows the API key to be provided in the query string.
 28    .PARAMETER AllowInsecureHttp
 29        If specified, allows the API key to be provided over HTTP instead of HTTPS.
 30    .PARAMETER EmitChallengeHeader
 31        If specified, emits a challenge header when the API key is missing or invalid.
 32    .PARAMETER ChallengeHeaderFormat
 33        The format of the challenge header to emit.
 34    .PARAMETER Logger
 35        A logger to use for logging authentication events.
 36    .PARAMETER ClaimPolicyConfig
 37        Configuration for claim policies to apply during authentication.
 38    .PARAMETER IssueClaimsScriptBlock
 39        A script block that contains the logic for issuing claims after successful authentication.
 40    .PARAMETER IssueClaimsCode
 41        C# or VBNet code that contains the logic for issuing claims after successful authentication.
 42    .PARAMETER IssueClaimsCodeLanguage
 43        The scripting language of the code used for issuing claims.
 44    .PARAMETER IssueClaimsCodeFilePath
 45        Path to a file containing the code that contains the logic for issuing claims after successful authentication
 46    .PARAMETER PassThru
 47        If specified, returns the modified server instance after adding the authentication.
 48    .EXAMPLE
 49        Add-KrApiKeyAuthentication -Name 'MyApiKey' -ExpectedKey '12345' -HeaderName 'X-Api-Key'
 50        This example adds API key authentication to the server with the specified expected key and header name.
 51    .EXAMPLE
 52        Add-KrApiKeyAuthentication -Name 'MyApiKey' -ScriptBlock {
 53            param($username, $password)
 54            return $username -eq 'admin' -and $password -eq 'password'
 55        }
 56        This example adds API key authentication using a script block to validate the API key.
 57    .EXAMPLE
 58        Add-KrApiKeyAuthentication -Name 'MyApiKey' -Code @"
 59            return username == "admin" && password == "password";
 60        "@
 61        This example adds API key authentication using C# code to validate the API key.
 62    .EXAMPLE
 63        Add-KrApiKeyAuthentication -Name 'MyApiKey' -CodeFilePath 'C:\path\to\code.cs'
 64        This example adds API key authentication using a C# code file to validate the API key.
 65    .LINK
 66        https://learn.microsoft.com/en-us/dotnet/api/microsoft.aspnetcore.authentication.apikey.apikeyauthenticationopti
 67    .NOTES
 68        This cmdlet is used to configure API key authentication for the Kestrun server, allowing you to secure your APIs
 69#>
 70function Add-KrApiKeyAuthentication {
 71    [KestrunRuntimeApi('Definition')]
 72    [CmdletBinding(defaultParameterSetName = 'ItemsScriptBlock')]
 73    [OutputType([Kestrun.Hosting.KestrunHost])]
 74    param(
 75        [Parameter(Mandatory = $false, ValueFromPipeline)]
 76        [Kestrun.Hosting.KestrunHost]$Server,
 77
 78        [Parameter(Mandatory = $true)]
 79        [string]$Name,
 80
 81        [Parameter(Mandatory = $true, ParameterSetName = 'Options')]
 82        [Kestrun.Authentication.ApiKeyAuthenticationOptions]$Options,
 83
 84        [Parameter(Mandatory = $true, ParameterSetName = 'v1')]
 85        [Parameter(Mandatory = $true, ParameterSetName = 'v1_i1')]
 86        [Parameter(Mandatory = $true, ParameterSetName = 'v1_i2')]
 87        [Parameter(Mandatory = $true, ParameterSetName = 'v1_i3')]
 88        [scriptblock]$ScriptBlock,
 89
 90        [Parameter(Mandatory = $true, ParameterSetName = 'v2')]
 91        [Parameter(Mandatory = $true, ParameterSetName = 'v2_i1')]
 92        [Parameter(Mandatory = $true, ParameterSetName = 'v2_i2')]
 93        [Parameter(Mandatory = $true, ParameterSetName = 'v2_i3')]
 94        [string]$Code,
 95
 96        [Parameter(ParameterSetName = 'v2')]
 97        [Parameter(ParameterSetName = 'v2_i1')]
 98        [Parameter(ParameterSetName = 'v2_i2')]
 99        [Parameter(ParameterSetName = 'v2_i3')]
 100        [Kestrun.Scripting.ScriptLanguage]$CodeLanguage = [Kestrun.Scripting.ScriptLanguage]::CSharp,
 101
 102        [Parameter(Mandatory = $true, ParameterSetName = 'v3')]
 103        [Parameter(Mandatory = $true, ParameterSetName = 'v3_i1')]
 104        [Parameter(Mandatory = $true, ParameterSetName = 'v3_i2')]
 105        [Parameter(Mandatory = $true, ParameterSetName = 'v3_i3')]
 106        [string]$CodeFilePath,
 107
 108        [Parameter(Mandatory = $true, ParameterSetName = 'v4')]
 109        [Parameter(Mandatory = $true, ParameterSetName = 'v4_i1')]
 110        [Parameter(Mandatory = $true, ParameterSetName = 'v4_i2')]
 111        [Parameter(Mandatory = $true, ParameterSetName = 'v4_i3')]
 112        [string]$ExpectedKey,
 113
 114        [Parameter(ParameterSetName = 'v1')]
 115        [Parameter(ParameterSetName = 'v1_i1')]
 116        [Parameter(ParameterSetName = 'v1_i2')]
 117        [Parameter(ParameterSetName = 'v1_i3')]
 118        [Parameter(ParameterSetName = 'v2')]
 119        [Parameter(ParameterSetName = 'v2_i1')]
 120        [Parameter(ParameterSetName = 'v2_i2')]
 121        [Parameter(ParameterSetName = 'v2_i3')]
 122        [Parameter(ParameterSetName = 'v3')]
 123        [Parameter(ParameterSetName = 'v3_i1')]
 124        [Parameter(ParameterSetName = 'v3_i2')]
 125        [Parameter(ParameterSetName = 'v3_i3')]
 126        [Parameter(ParameterSetName = 'v4')]
 127        [Parameter(ParameterSetName = 'v4_i1')]
 128        [Parameter(ParameterSetName = 'v4_i2')]
 129        [Parameter(ParameterSetName = 'v4_i3')]
 130        [string]$HeaderName,
 131
 132        [Parameter(ParameterSetName = 'v1')]
 133        [Parameter(ParameterSetName = 'v1_i1')]
 134        [Parameter(ParameterSetName = 'v1_i2')]
 135        [Parameter(ParameterSetName = 'v1_i3')]
 136        [Parameter(ParameterSetName = 'v2')]
 137        [Parameter(ParameterSetName = 'v2_i1')]
 138        [Parameter(ParameterSetName = 'v2_i2')]
 139        [Parameter(ParameterSetName = 'v2_i3')]
 140        [Parameter(ParameterSetName = 'v3')]
 141        [Parameter(ParameterSetName = 'v3_i1')]
 142        [Parameter(ParameterSetName = 'v3_i2')]
 143        [Parameter(ParameterSetName = 'v3_i3')]
 144        [Parameter(ParameterSetName = 'v4')]
 145        [Parameter(ParameterSetName = 'v4_i1')]
 146        [Parameter(ParameterSetName = 'v4_i2')]
 147        [Parameter(ParameterSetName = 'v4_i3')]
 148        [string[]]$AdditionalHeaderNames,
 149
 150        [Parameter(ParameterSetName = 'v1')]
 151        [Parameter(ParameterSetName = 'v1_i1')]
 152        [Parameter(ParameterSetName = 'v1_i2')]
 153        [Parameter(ParameterSetName = 'v1_i3')]
 154        [Parameter(ParameterSetName = 'v2')]
 155        [Parameter(ParameterSetName = 'v2_i1')]
 156        [Parameter(ParameterSetName = 'v2_i2')]
 157        [Parameter(ParameterSetName = 'v2_i3')]
 158        [Parameter(ParameterSetName = 'v3')]
 159        [Parameter(ParameterSetName = 'v3_i1')]
 160        [Parameter(ParameterSetName = 'v3_i2')]
 161        [Parameter(ParameterSetName = 'v3_i3')]
 162        [Parameter(ParameterSetName = 'v4')]
 163        [Parameter(ParameterSetName = 'v4_i1')]
 164        [Parameter(ParameterSetName = 'v4_i2')]
 165        [Parameter(ParameterSetName = 'v4_i3')]
 166        [switch]$AllowQueryStringFallback,
 167
 168        [Parameter(ParameterSetName = 'v1')]
 169        [Parameter(ParameterSetName = 'v1_i1')]
 170        [Parameter(ParameterSetName = 'v1_i2')]
 171        [Parameter(ParameterSetName = 'v1_i3')]
 172        [Parameter(ParameterSetName = 'v2')]
 173        [Parameter(ParameterSetName = 'v2_i1')]
 174        [Parameter(ParameterSetName = 'v2_i2')]
 175        [Parameter(ParameterSetName = 'v2_i3')]
 176        [Parameter(ParameterSetName = 'v3')]
 177        [Parameter(ParameterSetName = 'v3_i1')]
 178        [Parameter(ParameterSetName = 'v3_i2')]
 179        [Parameter(ParameterSetName = 'v3_i3')]
 180        [Parameter(ParameterSetName = 'v4')]
 181        [Parameter(ParameterSetName = 'v4_i1')]
 182        [Parameter(ParameterSetName = 'v4_i2')]
 183        [Parameter(ParameterSetName = 'v4_i3')]
 184        [switch]$AllowInsecureHttp,
 185
 186        [Parameter(ParameterSetName = 'v1')]
 187        [Parameter(ParameterSetName = 'v1_i1')]
 188        [Parameter(ParameterSetName = 'v1_i2')]
 189        [Parameter(ParameterSetName = 'v1_i3')]
 190        [Parameter(ParameterSetName = 'v2')]
 191        [Parameter(ParameterSetName = 'v2_i1')]
 192        [Parameter(ParameterSetName = 'v2_i2')]
 193        [Parameter(ParameterSetName = 'v2_i3')]
 194        [Parameter(ParameterSetName = 'v3')]
 195        [Parameter(ParameterSetName = 'v3_i1')]
 196        [Parameter(ParameterSetName = 'v3_i2')]
 197        [Parameter(ParameterSetName = 'v3_i3')]
 198        [Parameter(ParameterSetName = 'v4')]
 199        [Parameter(ParameterSetName = 'v4_i1')]
 200        [Parameter(ParameterSetName = 'v4_i2')]
 201        [Parameter(ParameterSetName = 'v4_i3')]
 202        [switch]$EmitChallengeHeader,
 203
 204        [Parameter(ParameterSetName = 'v1')]
 205        [Parameter(ParameterSetName = 'v1_i1')]
 206        [Parameter(ParameterSetName = 'v1_i2')]
 207        [Parameter(ParameterSetName = 'v1_i3')]
 208        [Parameter(ParameterSetName = 'v2')]
 209        [Parameter(ParameterSetName = 'v2_i1')]
 210        [Parameter(ParameterSetName = 'v2_i2')]
 211        [Parameter(ParameterSetName = 'v2_i3')]
 212        [Parameter(ParameterSetName = 'v3')]
 213        [Parameter(ParameterSetName = 'v3_i1')]
 214        [Parameter(ParameterSetName = 'v3_i2')]
 215        [Parameter(ParameterSetName = 'v3_i3')]
 216        [Parameter(ParameterSetName = 'v4')]
 217        [Parameter(ParameterSetName = 'v4_i1')]
 218        [Parameter(ParameterSetName = 'v4_i2')]
 219        [Parameter(ParameterSetName = 'v4_i3')]
 220        [Kestrun.Authentication.ApiKeyChallengeFormat]$ChallengeHeaderFormat,
 221
 222        [Parameter(ParameterSetName = 'v1')]
 223        [Parameter(ParameterSetName = 'v1_i1')]
 224        [Parameter(ParameterSetName = 'v1_i2')]
 225        [Parameter(ParameterSetName = 'v1_i3')]
 226        [Parameter(ParameterSetName = 'v2')]
 227        [Parameter(ParameterSetName = 'v2_i1')]
 228        [Parameter(ParameterSetName = 'v2_i2')]
 229        [Parameter(ParameterSetName = 'v2_i3')]
 230        [Parameter(ParameterSetName = 'v3')]
 231        [Parameter(ParameterSetName = 'v3_i1')]
 232        [Parameter(ParameterSetName = 'v3_i2')]
 233        [Parameter(ParameterSetName = 'v3_i3')]
 234        [Parameter(ParameterSetName = 'v4')]
 235        [Parameter(ParameterSetName = 'v4_i1')]
 236        [Parameter(ParameterSetName = 'v4_i2')]
 237        [Parameter(ParameterSetName = 'v4_i3')]
 238        [Serilog.ILogger]$Logger,
 239
 240        [Parameter(ParameterSetName = 'v1_i1')]
 241        [Parameter(ParameterSetName = 'v1_i2')]
 242        [Parameter(ParameterSetName = 'v1_i3')]
 243        [Parameter(ParameterSetName = 'v2_i1')]
 244        [Parameter(ParameterSetName = 'v2_i2')]
 245        [Parameter(ParameterSetName = 'v2_i3')]
 246        [Parameter(ParameterSetName = 'v3_i1')]
 247        [Parameter(ParameterSetName = 'v3_i2')]
 248        [Parameter(ParameterSetName = 'v3_i3')]
 249        [Parameter(ParameterSetName = 'v4_i1')]
 250        [Parameter(ParameterSetName = 'v4_i2')]
 251        [Parameter(ParameterSetName = 'v4_i3')]
 252        [Kestrun.Claims.ClaimPolicyConfig]$ClaimPolicyConfig,
 253
 254        [Parameter(Mandatory = $true, ParameterSetName = 'v1_i1')]
 255        [Parameter(Mandatory = $true, ParameterSetName = 'v2_i1')]
 256        [Parameter(Mandatory = $true, ParameterSetName = 'v3_i1')]
 257        [Parameter(Mandatory = $true, ParameterSetName = 'v4_i1')]
 258        [scriptblock]$IssueClaimsScriptBlock,
 259
 260        [Parameter(Mandatory = $true, ParameterSetName = 'v3_i2')]
 261        [Parameter(Mandatory = $true, ParameterSetName = 'v2_i2')]
 262        [Parameter(Mandatory = $true, ParameterSetName = 'v1_i2')]
 263        [Parameter(Mandatory = $true, ParameterSetName = 'v4_i2')]
 264        [string]$IssueClaimsCode,
 265
 266        [Parameter(ParameterSetName = 'v3_i2')]
 267        [Parameter(ParameterSetName = 'v2_i2')]
 268        [Parameter(ParameterSetName = 'v1_i2')]
 269        [Parameter(ParameterSetName = 'v4_i2')]
 270        [Kestrun.Scripting.ScriptLanguage]$IssueClaimsCodeLanguage = [Kestrun.Scripting.ScriptLanguage]::CSharp,
 271
 272        [Parameter(Mandatory = $true, ParameterSetName = 'v3_i3')]
 273        [Parameter(Mandatory = $true, ParameterSetName = 'v2_i3')]
 274        [Parameter(Mandatory = $true, ParameterSetName = 'v1_i3')]
 275        [Parameter(Mandatory = $true, ParameterSetName = 'v4_i3')]
 276        [string]$IssueClaimsCodeFilePath,
 277
 278        [Parameter()]
 279        [switch]$PassThru
 280    )
 281    process {
 1282        if ($PSCmdlet.ParameterSetName -ne 'Options') {
 1283            $Options = [Kestrun.Authentication.ApiKeyAuthenticationOptions]::new()
 1284            $Options.ValidateCodeSettings = [Kestrun.Authentication.AuthenticationCodeSettings]::new()
 1285            if (-not [string]::IsNullOrWhiteSpace($ExpectedKey)) {
 1286                $Options.ExpectedKey = $ExpectedKey
 1287            } elseif ($null -ne $ScriptBlock) {
 1288                $Options.ValidateCodeSettings.Code = $ScriptBlock.ToString()
 1289                $Options.ValidateCodeSettings.Language = [Kestrun.Scripting.ScriptLanguage]::PowerShell
 1290            } elseif (-not [string]::IsNullOrWhiteSpace($Code)) {
 1291                $Options.ValidateCodeSettings.Code = $Code
 1292                $Options.ValidateCodeSettings.Language = $CodeLanguage
 0293            } elseif (-not [string]::IsNullOrWhiteSpace($CodeFilePath)) {
 0294                if (-not (Test-Path -Path $CodeFilePath)) {
 0295                    throw "The specified code file path does not exist: $CodeFilePath"
 296                }
 0297                $extension = Split-Path -Path $CodeFilePath -Extension
 0298                switch ($extension) {
 299                    '.ps1' {
 0300                        $Options.ValidateCodeSettings.Language = [Kestrun.Scripting.ScriptLanguage]::PowerShell
 301                    }
 302                    '.cs' {
 0303                        $Options.ValidateCodeSettings.Language = [Kestrun.Scripting.ScriptLanguage]::CSharp
 304                    }
 305                    '.vb' {
 0306                        $Options.ValidateCodeSettings.Language = [Kestrun.Scripting.ScriptLanguage]::VisualBasic
 307                    }
 308                    default {
 0309                        throw "Unsupported '$extension' code file extension."
 310                    }
 311                }
 0312                $Options.ValidateCodeSettings.Code = Get-Content -Path $CodeFilePath -Raw
 313            }
 314
 1315            if (-not [string]::IsNullOrWhiteSpace($HeaderName)) {
 1316                $Options.HeaderName = $HeaderName
 317            }
 1318            if ($AdditionalHeaderNames.Count -gt 0) {
 0319                $Options.AdditionalHeaderNames = $AdditionalHeaderNames
 320            }
 1321            if ($AllowQueryStringFallback.IsPresent) {
 0322                $Options.AllowQueryStringFallback = $AllowQueryStringFallback.IsPresent
 323            }
 1324            if ($EmitChallengeHeader.IsPresent) {
 0325                $Options.EmitChallengeHeader = $EmitChallengeHeader.IsPresent
 326            }
 1327            if ($null -ne $ChallengeHeaderFormat) {
 0328                $Options.ChallengeHeaderFormat = $ChallengeHeaderFormat
 329            }
 330
 1331            if ($AllowInsecureHttp.IsPresent) {
 1332                $Options.RequireHttps = $false
 333            } else {
 0334                $Options.RequireHttps = $true
 335            }
 1336            if ($null -ne $ClaimPolicyConfig) {
 1337                $Options.ClaimPolicyConfig = $ClaimPolicyConfig
 338            }
 1339            if ($null -ne $Logger) {
 1340                $Options.Logger = $Logger
 341            }
 342
 1343            if ($PSCmdlet.ParameterSetName.contains('_')) {
 344
 1345                $Options.IssueClaimsCodeSettings = [Kestrun.Authentication.AuthenticationCodeSettings]::new()
 1346                if ($null -ne $IssueClaimsScriptBlock) {
 0347                    $Options.IssueClaimsCodeSettings.Code = $IssueClaimsScriptBlock.ToString()
 0348                    $Options.IssueClaimsCodeSettings.Language = [Kestrun.Scripting.ScriptLanguage]::PowerShell
 1349                } elseif (-not [string]::IsNullOrWhiteSpace($IssueClaimsCode)) {
 1350                    $Options.IssueClaimsCodeSettings.Code = $IssueClaimsCode
 1351                    $Options.IssueClaimsCodeSettings.Language = $IssueClaimsCodeLanguage
 0352                } elseif (-not [string]::IsNullOrWhiteSpace($IssueClaimsCodeFilePath)) {
 0353                    if (-not (Test-Path -Path $IssueClaimsCodeFilePath)) {
 0354                        throw "The specified code file path does not exist: $IssueClaimsCodeFilePath"
 355                    }
 0356                    $extension = Split-Path -Path $IssueClaimsCodeFilePath -Extension
 0357                    switch ($extension) {
 358                        '.ps1' {
 0359                            $Options.IssueClaimsCodeSettings.Language = [Kestrun.Scripting.ScriptLanguage]::PowerShell
 360                        }
 361                        '.cs' {
 0362                            $Options.IssueClaimsCodeSettings.Language = [Kestrun.Scripting.ScriptLanguage]::CSharp
 363                        }
 364                        '.vb' {
 0365                            $Options.IssueClaimsCodeSettings.Language = [Kestrun.Scripting.ScriptLanguage]::VisualBasic
 366                        }
 367                        default {
 0368                            throw "Unsupported '$extension' code file extension."
 369                        }
 370                    }
 0371                    $Options.IssueClaimsCodeSettings.Code = Get-Content -Path $CodeFilePath -Raw
 372                }
 373            }
 374        }
 375        # Ensure the server instance is resolved
 1376        $Server = Resolve-KestrunServer -Server $Server
 377
 1378        [Kestrun.Hosting.KestrunHostAuthExtensions]::AddApiKeyAuthentication(
 379            $Server,
 380            $Name,
 381            $Options
 1382        ) | Out-Null
 1383        if ($PassThru.IsPresent) {
 384            # if the PassThru switch is specified, return the server instance
 385            # Return the modified server instance
 0386            return $Server
 387        }
 388    }
 389}
 390
Generated by: ReportGenerator 5.4.12.0
09/10/2025 - 19:58:59
GitHub | reportgenerator.io

Methods/Properties

Add-KrApiKeyAuthentication()