< 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@2d87023b37eb91155071c91dd3d6a2eeb3004705
Line coverage
0%
Covered lines: 0
Uncovered lines: 61
Coverable lines: 61
Total lines: 390
Line coverage: 0%
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 08/26/2025 - 01:25:22 Line coverage: 54% (33/61) Total lines: 389 Tag: Kestrun/Kestrun@07f821172e5dc3657f1be7e6818f18d6721cf38a09/04/2025 - 22:37:32 Line coverage: 54% (33/61) Total lines: 390 Tag: Kestrun/Kestrun@afb7aadc0a8a42bfa2b51ea62c8a6e2cf63faec609/12/2025 - 16:20:13 Line coverage: 54% (33/61) Total lines: 391 Tag: Kestrun/Kestrun@bd014be0a15f3c9298922d2ff67068869adda2a010/13/2025 - 16:52:37 Line coverage: 0% (0/61) Total lines: 390 Tag: Kestrun/Kestrun@10d476bee71c71ad215bb8ab59f219887b5b4a5e

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 {
 0282        if ($PSCmdlet.ParameterSetName -ne 'Options') {
 0283            $Options = [Kestrun.Authentication.ApiKeyAuthenticationOptions]::new()
 0284            $Options.ValidateCodeSettings = [Kestrun.Authentication.AuthenticationCodeSettings]::new()
 0285            if (-not [string]::IsNullOrWhiteSpace($ExpectedKey)) {
 0286                $Options.ExpectedKey = $ExpectedKey
 0287            } elseif ($null -ne $ScriptBlock) {
 0288                $Options.ValidateCodeSettings.Code = $ScriptBlock.ToString()
 0289                $Options.ValidateCodeSettings.Language = [Kestrun.Scripting.ScriptLanguage]::PowerShell
 0290            } elseif (-not [string]::IsNullOrWhiteSpace($Code)) {
 0291                $Options.ValidateCodeSettings.Code = $Code
 0292                $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
 0315            if (-not [string]::IsNullOrWhiteSpace($HeaderName)) {
 0316                $Options.HeaderName = $HeaderName
 317            }
 0318            if ($AdditionalHeaderNames.Count -gt 0) {
 0319                $Options.AdditionalHeaderNames = $AdditionalHeaderNames
 320            }
 0321            if ($AllowQueryStringFallback.IsPresent) {
 0322                $Options.AllowQueryStringFallback = $AllowQueryStringFallback.IsPresent
 323            }
 0324            if ($EmitChallengeHeader.IsPresent) {
 0325                $Options.EmitChallengeHeader = $EmitChallengeHeader.IsPresent
 326            }
 0327            if ($null -ne $ChallengeHeaderFormat) {
 0328                $Options.ChallengeHeaderFormat = $ChallengeHeaderFormat
 329            }
 330
 0331            if ($AllowInsecureHttp.IsPresent) {
 0332                $Options.RequireHttps = $false
 333            } else {
 0334                $Options.RequireHttps = $true
 335            }
 0336            if ($null -ne $ClaimPolicyConfig) {
 0337                $Options.ClaimPolicyConfig = $ClaimPolicyConfig
 338            }
 0339            if ($null -ne $Logger) {
 0340                $Options.Logger = $Logger
 341            }
 342
 0343            if ($PSCmdlet.ParameterSetName.contains('_')) {
 344
 0345                $Options.IssueClaimsCodeSettings = [Kestrun.Authentication.AuthenticationCodeSettings]::new()
 0346                if ($null -ne $IssueClaimsScriptBlock) {
 0347                    $Options.IssueClaimsCodeSettings.Code = $IssueClaimsScriptBlock.ToString()
 0348                    $Options.IssueClaimsCodeSettings.Language = [Kestrun.Scripting.ScriptLanguage]::PowerShell
 0349                } elseif (-not [string]::IsNullOrWhiteSpace($IssueClaimsCode)) {
 0350                    $Options.IssueClaimsCodeSettings.Code = $IssueClaimsCode
 0351                    $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
 0376        $Server = Resolve-KestrunServer -Server $Server
 377
 0378        [Kestrun.Hosting.KestrunHostAuthnExtensions]::AddApiKeyAuthentication(
 379            $Server,
 380            $Name,
 381            $Options
 0382        ) | Out-Null
 383
 0384        if ($PassThru.IsPresent) {
 385            # if the PassThru switch is specified, return the modified server instance
 0386            return $Server
 387        }
 388    }
 389}
 390
Generated by: ReportGenerator 5.4.17.0
10/18/2025 - 15:14:40
GitHub | reportgenerator.io

Methods/Properties

Add-KrApiKeyAuthentication()