Merge pull request #681 from Badgerati/develop

v2.1.0

.gitignore

@@ -6,6 +6,7 @@ pode_modules/
 ps_modules/
 docs/[Ff]unctions/
 examples/state.json
+examples/issue-*
 pkg/
 
 

Dockerfile

@@ -1,4 +1,4 @@
-FROM mcr.microsoft.com/powershell:7.0.1-ubuntu-16.04
+FROM mcr.microsoft.com/powershell:7.1.1-ubuntu-18.04
 LABEL maintainer="Matthew Kelly (Badgerati)"
 RUN mkdir -p /usr/local/share/powershell/Modules/Pode
 COPY ./pkg/ /usr/local/share/powershell/Modules/Pode

LICENSE.txt

@@ -1,6 +1,6 @@
 The MIT License (MIT)
 
-Copyright (c) [2017-2020] [Matthew Kelly (Badgerati)]
+Copyright (c) [2017-2021] [Matthew Kelly (Badgerati)]
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

arm32.dockerfile

@@ -1,4 +1,4 @@
-FROM badgerati/ps-core:7.0.1-arm32
+FROM badgerati/ps-core:7.1.1-arm32
 LABEL maintainer="Matthew Kelly (Badgerati)"
 RUN mkdir -p /usr/local/share/powershell/Modules/Pode
 COPY ./pkg/ /usr/local/share/powershell/Modules/Pode

docs/Getting-Started/Installation.md

@@ -27,7 +27,7 @@ Install-Module -Name Pode
 [![Docker](https://img.shields.io/docker/stars/badgerati/pode.svg?label=Stars)](https://hub.docker.com/r/badgerati/pode/)
 [![Docker](https://img.shields.io/docker/pulls/badgerati/pode.svg?label=Pulls)](https://hub.docker.com/r/badgerati/pode/)
 
-Pode can run on *nix environments, therefore it only makes sense for there to be Docker images for you to use! The images use PowerShell Core on either an Ubuntu Xenial image (default), or an ARM32 image (for Raspberry Pis).
+Pode can run on *nix environments, therefore it only makes sense for there to be Docker images for you to use! The images use PowerShell v7.1.1 on either an Ubuntu Bionic image (default), or an ARM32 image (for Raspberry Pis).
 
 * To pull down the latest Pode image you can do:
 
@@ -36,7 +36,7 @@ Pode can run on *nix environments, therefore it only makes sense for there to be
 docker pull badgerati/pode:latest
 
 # or the following for a specific version:
-docker pull badgerati/pode:1.0.1
+docker pull badgerati/pode:2.1.0
 ```
 
 * To pull down the ARM32 Pode image you can do:
@@ -46,7 +46,7 @@ docker pull badgerati/pode:1.0.1
 docker pull badgerati/pode:latest-arm32
 
 # or the following for a specific version:
-docker pull badgerati/pode:1.0.1-arm32
+docker pull badgerati/pode:2.1.0-arm32
 ```
 
 Once pulled, you can [view here](../Docker) on how to use the image.
@@ -62,7 +62,7 @@ You can also get the Pode docker image from the GitHub Package Registry! The ima
 docker pull docker.pkg.github.com/badgerati/pode/pode:latest
 
 # or the following for a specific version:
-docker pull docker.pkg.github.com/badgerati/pode/pode:1.0.1
+docker pull docker.pkg.github.com/badgerati/pode/pode:2.1.0
 ```
 
 * To pull down the ARM32 Pode image you can do:
@@ -72,7 +72,7 @@ docker pull docker.pkg.github.com/badgerati/pode/pode:1.0.1
 docker pull docker.pkg.github.com/badgerati/pode/pode:latest-arm32
 
 # or the following for a specific version:
-docker pull docker.pkg.github.com/badgerati/pode/pode:1.0.1-arm32
+docker pull docker.pkg.github.com/badgerati/pode/pode:2.1.0-arm32
 ```
 
 Once pulled, you can [view here](../Docker) on how to use the image.

docs/Hosting/Docker.md

@@ -2,7 +2,7 @@
 
 Pode has a Docker image that you can use to host your server, for instructions on pulling these images you can [look here](../../Installation).
 
-The images use PowerShell Core on either an Ubuntu Xenial (default) or ARM32 image.
+The images use PowerShell v7.1.1 on either an Ubuntu Bionic (default) or ARM32 image.
 
 ## Images
 
@@ -11,7 +11,7 @@ The images use PowerShell Core on either an Ubuntu Xenial (default) or ARM32 ima
 
 ### Default
 
-The default Pode image is an Ubuntu Xenial image with PowerShell Core and Pode installed. An example of using this image in your Dockerfile could be as follows:
+The default Pode image is an Ubuntu Bionic image with PowerShell v7.1.1 and Pode installed. An example of using this image in your Dockerfile could be as follows:
 
 ```dockerfile
 # pull down the pode image

docs/Hosting/IIS.md

@@ -115,6 +115,7 @@ If the required header is missing, then Pode responds with a 401. The retrieved
 | Name | Type | Description |
 | ---- | ---- | ----------- |
 | UserType | string | Specifies if the user is a Domain or Local user |
+| Identity | System.Security.Principal.WindowsIdentity | Returns the WindowsIdentity which can be used for Impersonation |
 | AuthenticationType | string | Value is fixed to LDAP |
 | DistinguishedName | string | The distinguished name of the user |
 | Username | string | The user's username (without domain) |
@@ -127,6 +128,51 @@ If the required header is missing, then Pode responds with a 401. The retrieved
 !!! note
     If the authenticated user is a Local User, then the following properties will be empty: FQDN, Email, and DistinguishedName
 
+### Kerberos Constrained Delegation
+
+Pode can impersonate the user that requests the webpage using Kerberos Constrained Delegation (KCD).
+
+Requirements
+- The use of KCD requires additional configuration in the Active Directory (read up on PrincipalsAllowedToDelegateToAccount)
+- No Session Middleware configured
+
+This can be done using the following example:
+
+```powershell
+[System.Security.Principal.WindowsIdentity]::RunImpersonated($WebEvent.Auth.User.Identity.AccessToken,{
+    $newIdentity = [Security.Principal.WindowsIdentity]::GetCurrent() | Select-Object -ExpandProperty 'Name'    
+    Write-PodeTextResponse -Value "You are running this command as the server user $newIdentity"
+})
+```
+
+
+### Additional Validation
+
+Similar to the normal [`Add-PodeAuth`](../../Functions/Authentication/Add-PodeAuth), [`Add-PodeAuthIIS`](../../Functions/Authentication/Add-PodeAuthIIS) can be supplied can an optional ScriptBlock parameter. This ScriptBlock is supplied the found User object as a parameter, structured as details above. You can then use this to further check the user, or load additional user information from another storage.
+
+The ScriptBlock has the same return rules as [`Add-PodeAuth`](../../Functions/Authentication/Add-PodeAuth), as can be seen in the [Overview](../../Tutorials/Authentication/Overview).
+
+For example, to return the user back:
+
+```powershell
+Add-PodeAuthIIS -Name 'IISAuth' -Sessionless -ScriptBlock {
+    param($user)
+
+    # check or load extra data
+
+    return @{ User = $user }
+}
+```
+
+Or to fail authentication with an error message:
+
+```powershell
+Add-PodeAuthIIS -Name 'IISAuth' -Sessionless -ScriptBlock {
+    param($user)
+    return @{ Message = 'Authorisation failed' }
+}
+```
+
 ## Azure Web Apps
 
 To host your Pode server under IIS using Azure Web Apps, ensure the OS type is Windows and the framework is .NET Core 2.1/3.0.

docs/Tutorials/Authentication/Inbuilt/UserFile.md

@@ -97,8 +97,35 @@ You can supply a list of authorised usernames to validate a user's access, after
 
 ```powershell
 Start-PodeServer {
-    New-PodeAuthScheme -Form | Add-PodeAuthWindowsAd -Name 'Login' -Users @('jsnow', 'rsanchez')
+    New-PodeAuthScheme -Form | Add-PodeAuthUserFile -Name 'Login' -Users @('jsnow', 'rsanchez')
 }
 ```
 
 If an user being authenticated is not one of the allowed users, then a 401 is returned.
+
+### Additional Validation
+
+Similar to the normal [`Add-PodeAuth`](../../../../Functions/Authentication/Add-PodeAuth), [`Add-PodeAuthUserFile`](../../../../Functions/Authentication/Add-PodeAuthUserFile) can be supplied can an optional ScriptBlock parameter. This ScriptBlock is supplied the found User object as a parameter, structured as details above. You can then use this to further check the user, or load additional user information from another storage.
+
+The ScriptBlock has the same return rules as [`Add-PodeAuth`](../../../../Functions/Authentication/Add-PodeAuth), as can be seen in the [Overview](../../Overview).
+
+For example, to return the user back:
+
+```powershell
+New-PodeAuthScheme -Form | Add-PodeAuthUserFile -Name 'Login' -ScriptBlock {
+    param($user)
+
+    # check or load extra data
+
+    return @{ User = $user }
+}
+```
+
+Or to fail authentication with an error message:
+
+```powershell
+New-PodeAuthScheme -Form | Add-PodeAuthUserFile -Name 'Login' -ScriptBlock {
+    param($user)
+    return @{ Message = 'Authorisation failed' }
+}
+```

docs/Tutorials/Authentication/Inbuilt/WindowsAD.md

@@ -71,3 +71,30 @@ Start-PodeServer {
 ```
 
 If an user being authenticated is not one of the allowed users, then a 401 is returned.
+
+### Additional Validation
+
+Similar to the normal [`Add-PodeAuth`](../../../../Functions/Authentication/Add-PodeAuth), [`Add-PodeAuthWindowsAd`](../../../../Functions/Authentication/Add-PodeAuthWindowsAd) can be supplied can an optional ScriptBlock parameter. This ScriptBlock is supplied the found User object as a parameter, structured as details above. You can then use this to further check the user, or load additional user information from another storage.
+
+The ScriptBlock has the same return rules as [`Add-PodeAuth`](../../../../Functions/Authentication/Add-PodeAuth), as can be seen in the [Overview](../../Overview).
+
+For example, to return the user back:
+
+```powershell
+New-PodeAuthScheme -Form | Add-PodeAuthWindowsAd -Name 'Login' -ScriptBlock {
+    param($user)
+
+    # check or load extra data
+
+    return @{ User = $user }
+}
+```
+
+Or to fail authentication with an error message:
+
+```powershell
+New-PodeAuthScheme -Form | Add-PodeAuthWindowsAd -Name 'Login' -ScriptBlock {
+    param($user)
+    return @{ Message = 'Authorisation failed' }
+}
+```

docs/Tutorials/Authentication/Inbuilt/WindowsLocal.md

@@ -59,3 +59,30 @@ Start-PodeServer {
 ```
 
 If an user being authenticated is not one of the allowed users, then a 401 is returned.
+
+### Additional Validation
+
+Similar to the normal [`Add-PodeAuth`](../../../../Functions/Authentication/Add-PodeAuth), [`Add-PodeAuthWindowsLocal`](../../../../Functions/Authentication/Add-PodeAuthWindowsLocal) can be supplied can an optional ScriptBlock parameter. This ScriptBlock is supplied the found User object as a parameter, structured as details above. You can then use this to further check the user, or load additional user information from another storage.
+
+The ScriptBlock has the same return rules as [`Add-PodeAuth`](../../../../Functions/Authentication/Add-PodeAuth), as can be seen in the [Overview](../../Overview).
+
+For example, to return the user back:
+
+```powershell
+New-PodeAuthScheme -Form | Add-PodeAuthWindowsLocal -Name 'Login' -ScriptBlock {
+    param($user)
+
+    # check or load extra data
+
+    return @{ User = $user }
+}
+```
+
+Or to fail authentication with an error message:
+
+```powershell
+New-PodeAuthScheme -Form | Add-PodeAuthWindowsLocal -Name 'Login' -ScriptBlock {
+    param($user)
+    return @{ Message = 'Authorisation failed' }
+}
+```

docs/Tutorials/Authentication/Methods/AzureAD.md

@@ -62,6 +62,38 @@ Start-PodeServer {
 }
 ```
 
+## Requests using Basic Authentication
+
+To authenticate against Azure Active Directory with Applications that do not support Modern Authentication (for example PowerShell Invoke-RestMethod), you will need to use Basic Authentication.
+This method only works if you're either using Password Hash Sync (PHS), Pass-through Authentication (PTA) or both. If you're using claim based authentication against another IdP like Active Directory Federation Services (ADFS) then this will not work as the Azure AD does not know the users' credentials.
+
+The client side may look like this:
+
+```powershell
+$res = Invoke-RestMethod -Url 'http://localhost:8080' -SessionVariable session
+$res.Form[0].username = 'username'
+$res.Form[0].password = 'password'
+Invoke-RestMethod -Url 'http://localhost:8080' -WebSession $session -Body $res.Form[0]
+```
+
+The Pode side needs to be configured to allow basic authentication as well. This can be done side by side with Form based Authentication using this example
+
+```powershell
+$form  = New-PodeAuthScheme -Form
+$schemeForm = New-PodeAuthAzureADScheme -ClientID '<clientId>' -ClientSecret '<clientSecret>' -Tenant '<tenant>' -InnerScheme $form
+
+$basic = New-PodeAuthSceme -Basic
+$schemeBasic = New-PodeAuthAzureADScheme -ClientID '<clientId>' -ClientSecret '<clientSecret>' -Tenant '<tenant>' -InnerScheme $basic
+
+$authLogin = {
+    param($user, $accessToken, $refreshToken)
+    # check user
+}
+
+$schemeForm | Add-PodeAuth -Name 'LoginForm' -FailureUrl '/login' -SuccessUrl '/' -ScriptBlock $authLogic
+$schemeBasic | Add-PodeAuth -Name 'LoginBasic' -ScriptBlock $authLogic
+```
+
 ## Middleware
 
 Once configured you can start using Azure AD Authentication to validate incoming Requests. You can either configure the validation to happen on every Route as global Middleware, or as custom Route Middleware.

docs/release-notes.md

@@ -1,5 +1,32 @@
 # Release Notes
 
+## v2.1.0
+
+```plain
+### Enhancements
+* #655: Update the Socket Listener to handle larger request payloads, and fix receiving SSL requests
+* #657: Adds `-ScriptBlock` parameters to inbuilt authentication methods
+* #667: Set the WinIdentity from IIS auth, and add documentation for Kerberos Constrained Delegation (thanks @RobinBeismann!)
+
+### Bugs
+* #648: Fixes for using global authentcation in OpenAPI and Swagger
+* #650: Fix for redirecting HTTP to HTTPS on default 80/443 ports
+* #652: Fix for sessions not extending from AJAX requests, or when session data wasn't updated
+* #654: Fix for `-Title` and `-Version` in `Get-PodeOpenApiDefinition` being mandatory
+* #660: Fix for removing cookies in AJAX responses
+* #663: Fix for when an endpoint's `-Hostname` is localhost, and bound to a route
+* #669: Further fixes and improvements for more `-EndpointName` validation use-cases on routes
+* #670: Remove extra NewLine from form files (thanks @ili101!)
+* #673: Fix to make headers in request/response case-insensitive
+
+### Documentation
+* #651: Update Azure AD authentication documentation to reference using Basic authentication as well (thanks @RobinBeismann)
+
+### Packaging
+* #629: Update dockerfile to use Ubuntu 18.04
+* #630: Update dockerfiles to use PowerShell 7.1.1
+```
+
 ## v2.0.3
 
 ```plain

examples/web-pages-simple.ps1

@@ -0,0 +1,30 @@
+param (
+    [int]
+    $Port = 8085
+)
+
+$path = Split-Path -Parent -Path (Split-Path -Parent -Path $MyInvocation.MyCommand.Path)
+Import-Module "$($path)/src/Pode.psm1" -Force -ErrorAction Stop
+
+# or just:
+# Import-Module Pode
+
+# create a server, and start listening on port 8085
+Start-PodeServer -Threads 2 {
+
+    # listen on localhost:8085
+    Add-PodeEndpoint -Address * -Port 8090 -Protocol Http -Name '8090Address'
+    Add-PodeEndpoint -Address * -Port $Port -Protocol Http -Name '8085Address' -RedirectTo '8090Address'
+
+    # log errors to the terminal
+    # New-PodeLoggingMethod -Terminal | Enable-PodeErrorLogging
+
+    # set view engine to pode renderer
+    Set-PodeViewEngine -Type Pode
+
+    # GET request for web page on "localhost:8085/"
+    Add-PodeRoute -Method Get -Path '/' -ScriptBlock {
+        Write-PodeViewResponse -Path 'simple' -Data @{ 'numbers' = @(1, 2, 3); }
+    }
+
+}

examples/web-rest-openapi-shared.ps1

@@ -13,13 +13,20 @@ Start-PodeServer {
 
 
     New-PodeAuthScheme -Basic | Add-PodeAuth -Name 'Validate' -Sessionless -ScriptBlock {
-        return @{
-            User = @{
-                ID ='M0R7Y302'
-                Name = 'Morty'
-                Type = 'Human'
+        param($username, $password)
+
+        # here you'd check a real user storage, this is just for example
+        if ($username -eq 'morty' -and $password -eq 'pickle') {
+            return @{
+                User = @{
+                    ID ='M0R7Y302'
+                    Name = 'Morty'
+                    Type = 'Human'
+                }
             }
         }
+
+        return @{ Message = 'Invalid details supplied' }
     }
 
 

examples/web-route-protocols.ps1

@@ -9,7 +9,7 @@ Start-PodeServer {
 
     # listen on localhost:8080/8443
     Add-PodeEndpoint -Address * -Port 8080 -Protocol Http -Name Endpoint1
-    Add-PodeEndpoint -Address * -Port 8443 -Protocol Https -Name Endpoint2
+    Add-PodeEndpoint -Address * -Port 8443 -Protocol Https -Name Endpoint2 -SelfSigned
 
     # set view engine to pode
     Set-PodeViewEngine -Type Pode
@@ -30,7 +30,7 @@ Start-PodeServer {
     }
 
     # ALL requests for http only to redirect to https
-    Add-PodeRoute -Method * -Path * -EndpointName Endpoint1 {
+    Add-PodeRoute -Method * -Path * -EndpointName Endpoint1 -ScriptBlock {
         Move-PodeResponseUrl -Protocol Https -Port 8443
     }