| | | 1 | | <# |
| | | 2 | | .SYNOPSIS |
| | | 3 | | Protects a JWT token using a specified secret or certificate. |
| | | 4 | | .DESCRIPTION |
| | | 5 | | This function allows you to sign a JWT token with a secret or certificate, ensuring its integrity and authentici |
| | | 6 | | .PARAMETER Builder |
| | | 7 | | The JWT token builder to modify. |
| | | 8 | | .PARAMETER Base64Url |
| | | 9 | | The Base64Url encoded secret to use for signing the JWT token. |
| | | 10 | | .PARAMETER HexadecimalKey |
| | | 11 | | The hexadecimal key to use for signing the JWT token. |
| | | 12 | | .PARAMETER Passphrase |
| | | 13 | | The passphrase to use for signing the JWT token, provided as a secure string. |
| | | 14 | | .PARAMETER PemPath |
| | | 15 | | The path to a PEM file containing the RSA key to use for signing the JWT token. |
| | | 16 | | .PARAMETER JwkJson |
| | | 17 | | The JWK JSON string to use for signing the JWT token. |
| | | 18 | | .PARAMETER JwkPath |
| | | 19 | | The path to a JWK file to use for signing the JWT token. |
| | | 20 | | .PARAMETER Certificate |
| | | 21 | | The X509 certificate to use for signing the JWT token. |
| | | 22 | | .PARAMETER Algorithm |
| | | 23 | | The algorithm to use for signing the JWT token. |
| | | 24 | | Defaults to 'Auto' which will determine the algorithm based on the provided secret or certificate. |
| | | 25 | | .PARAMETER X509Certificate |
| | | 26 | | The X509 certificate to use for signing the JWT token. |
| | | 27 | | .OUTPUTS |
| | | 28 | | [Kestrun.Jwt.JwtTokenBuilder] |
| | | 29 | | The modified JWT token builder with the signing configuration applied. |
| | | 30 | | .EXAMPLE |
| | | 31 | | $builder = New-KrJWTTokenBuilder | Protect-KrJWT -Base64Url "your_base64_url_secret" |
| | | 32 | | $builder | Protect-KrJWT -HexadecimalKey "a1b2c3d4e5f6" |
| | | 33 | | $builder | Protect-KrJWT -Passphrase (ConvertTo-SecureString "mysecret" -AsPlainText -Force) |
| | | 34 | | $builder | Protect-KrJWT -PemPath "C:\path\to\key.pem" |
| | | 35 | | $builder | Protect-KrJWT -Certificate (Get-Item "C:\path\to\certificate.pfx") |
| | | 36 | | This example demonstrates how to create a JWT token builder and apply various signing methods. |
| | | 37 | | .NOTES |
| | | 38 | | This function is part of the Kestrun.Jwt module and is used to build JWT tokens |
| | | 39 | | Maps to JwtTokenBuilder.SignWithSecret, JwtTokenBuilder.SignWithSecretHex, JwtTokenBuilder.SignWithSecretPassphr |
| | | 40 | | JwtTokenBuilder.SignWithRsaPem, and JwtTokenBuilder.SignWithCertificate methods. |
| | | 41 | | .LINK |
| | | 42 | | https://docs.microsoft.com/en-us/dotnet/api/system.identitymodel.tokens.jwt.jwtsecuritytoken |
| | | 43 | | #> |
| | | 44 | | function Protect-KrJWT { |
| | | 45 | | [KestrunRuntimeApi('Everywhere')] |
| | | 46 | | [CmdletBinding(DefaultParameterSetName = 'SecretBase64Url')] |
| | | 47 | | [OutputType([Kestrun.Jwt.JwtTokenBuilder])] |
| | | 48 | | param( |
| | | 49 | | [Parameter(Mandatory = $true, ValueFromPipeline)] |
| | | 50 | | [Kestrun.Jwt.JwtTokenBuilder] $Builder, |
| | | 51 | | [Parameter(Mandatory = $true, ParameterSetName = 'SecretBase64Url')] |
| | | 52 | | [string] $Base64Url, |
| | | 53 | | [Parameter(Mandatory = $true, ParameterSetName = 'SecretHexadecimalKey')] |
| | | 54 | | [string] $HexadecimalKey, |
| | | 55 | | [Parameter(Mandatory = $true, ParameterSetName = 'SecretPassphrase')] |
| | | 56 | | [securestring] $Passphrase, |
| | | 57 | | [Parameter(Mandatory = $true, ParameterSetName = 'PemPath')] |
| | | 58 | | [string] $PemPath, |
| | | 59 | | [Parameter(Mandatory = $true, ParameterSetName = 'JwkJson')] |
| | | 60 | | [string] $JwkJson, |
| | | 61 | | [Parameter(Mandatory = $true, ParameterSetName = 'JwkPath')] |
| | | 62 | | [string] $JwkPath, |
| | | 63 | | [Parameter(Mandatory = $true, ParameterSetName = 'Certificate')] |
| | | 64 | | [System.Security.Cryptography.X509Certificates.X509Certificate2] $X509Certificate, |
| | | 65 | | [Parameter(Mandatory = $false)] |
| | | 66 | | [ValidateSet('Auto', 'HS256', 'HS384', 'HS512', 'RS256', 'RS384', 'RS512', 'ES256', 'ES384', 'ES512')] |
| | | 67 | | [string] $Algorithm = 'Auto' # Default to 'Auto' which will determine the algorithm based on the provided secret |
| | | 68 | | ) |
| | | 69 | | |
| | | 70 | | process { |
| | 0 | 71 | | $algEnum = [Kestrun.Jwt.JwtAlgorithm]::$Algorithm |
| | 0 | 72 | | switch ($PSCmdlet.ParameterSetName) { |
| | | 73 | | 'SecretBase64Url' { |
| | 0 | 74 | | $Builder.SignWithSecret($Base64Url, $algEnum) | Out-Null |
| | | 75 | | break |
| | | 76 | | } |
| | | 77 | | 'SecretHexadecimalKey' { |
| | 0 | 78 | | $Builder.SignWithSecretHex($HexadecimalKey, $algEnum) | Out-Null |
| | | 79 | | break |
| | | 80 | | } |
| | | 81 | | 'SecretPassphrase' { |
| | 0 | 82 | | $Builder.SignWithSecretPassphrase($Passphrase, $algEnum) | Out-Null |
| | | 83 | | break |
| | | 84 | | } |
| | | 85 | | 'PemPath' { |
| | 0 | 86 | | $resolvedPath = Resolve-KrPath -Path $PemPath -KestrunRoot |
| | 0 | 87 | | $Builder.SignWithRsaPem($resolvedPath, $algEnum) | Out-Null |
| | | 88 | | break |
| | | 89 | | } |
| | | 90 | | 'Certificate' { |
| | 0 | 91 | | $Builder.SignWithCertificate($X509Certificate, $algEnum) | Out-Null |
| | | 92 | | break |
| | | 93 | | } |
| | | 94 | | 'JwkJson' { |
| | 0 | 95 | | $Builder.SignWithJwkJson($JwkJson, $algEnum) | Out-Null |
| | | 96 | | break |
| | | 97 | | } |
| | | 98 | | 'JwkPath' { |
| | 0 | 99 | | $resolvedPath = Resolve-KrPath -Path $JwkPath -KestrunRoot |
| | 0 | 100 | | $json = Get-Content -Path $resolvedPath -Raw |
| | 0 | 101 | | $Builder.SignWithJwkJson($json, $algEnum) | Out-Null |
| | | 102 | | break |
| | | 103 | | } |
| | | 104 | | } |
| | 0 | 105 | | return $Builder |
| | | 106 | | } |
| | | 107 | | } |