| | | 1 | | <# |
| | | 2 | | .SYNOPSIS |
| | | 3 | | Creates and configures a new [Microsoft.AspNetCore.Http.CookieBuilder] instance. |
| | | 4 | | .DESCRIPTION |
| | | 5 | | Provides a PowerShell-friendly wrapper for constructing CookieBuilder objects with strongly-typed |
| | | 6 | | properties commonly used when configuring cookie authentication. All parameters are optional; any |
| | | 7 | | not supplied retain the underlying default from CookieBuilder / ASP.NET Core. |
| | | 8 | | This helper simplifies scripts by avoiding direct new() object + property assignment sequences. |
| | | 9 | | .PARAMETER Name |
| | | 10 | | The name of the cookie. If not specified, a framework default may be used by the consumer. |
| | | 11 | | .PARAMETER Domain |
| | | 12 | | The domain to associate the cookie with. If not specified, the cookie is associated with the host of the request. |
| | | 13 | | .PARAMETER Path |
| | | 14 | | The path to associate the cookie with. If not specified, the cookie is associated with the root path ('/'). |
| | | 15 | | .PARAMETER HttpOnly |
| | | 16 | | Indicates whether a cookie is inaccessible by client-side script but specific components may use a different value. |
| | | 17 | | .PARAMETER IsEssential |
| | | 18 | | Indicates if this cookie is essential for the application to function correctly. If true then |
| | | 19 | | consent policy checks may be bypassed.SameSiteMode Default is $false. |
| | | 20 | | .PARAMETER MaxAge |
| | | 21 | | The maximum age of the cookie. Accepts a TimeSpan or a value convertible to Time |
| | | 22 | | Span (e.g. string like '00:30:00' or integer seconds). If not specified, the cookie is a session cookie. |
| | | 23 | | .PARAMETER Expiration |
| | | 24 | | Alias for Expires; provided for convenience. Accepts the same types and conversion as Expires. |
| | | 25 | | .PARAMETER SecurePolicy |
| | | 26 | | The secure policy for the cookie. Accepts a value from the CookieSecurePolicy enum. |
| | | 27 | | If not specified, the default is CookieSecurePolicy.SameAsRequest. |
| | | 28 | | - SameAsRequest: Cookie is secure if the request is HTTPS; supports both HTTP and HTTPS for development. |
| | | 29 | | - Always: Cookie is always marked secure; use when all pages are served over HTTPS. |
| | | 30 | | - None: Cookie is never marked secure; not recommended due to potential security risks on HTTP connections. |
| | | 31 | | .PARAMETER SameSite |
| | | 32 | | The SameSite mode for the cookie. Accepts a value from the [Microsoft.AspNetCore.Http.SameSiteMode] enum: |
| | | 33 | | - Unspecified (-1): No SameSite field will be set; the client should follow its default cookie policy. |
| | | 34 | | - None (0): Indicates the client should disable same-site restrictions. |
| | | 35 | | - Lax: Indicates the client should send the cookie with "same-site" requests, and with "cross-site" top-level naviga |
| | | 36 | | - Strict: Indicates the client should only send the cookie with "same-site" requests. |
| | | 37 | | .PARAMETER Extensions |
| | | 38 | | Additional cookie attributes to append to the Set-Cookie header. Accepts an array of strings |
| | | 39 | | .PARAMETER WhatIf |
| | | 40 | | Shows what would happen if the command runs. The command is not run. |
| | | 41 | | .PARAMETER Confirm |
| | | 42 | | Prompts you for confirmation before running the command. The command is not run unless you respond affirmatively. |
| | | 43 | | .EXAMPLE |
| | | 44 | | # Basic cookie |
| | | 45 | | $cookie = New-KrCookieBuilder -Name 'AuthCookie' -HttpOnly -SameSite Lax |
| | | 46 | | .EXAMPLE |
| | | 47 | | # Full configuration |
| | | 48 | | $cookie = New-KrCookieBuilder -Name 'AuthCookie' -Domain 'example.local' -Path '/' -SecurePolicy Always \ |
| | | 49 | | -IsEssential -MaxAge (New-TimeSpan -Hours 1) -Expires (Get-Date).AddHours(1) -SameSite Strict -HttpOnly |
| | | 50 | | .OUTPUTS |
| | | 51 | | Microsoft.AspNetCore.Http.CookieBuilder |
| | | 52 | | |
| | | 53 | | .NOTES |
| | | 54 | | Setting both -MaxAge and -Expires is allowed; ASP.NET Core will honour both where applicable. |
| | | 55 | | If -Name is omitted a framework default may be used by the consumer. |
| | | 56 | | #> |
| | | 57 | | function New-KrCookieBuilder { |
| | | 58 | | [KestrunRuntimeApi('Definition')] |
| | | 59 | | [CmdletBinding(SupportsShouldProcess = $true, ConfirmImpact = 'Low')] |
| | | 60 | | [OutputType([Microsoft.AspNetCore.Http.CookieBuilder])] |
| | | 61 | | param( |
| | | 62 | | [Parameter()] [string]$Name, |
| | | 63 | | [Parameter()] [string]$Domain, |
| | | 64 | | [Parameter()] [string]$Path, |
| | | 65 | | [Parameter()] [switch]$HttpOnly, |
| | | 66 | | [Parameter()] [switch]$IsEssential, |
| | | 67 | | [Parameter()] [object]$MaxAge, |
| | | 68 | | [Parameter()] [object]$Expiration, |
| | | 69 | | [Parameter()] [Microsoft.AspNetCore.Http.CookieSecurePolicy]$SecurePolicy, |
| | | 70 | | [Parameter()] [Microsoft.AspNetCore.Http.SameSiteMode]$SameSite, |
| | | 71 | | [Parameter()] [string[]]$Extensions |
| | | 72 | | ) |
| | 0 | 73 | | $builder = [Microsoft.AspNetCore.Http.CookieBuilder]::new() |
| | | 74 | | |
| | 0 | 75 | | if ($PSBoundParameters.ContainsKey('Name')) { |
| | 0 | 76 | | $builder.Name = $Name |
| | | 77 | | } |
| | 0 | 78 | | if ($PSBoundParameters.ContainsKey('Domain')) { |
| | 0 | 79 | | $builder.Domain = $Domain |
| | | 80 | | } |
| | 0 | 81 | | if ($PSBoundParameters.ContainsKey('Path')) { |
| | 0 | 82 | | $builder.Path = $Path |
| | | 83 | | } |
| | 0 | 84 | | if ($HttpOnly.IsPresent) { |
| | 0 | 85 | | $builder.HttpOnly = $true |
| | | 86 | | } |
| | 0 | 87 | | if ($IsEssential.IsPresent) { |
| | 0 | 88 | | $builder.IsEssential = $true |
| | | 89 | | } |
| | 0 | 90 | | if ($PSBoundParameters.ContainsKey('MaxAge')) { |
| | 0 | 91 | | $builder.MaxAge = ConvertTo-TimeSpan -InputObject $MaxAge |
| | | 92 | | } |
| | 0 | 93 | | if ($PSBoundParameters.ContainsKey('Expiration')) { |
| | 0 | 94 | | $builder.Expiration = ConvertTo-TimeSpan -InputObject $Expiration |
| | | 95 | | } |
| | 0 | 96 | | if ($PSBoundParameters.ContainsKey('SecurePolicy')) { |
| | 0 | 97 | | $builder.SecurePolicy = $SecurePolicy |
| | | 98 | | } |
| | 0 | 99 | | if ($PSBoundParameters.ContainsKey('SameSite')) { |
| | 0 | 100 | | $builder.SameSite = $SameSite |
| | | 101 | | } |
| | 0 | 102 | | if ($PSBoundParameters.ContainsKey('Extensions')) { |
| | 0 | 103 | | $builder.Extensions.Clear() |
| | 0 | 104 | | $builder.Extensions.AddRange($Extensions) |
| | | 105 | | } |
| | | 106 | | |
| | 0 | 107 | | if ($PSCmdlet.ShouldProcess('CookieBuilder', 'Create')) { |
| | 0 | 108 | | return $builder |
| | | 109 | | } else { |
| | 0 | 110 | | return $null |
| | | 111 | | } |
| | | 112 | | } |