Merge pull request #930 from Badgerati/develop

v2.6.0

.github/CONTRIBUTING.md

@@ -39,13 +39,13 @@ If you have a question, feel free to either ask it on [GitHub Issues](https://gi
 
 ## About Pode
 
-Pode is a PowerShell framework/web server. The aim is to make it purely PowerShell, with *no* external dependencies - other than what is available in .NET Core. This allows Pode to be very lightweight, and just work out-of-the-box when the module is installed on any platform.
+Pode is a PowerShell framework/web server. The aim is to make it purely PowerShell, with *no* external dependencies - other than what is available in .NET. This allows Pode to be very lightweight, and just work out-of-the-box when the module is installed on any platform.
 
-The only current exception to the "all PowerShell" rule is the socket listener Pode uses. This listener is a part of Pode, but is written in .NET Core.
+The only current exception to the "all PowerShell" rule is the socket listener Pode uses. This listener is a part of Pode, but is written in .NET.
 
 ## How to Contribute
 
-When contributing, please try and raise an issue first before working on the issue. This allows us, and other people, to comment and help. If you raise an issue that you're intending on doing yourself, please state this within the issue - to above somebody else picking the issue up.
+When contributing, please try and raise an issue first before working on the issue. This allows us, and other people, to comment and help. If you raise an issue that you're intending on doing yourself, please state this within the issue - to avoid somebody else picking the issue up.
 
 ### Issues
 
@@ -105,6 +105,10 @@ To see the docs you'll need to have the [`Invoke-Build`](https://github.com/nigh
 Invoke-Build Docs
 ```
 
+### Importing
+
+When editing Pode and you need to import the local dev module for testing, you will need to import the `Pode.psm1` in the `/src` directory. This is the same as importing Pode's `.psd1` file, but will avoid errors for an invalid version number.
+
 ## Styleguide
 
 ### Code

.github/workflows/ci.yml

@@ -20,7 +20,12 @@ jobs:
         os: [ubuntu-latest, windows-latest, macOS-latest]
 
     steps:
-    - uses: actions/checkout@v1
+    - uses: actions/checkout@v2
+
+    - name: Setup .NET
+      uses: actions/setup-dotnet@v1.9.0
+      with:
+        dotnet-version: 6.0.x
 
     - name: Install Invoke-Build
       shell: pwsh

README.md

@@ -81,7 +81,7 @@ docker pull badgerati/pode
 
 Pull Requests, Bug Reports and Feature Requests are welcome! Feel free to help out with Issues and Projects!
 
-To run the unit tests, run the following command from the root of the repository (this will build Pode and, if needed, auto-install Pester/.NET Core):
+To run the unit tests, run the following command from the root of the repository (this will build Pode and, if needed, auto-install Pester/.NET):
 
 ```powershell
 Invoke-Build Test

docs/Listeners/Pode.md

@@ -1,3 +1,3 @@
 # Pode
 
-Pode has an inbuilt .NET Core socket listener that is used by default. You don't need to do anything special outside of using Pode normally. Pode's default listener supports HTTP/HTTPS, WS/WSS, SMTP and TCP.
+Pode has an inbuilt .NET cross-platform socket listener that is used by default. You don't need to do anything special outside of using Pode normally. Pode's default listener supports HTTP/HTTPS, WS/WSS, SMTP and TCP.

docs/Tutorials/Authentication/Methods/AzureAD.md → docs/Tutorials/Authentication/Inbuilt/AzureAD.md

@@ -2,7 +2,7 @@
 
 The Azure AD authentication is just a wrapper around the inbuilt [OAuth2](../OAuth2) authentication.
 
-Both the `authorization_code` and `password` grant types are supported. The `password` type is only supported on Work/School accounts, and on accounts with MFA disabled.
+Both the `authorization_code` and `password` grant types are supported. The `password` type is only supported on Work/School accounts, and on accounts with MFA disabled. There is also support for PKCE, via `-UsePKCE` if sessions are enabled.
 
 ## Setup
 
@@ -11,7 +11,8 @@ Before using Azure AD authentication in Pode, you first need to register a new a
 * In the Azure Portal, open up the Azure Active Directory
 * Then select "App Registrations" in the menu, followed by "New Registration" at the top
 * Enter a name for the app, followed by the redirect URL
-    * the default is redirect is `<host>/oauth2/callback` (such as `http://localhost:8080/oauth2/callback`)
+    * Platform should be "Web"
+    * The default redirect is `<host>/oauth2/callback` (such as `http://localhost:8080/oauth2/callback`)
 * Click create
     * Make a note of the "Client ID" and "Tenant"
 * Then select "Certificates & Secrets"
@@ -20,6 +21,20 @@ Before using Azure AD authentication in Pode, you first need to register a new a
 
 With the Client and Tenant ID, plus the Client Secret, you can now setup Azure AD authentication in Pode.
 
+### PKCE
+
+If you're using PKCE, then the flow changes a little bit:
+
+* In the Azure Portal, open up the Azure Active Directory
+* Then select "App Registrations" in the menu, followed by "New Registration" at the top
+* Enter a name for the app, followed by the redirect URL
+    * Platform should be "Single-page application"
+    * The default redirect is `<host>/oauth2/callback` (such as `http://localhost:8080/oauth2/callback`)
+* Click create
+    * Make a note of the "Client ID" and "Tenant"
+
+With just the Client and Tenant ID you're good to go; PKCE doesn't require a Client Secret to work.
+
 ### Authorisation Code
 
 To setup and start using Azure AD authentication in Pode you use `New-PodeAuthAzureADScheme`, and then pipe this into the [`Add-PodeAuth`](../../../../Functions/Authentication/Add-PodeAuth) function:

docs/Tutorials/Authentication/Inbuilt/Twitter.md

@@ -0,0 +1,116 @@
+# Twitter
+
+The Twitter authentication is just a wrapper around the inbuilt [OAuth2](../OAuth2) authentication.
+
+Only the `authorization_code` grant type is supported, and there's also support for PKCE, via `-UsePKCE` if sessions are enabled.
+
+## Setup
+
+Before using Twitter authentication in Pode, you first need to register a new app within Twitter:
+
+* Make sure to have a Twitter Developer account, and open the Developer Portal
+* Create a new, or select an existing app
+* In the app's settings, select "Edit" on OAuth2 under "User authentication settings"
+    * Enable "OAuth 2.0"
+    * Set the Type of App to "Web App"
+    * The default redirect is `<host>/oauth2/callback` (such as `http://localhost:8080/oauth2/callback`)
+    * Enter some Website URL
+    * Click "Save"
+* Make a note of the Client ID and Secret presented
+
+With the Client ID and Secret, you can now setup Twitter authentication in Pode.
+
+### PKCE
+
+If you're using PKCE, then the flow changes a little bit:
+
+* Make sure to have a Twitter Developer account, and open the Developer Portal
+* Create a new, or select an existing app
+* In the app's settings, select "Edit" on OAuth2 under "User authentication settings"
+    * Enable "OAuth 2.0"
+    * Set the Type of App to "Single page App"
+    * The default redirect is `<host>/oauth2/callback` (such as `http://localhost:8080/oauth2/callback`)
+    * Enter some Website URL
+    * Click "Save"
+* Make a note of the Client ID presented
+
+With just the Client ID you're good to go; PKCE doesn't require a Client Secret to work.
+
+### Authorisation Code
+
+To setup and start using Twitter authentication in Pode you use `New-PodeAuthTwitterScheme`, and then pipe this into the [`Add-PodeAuth`](../../../../Functions/Authentication/Add-PodeAuth) function:
+
+```powershell
+Start-PodeServer {
+    $scheme = New-PodeAuthTwitterScheme -ClientID '<clientId>' -ClientSecret '<clientSecret>'
+
+    $scheme | Add-PodeAuth -Name 'Login' -FailureUrl '/login' -SuccessUrl '/' -ScriptBlock {
+        param($user, $accessToken, $refreshToken, $response)
+
+        # check if the user is valid
+
+        return @{ User = $user.data }
+    }
+}
+```
+
+If you don't specify a `-RedirectUrl`, then an internal default one is created as `/oauth2/callback` on the first endpoint.
+
+When a user accesses your site unauthenticated, they will be to Twitter to login and approve your app, and then redirected back to your site.
+
+## Middleware
+
+Once configured you can start using Twitter Authentication to validate incoming Requests. You can either configure the validation to happen on every Route as global Middleware, or as custom Route Middleware.
+
+The following will use Twitter Authentication to validate every request on every Route:
+
+```powershell
+Start-PodeServer {
+    Add-PodeAuthMiddleware -Name 'GlobalAuthValidation' -Authentication 'Login'
+}
+```
+
+Whereas the following example will use Twitter Authentication to only validate requests on specific a Route:
+
+```powershell
+Start-PodeServer {
+    Add-PodeRoute -Method Get -Path '/about' -Authentication 'Login' -ScriptBlock {
+        # logic
+    }
+}
+```
+
+## Full Example
+
+The following full example of Twitter authentication. This will setup and configure authentication, redirect a user to Twitter for validation and approval, and then validate on a specific Route:
+
+```powershell
+Start-PodeServer {
+    Add-PodeEndpoint -Address * -Port 8080 -Protocol Http
+    Set-PodeViewEngine -Type Pode
+
+    # setup authentication to validate a user
+    $scheme = New-PodeAuthTwitterScheme -ClientID '<clientId>' -ClientSecret '<clientSecret>'
+
+    $scheme | Add-PodeAuth -Name 'Login' -FailureUrl '/login' -SuccessUrl '/' -ScriptBlock {
+        param($user, $accessToken, $refreshToken, $response)
+
+        # check if the user is valid
+
+        return @{ User = $user.data }
+    }
+
+    # home page:
+    # redirects to login page if not authenticated
+    Add-PodeRoute -Method Get -Path '/' -Authentication Login -ScriptBlock {
+        Write-PodeViewResponse -Path 'home' -Data @{ Username = $WebEvent.Auth.User.name }
+    }
+
+    # login - this will just redirect to twitter
+    # NOTE: you do not need the -Login switch
+    Add-PodeRoute -Method Get -Path '/login' -Authentication Login
+
+    # logout
+    Add-PodeRoute -Method Post -Path '/logout' -Authentication Login -Logout
+}
+```

docs/Tutorials/Authentication/Methods/OAuth2.md

@@ -1,12 +1,12 @@
-# OAuth2
+# OAuth 2.0 & OIDC
 
-The OAuth2 authentication lets you setup authentication with other services that support OAuth2.
+The OAuth2 authentication lets you setup authentication with services that support OAuth 2.0.
 
-To use this scheme, you'll need to supply an Authorise/Token URL, as well as setup a app registration to acquire a Client ID and Secret.
+To use this scheme, you'll need to supply an Authorise/Token URL, as well as setup a app registration to acquire a Client ID and Secret. There is also support for converting an OpenID Connect Discovery URL to a Pode OAuth2 scheme.
 
 ## Setup
 
-Before using the OAuth2 authentication in Pode, you first need to register a new app within your service of choice. This registration will supply you with the required Client ID and Secret.
+Before using the OAuth2 authentication in Pode, you first need to register a new app within your service of choice. This registration will supply you with the required Client ID and Secret (if you're using [PKCE](#PKCE) then the Client Secret is optional).
 
 To setup and start using OAuth2 authentication in Pode you use `New-PodeAuthScheme -OAuth2`, and then pipe this into the [`Add-PodeAuth`](../../../../Functions/Authentication/Add-PodeAuth) function.
 
@@ -103,6 +103,34 @@ Add-PodeRoute -Method Get -Path '/login' -Authentication Login -Login -ScriptBlo
 Add-PodeRoute -Method Post -Path '/login' -Authentication Login -Login
 ```
 
+## PKCE
+
+!!! important
+    When using PKCE, you will need to enable the use of [sessions](../../../Middleware/Types/Sessions) in Pode.
+
+If your app is setup as a "Single Page Application" then you'll be able to use PKCE in your OAuth2 requests. To enable Pode's OAuth2 authentication to use PKCE, supply the `-UsePKCE` switch:
+
+```powershell
+Start-PodeServer {
+    $scheme = New-PodeAuthScheme `
+        -OAuth2 `
+        -ClientID '<clientId>' `
+        -AuthoriseUrl 'https://some-service.com/oauth2/authorize' `
+        -TokenUrl 'https://some-service.com/oauth2/token' `
+        -UsePKCE
+
+    $scheme | Add-PodeAuth -Name 'Login' -FailureUrl '/login' -SuccessUrl '/' -ScriptBlock {
+        param($user, $accessToken, $refreshToken, $response)
+
+        # check if the user is valid
+
+        return @{ User = $user }
+    }
+}
+```
+
+When using PKCE the `-ClientSecret` is optional, and doesn't need to be supplied.
+
 ## Middleware
 
 Once configured you can start using the OAuth2 Authentication to validate incoming Requests. You can either configure the validation to happen on every Route as global Middleware, or as custom Route Middleware.
@@ -125,6 +153,26 @@ Start-PodeServer {
 }
 ```
 
+## OIDC Discovery
+
+If the provider you're wanting to use OAuth2 for supports OpenID Connect Discovery, and has an appropriate `/.well-known/openid-configuration` endpoint, then you can use this with [`ConvertFrom-PodeOIDCDiscovery`](../../../../Functions/Authentication/ConvertFrom-PodeOIDCDiscovery) to automatically build a Pode OAuth2 scheme.
+
+For example, if you were using Google OAuth2 with PKCE, then the following example would build an OAuth2 scheme:
+
+```powershell
+$scheme = ConvertFrom-PodeOIDCDiscovery -Url 'https://accounts.google.com' -ClientId '<client_id>' -UsePKCE
+
+$scheme | Add-PodeAuth -Name 'Login' -FailureUrl '/login' -SuccessUrl '/' -ScriptBlock {
+    param($user, $accessToken, $refreshToken, $response)
+
+    # check if the user is valid
+
+    return @{ User = $user }
+}
+```
+
+If the `-Url` supplied doesn't end with `/.well-known/openid-configuration`, then Pode will append it to the URL automatically.
+
 ## Full Example
 
 The following is an example of OAuth2 authentication usin the `authorization_code` grant type. This will setup and configure authentication, redirect a user to some service for validation, and then validate on a specific Route:

docs/Tutorials/Metrics/Requests.md

@@ -52,8 +52,14 @@ $code = (Get-PodeRoute -Method Get -Path '/about').Metrics.Requests.StatusCodes[
 
 ## Active
 
-You can retrieve the current count of active requests by using [`Get-PodeServerActiveRequestMetric`](../../../Functions/Metrics/Get-PodeServerActiveRequestMetric). Active requests are ones that are queued internally, ready to be processed:
+You can retrieve the current count of active requests by using [`Get-PodeServerActiveRequestMetric`](../../../Functions/Metrics/Get-PodeServerActiveRequestMetric). Active requests are ones that are queued, or are currently being processed:
 
 ```powershell
 $activeReqs = Get-PodeServerActiveRequestMetric
 ```
+
+The default is to return the count of all requests, but you can filter a count of queued or processing via `-CountType`:
+
+```powershell
+$queuedReqs = Get-PodeServerActiveRequestMetric -CountType Queued
+```

docs/Tutorials/Middleware/Overview.md

@@ -88,15 +88,17 @@ Although you can define your own custom middleware, Pode does have some inbuilt
 
 | Order | Middleware | Description |
 | ----- | ---------- | ----------- |
-| 1 | **Access Rules** | Allowing/Denying IP addresses (if access rules have been defined) |
-| 2 | **Rate Limiting** | Limiting access to IP addresses (if rate limiting rules have been defined) |
-| 3 | **Static Content** | Static Content, such as images/css/js/html, in the `/public` directory |
-| 4 | **Body Parsing** | Parsing request payload as JSON, XML, or other types |
-| 5 | **Query String** | Getting any query string parameters currently on the request URL |
-| 6 | **Cookie Parsing** | Parse the cookies from the request's header (this only applies to serverless) |
-| 7 | **Custom Middleware** | Runs any defined user defined global Middleware in the order it was created |
-| 8 | **Route Middleware** | Runs any Route level Middleware for the current Route being processed |
-| 9 | **Route** | Finally, the route itself is processed |
+| 1 | **Security Headers** | Add any defined security headers onto the response |
+| 2 | **Access Rules** | Allowing/Denying IP addresses (if access rules have been defined) |
+| 3 | **Rate Limiting** | Limiting access to IP addresses (if rate limiting rules have been defined) |
+| 4 | **Static Content** | Static Content, such as images/css/js/html, in the `/public` directory |
+| 5 | **Body Parsing** | Parsing request payload as JSON, XML, or other types |
+| 6 | **Query String** | Getting any query string parameters currently on the request URL |
+| 7 | **Cookie Parsing** | Parse the cookies from the request's header (this only applies to serverless) |
+| 8 | **Custom Middleware** | Runs any defined user defined global Middleware in the order it was created |
+| 9 | **Route Middleware** | Runs any Route level Middleware for the current Route being processed |
+| 10 | **Route** | Then, the route itself is processed |
+| 11 | **Endware** | Finally, any Endware configured is run |
 
 ## Overriding Inbuilt
 
@@ -108,6 +110,7 @@ Pode has inbuilt Middleware as defined in the order of running above. Sometimes
 * Body Parsing      - `__pode_mw_body_parsing__`
 * Query String      - `__pode_mw_query_parsing__`
 * Cookie Parsing    - `__pode_mw_cookie_parsing__`
+* Security Headers  - `__pode_mw_security__`
 
 The following example uses rate limiting, and defines Middleware that will override the inbuilt rate limiting logic: