Merge pull request #1176 from Badgerati/develop

v2.9.0

Author: Badgerati

.github/CONTRIBUTING.md

@@ -6,30 +6,34 @@ The following is a set of guidelines for contributing to Pode on GitHub. These a
 
 ## Table of Contents
 
-* [Code of Conduct](#code-of-conduct)
-* [I just have a Question](#i-just-have-a-question)
-* [About Pode](#about-pode)
-* [How to Contribute](#how-to-contribute)
-  * [Issues](#issues)
-  * [Branch Names](#branch-names)
-  * [Pull Requests](#pull-requests)
-  * [Building](#building)
-  * [Testing](#testing)
-  * [Documentation](#documentation)
-* [Styleguide](#styleguide)
-  * [Code](#code)
-  * [Comments](#comments)
-    * [General](#general)
-    * [Help](#help)
-  * [PowerShell Commandlets](#powershell-commandlets)
-    * [Foreach-Object](#foreach-object)
-    * [Where-Object](#where-object)
-    * [Select-Object](#select-object)
-    * [Measure-Object](#measure-object)
+- [Contributing to Pode](#contributing-to-pode)
+  - [Table of Contents](#table-of-contents)
+  - [Code of Conduct](#code-of-conduct)
+  - [I just have a Question](#i-just-have-a-question)
+  - [About Pode](#about-pode)
+  - [How to Contribute](#how-to-contribute)
+    - [Issues](#issues)
+    - [Branch Names](#branch-names)
+    - [Pull Requests](#pull-requests)
+    - [Building](#building)
+    - [Testing](#testing)
+    - [Documentation](#documentation)
+    - [Importing](#importing)
+  - [Styleguide](#styleguide)
+    - [Editor](#editor)
+    - [Code](#code)
+    - [Comments](#comments)
+      - [General](#general)
+      - [Help](#help)
+    - [PowerShell Commandlets](#powershell-commandlets)
+      - [Foreach-Object](#foreach-object)
+      - [Where-Object](#where-object)
+      - [Select-Object](#select-object)
+      - [Measure-Object](#measure-object)
 
 ## Code of Conduct
 
-This project and everyone participating in it is governed by the Pode's [Code of Conduct](../.github/CODE_OF_CONDUCT.md). By participating, you are expected to uphold this code.
+This project, and everyone participating in it, is governed by the Pode's [Code of Conduct](../.github/CODE_OF_CONDUCT.md). By participating, you are expected to uphold this code.
 
 ## I just have a Question
 
@@ -111,22 +115,20 @@ When editing Pode and you need to import the local dev module for testing, you w
 
 ## Styleguide
 
+### Editor
+
+You can use whatever editor you like, but it's recommended to use Visual Studio Code. To help with this style guide, specifically for PowerShell, Pode has code formatting workspace setting which will automatically format the files on save.
+
 ### Code
 
 In general, observe the coding style used within the file/project and mimic that as best as you can. Some standards that are typical are:
 
-* Bracers (`{}`) on the function header should be on a new line, such as:
+* Bracers  (`{}`) should be on the same line of the statement they following, such as `function`, `foreach`, `if`, etc.
 ```powershell
-function Add-Something
-{
-    # logic
-}
-```
-
-* Bracers  (`{}`) should be on the same line of other calls, such as `foreach`, `if`, etc.
-```powershell
-foreach ($item in $items) {
-    # logic
+function Add-Something {
+    foreach ($item in $items) {
+        # logic
+    }
 }
 ```
 
@@ -135,8 +137,7 @@ foreach ($item in $items) {
   * Ensure public functions always declare `[CmdletBinding()]` attribute.
   * Ensure parameter names, types, and attributes are declared on new lines - not all on one line.
 ```powershell
-function Add-Something
-{
+function Add-Something {
     [CmdletBinding()]
     param(
         [Parameter()]

.vscode/settings.json

@@ -0,0 +1,24 @@
+{
+    "editor.formatOnSave": true,
+    "editor.formatOnType": false,
+    "editor.minimap.enabled": false,
+    "powershell.codeFormatting.addWhitespaceAroundPipe": true,
+    "powershell.codeFormatting.alignPropertyValuePairs": true,
+    "powershell.codeFormatting.autoCorrectAliases": true,
+    "powershell.codeFormatting.avoidSemicolonsAsLineTerminators": true,
+    "powershell.codeFormatting.ignoreOneLineBlock": true,
+    "powershell.codeFormatting.pipelineIndentationStyle": "IncreaseIndentationForFirstPipeline",
+    "powershell.codeFormatting.trimWhitespaceAroundPipe": true,
+    "powershell.codeFormatting.useConstantStrings": true,
+    "powershell.codeFormatting.whitespaceBeforeOpenBrace": true,
+    "powershell.codeFormatting.whitespaceAroundOperator": true,
+    "powershell.codeFormatting.whitespaceAfterSeparator": true,
+    "powershell.codeFormatting.useCorrectCasing": false,
+    "powershell.codeFormatting.openBraceOnSameLine": true,
+    "powershell.codeFormatting.newLineAfterOpenBrace": true,
+    "powershell.codeFormatting.newLineAfterCloseBrace": true,
+    "powershell.codeFormatting.whitespaceBeforeOpenParen": true,
+    "powershell.codeFormatting.whitespaceBetweenParameters": false,
+    "powershell.codeFormatting.whitespaceInsideBrace": true,
+    "files.trimTrailingWhitespace": true
+}

README.md

@@ -67,6 +67,7 @@ Then navigate to `http://127.0.0.1:8000` in your browser.
 * Basic rate limiting for IP addresses and subnets
 * Middleware and Sessions on web servers, with Flash message and CSRF support
 * Authentication on requests, such as Basic, Windows and Azure AD
+* Authorisation support on requests, using Roles, Groups, Scopes, etc.
 * Support for dynamically building Routes from Functions and Modules
 * Generate/bind self-signed certificates
 * Secret management support to load secrets from vaults

alpine.dockerfile

@@ -1,4 +1,4 @@
-FROM mcr.microsoft.com/powershell:7.3-alpine-3.15
+FROM mcr.microsoft.com/powershell:7.3-alpine-3.17
 LABEL maintainer="Matthew Kelly (Badgerati)"
 RUN mkdir -p /usr/local/share/powershell/Modules/Pode
 COPY ./pkg/ /usr/local/share/powershell/Modules/Pode

arm32.dockerfile

@@ -1,4 +1,4 @@
-FROM mcr.microsoft.com/powershell:preview-7.3-arm32v7-ubuntu-18.04
+FROM mcr.microsoft.com/powershell:7.3-ubuntu-22.04-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/Migrating/0X-to-1X.md

@@ -186,7 +186,7 @@ There is a new [`New-PodeMiddleware`](../../../Functions/Middleware/New-PodeMidd
 
 ([Tutorial](../../../Tutorials/Middleware/Types/Sessions))
 
-The `session` function has now been replaced by the new [`Enable-PodeSessionMiddleware`](../../../Functions/Middleware/Enable-PodeSessionMiddleware) function. With the new function, not only will it automatically enabled session middleware for you, but the old `-Options` hashtable has now been converted into proper function parameters.
+The `session` function has now been replaced by the new [`Enable-PodeSessionMiddleware`](../../../Functions/Sessions/Enable-PodeSessionMiddleware) function. With the new function, not only will it automatically enabled session middleware for you, but the old `-Options` hashtable has now been converted into proper function parameters.
 
 ### CSRF
 

docs/Hosting/IIS.md

@@ -129,6 +129,10 @@ This allows you to write a Pode server that works locally, but will also automat
 !!! note
     This does mean that Pode will force all endpoints to `127.0.0.1:PORT`. So if you had two different IPs before, they'll be merged into one. Something to be aware of if you assign routes to specific endpoints, as under IIS this won't work.
 
+### Maximum Worker Processes
+
+Unless you're using an external data store for sessions, ensure the Maximum Worker Processes is 1. Each worker process will spawn a new instance of your Pode server, and if using Pode's inbuilt session storage you'll face authenticated/session timeout issues when one instance doesn't contain the right session.
+
 ### Advanced/Domain/Kerberos
 
 The above IIS site setup works, but only for simple sites. If you require the use of the Active Directory module, or your site to be running as a different user then follow the steps below.

docs/Tutorials/Authentication/Inbuilt/AzureAD.md

@@ -41,6 +41,8 @@ To setup and start using Azure AD authentication in Pode you use `New-PodeAuthAz
 
 ```powershell
 Start-PodeServer {
+    Enable-PodeSessionMiddleware -Duration 120 -Extend
+
     $scheme = New-PodeAuthAzureADScheme -ClientID '<clientId>' -ClientSecret '<clientSecret>' -Tenant '<tenant>'
 
     $scheme | Add-PodeAuth -Name 'Login' -FailureUrl '/login' -SuccessUrl '/' -ScriptBlock {
@@ -63,6 +65,8 @@ To setup Azure AD authentcation, but using your own Form login, then you can use
 
 ```powershell
 Start-PodeServer {
+    Enable-PodeSessionMiddleware -Duration 120 -Extend
+
     $form  = New-PodeAuthScheme -Form
 
     $scheme = New-PodeAuthAzureADScheme -ClientID '<clientId>' -ClientSecret '<clientSecret>' -Tenant '<tenant>' -InnerScheme $form
@@ -97,7 +101,7 @@ The Pode side needs to be configured to allow basic authentication as well. This
 $form  = New-PodeAuthScheme -Form
 $schemeForm = New-PodeAuthAzureADScheme -ClientID '<clientId>' -ClientSecret '<clientSecret>' -Tenant '<tenant>' -InnerScheme $form
 
-$basic = New-PodeAuthSceme -Basic
+$basic = New-PodeAuthScheme -Basic
 $schemeBasic = New-PodeAuthAzureADScheme -ClientID '<clientId>' -ClientSecret '<clientSecret>' -Tenant '<tenant>' -InnerScheme $basic
 
 $authLogin = {

docs/Tutorials/Authentication/Inbuilt/Session.md

@@ -0,0 +1,59 @@
+# Sessions
+
+Pode has support for Sessions when using Authentication, by default if you call a Route with authentication and you already have a session on the request then you're "authenticated". If there's no session, then the authentication logic is invoked, and if the details are invalid you're redirected to a login screen.
+
+If you have a need to use multiple authentication methods for login, and the user can chose the one they want, then on Routes there's no simple way of say which authentication is required. However, under the hood they all create a session object which can be used as a "shared" authentication method.
+
+This sessions authenticator can be used to pass authentication if a valid session in on the request, or to automatically redirect to a login page if there is no valid session. Useful for if you're using multiple authentication methods the user can choose from.
+
+## Usage
+
+To add sessions authentication you can use [`Add-PodeAuthSession`](../../../../Functions/Authentication/Add-PodeAuthSession). The following example will validate a user's credentials on login using Form authentication, but the home page uses session authentication to just verify there's a valid session:
+
+```powershell
+Start-PodeServer {
+    # endpoint and view engine
+    Add-PodeEndpoint -Address * -Port 8085 -Protocol Http
+    Set-PodeViewEngine -Type Pode
+
+    # enable sessions
+    Enable-PodeSessionMiddleware -Duration 120 -Extend
+
+    # setup form auth for login
+    New-PodeAuthScheme -Form | Add-PodeAuth -Name 'FormAuth' -FailureUrl '/login' -SuccessUrl '/' -ScriptBlock {
+        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 = @{ Name = 'Morty' } }
+        }
+
+        return @{ Message = 'Invalid details supplied' }
+    }
+
+    # setup session auth for routes and logout
+    Add-PodeAuthSession -Name 'SessionAuth' -FailureUrl '/login'
+
+    # home page: use session auth, and redirect to login if no valid session
+    Add-PodeRoute -Method Get -Path '/' -Authentication SessionAuth -ScriptBlock {
+        Write-PodeViewResponse -Path 'auth-home'
+    }
+
+    # login page: use form auth here to actually verify the user's credentials
+    Add-PodeRoute -Method Get -Path '/login' -Authentication FormAuth -Login -ScriptBlock {
+        Write-PodeViewResponse -Path 'auth-login' -FlashMessages
+    }
+
+    # login check: again, use form auth
+    Add-PodeRoute -Method Post -Path '/login' -Authentication FormAuth -Login
+
+    # logout - use session auth here to purge the session
+    Add-PodeRoute -Method Post -Path '/logout' -Authentication SessionAuth -Logout
+}
+```
+
+### User Object
+
+If a valid session is found on the request, then the user object set at `$WebEvent.Auth.User` will take the form of which ever authentication method using for login.
+
+The user object will simply be loaded from the session.

docs/Tutorials/Authentication/Inbuilt/UserFile.md

@@ -62,6 +62,7 @@ Start-PodeServer {
 Regardless of whether the password is a standard SHA256 hash or HMAC hash, the hashed output should be a base64 string. The following functions will return the hashed value in the expected format:
 
 **SHA256 HASH**:
+
 ```powershell
 function ConvertTo-SHA256([string]$String)
 {
@@ -73,6 +74,7 @@ function ConvertTo-SHA256([string]$String)
 ```
 
 **HMAC HASH:**
+
 ```powershell
 function ConvertTo-HMACSHA256([string]$String, [string]$Secret) {
     $HMACSHA256 = New-Object System.Security.Cryptography.HMACSHA256

docs/Tutorials/Authentication/Inbuilt/WindowsAD.md

@@ -149,3 +149,7 @@ New-PodeAuthScheme -Form | Add-PodeAuthWindowsAd -Name 'Login' -ScriptBlock {
     return @{ Message = 'Authorisation failed' }
 }
 ```
+
+## Protected Users
+
+In Windows AD there is a "Protected Users" group that you can assign users into. If users in this group are trying to use your site, then they will fail authentication. Unfortunately, this is just a secure feature of Windows AD, and the only way around this is to take the affected users out of the Protected Users group.

docs/Tutorials/Authentication/Methods/Bearer.md

@@ -12,7 +12,7 @@ To start using Bearer authentication in Pode you can use `New-PodeAuthScheme -Be
 
 ```powershell
 Start-PodeServer {
-    New-PodeAuthScheme -Bearer | Add-PodeAuth -Name 'Authenticate' -ScriptBlock {
+    New-PodeAuthScheme -Bearer | Add-PodeAuth -Name 'Authenticate' -Sessionless -ScriptBlock {
         param($token)
 
         # check if the token is valid, and get user