Skip to content

Commit

Permalink
Badgerati#314: Updates the docs for authentication
Browse files Browse the repository at this point in the history
  • Loading branch information
@Badgerati
Badgerati committed Jul 29, 2019
1 parent 5cc5737 commit 97a9eb7
Show file tree
Hide file tree
Showing 14 changed files with 472 additions and 377 deletions.
39 changes: 14 additions & 25 deletions docs/Tutorials/Authentication/Basic.md
View file
Original file line number Diff line number Diff line change
@@ -1,69 +1,65 @@
# Basic Authentication

Basic authentication is when you pass an encoded `username:password` value on the header of your requests: `@{ 'Authorization' = 'Basic <base64 encoded username:password>' }`.
Basic Authentication is when you pass an encoded `username:password` value on the header of your requests: `@{ 'Authorization' = 'Basic <base64 encoded username:password>' }`.

## Setup

To setup and start using Basic authentication in Pode you can call `auth use <name> -t basic` in your server script, the validator script you need to supply will have the username/password passed as arguments to the scriptblock:
To setup and start using Form Authentication in Pode you use the `New-PodeAuthType -Basic` function, and then pipe this into the `Add-PodeAuth` function:

```powershell
Start-PodeServer {
auth use login -t basic -v {
New-PodeAuthType -Basic | Add-PodeAuth -Name 'Login' -ScriptBlock {
param($username, $password)
# check if the user is valid
return @{ 'user' = $user }
return @{ User = $user }
}
}
```

By default, Pode will check if the request's header contains an `Authorization` key, and whether the value of that key starts with `Basic`. The `auth use` action can be supplied options via `-o` to override the start name of the value, as well as the encoding that Pode uses.
By default, Pode will check if the Request's header contains an `Authorization` key, and whether the value of that key starts with `Basic`. The `New-PodeAuthType -Basic` function can be supplied parameters to customise this name, as well as the encoding.

For example, to use `ASCII` encoding rather than the default `ISO-8859-1` you could do:

```powershell
Start-PodeServer {
auth use login -t basic -v {
# check
} -o @{ 'Encoding' = 'ASCII' }
New-PodeAuthType -Basic -Encoding 'ASCII' | Add-PodeAuth -Name 'Login' -ScriptBlock {}
}
```

More options can be seen further below.

## Validating

Once configured you can start using Basic authentication to validate incoming requests. You can either configure the validation to happen on every `route` as global `middleware`, or as custom `route` middleware.
Once configured you can start using Basic 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 Basic authentication to validate every request on every `route`:
The following will use Basic Authentication to validate every request on every Route:

```powershell
Start-PodeServer {
(auth check login) | Add-PodeMiddleware -Name 'GlobalAuthValidation'
Get-PodeAuthMiddleware -Name 'Login' | Add-PodeMiddleware -Name 'GlobalAuthValidation'
}
```

Whereas the following example will use Basic authentication to only validate requests on specific a `route`:
Whereas the following example will use Basic authentication to only validate requests on specific a Route:

```powershell
Start-PodeServer {
Add-PodeRoute -Method Get -Path '/info' -Middleware (auth check login) -ScriptBlock {
Add-PodeRoute -Method Get -Path '/info' -Middleware (Get-PodeAuthMiddleware -Name 'Login') -ScriptBlock {
# logic
}
}
```

## Full Example

The following full example of Basic authentication will setup and configure authentication, validate that a users username/password is valid, and then validate on a specific `route`:
The following full example of Basic authentication will setup and configure authentication, validate that a users username/password is valid, and then validate on a specific Route:

```powershell
Start-PodeServer {
Add-PodeEndpoint -Address *:8080 -Protocol Http
# setup basic authentication to validate a user
auth use login -t basic -v {
New-PodeAuthType -Basic | Add-PodeAuth -Name 'Login' -ScriptBlock {
param($username, $password)
# here you'd check a real user storage, this is just for example
Expand All @@ -79,7 +75,7 @@ Start-PodeServer {
}
# check the request on this route against the authentication
Add-PodeRoute -Method Get -Path '/cpu' -Middleware (auth check login) -ScriptBlock {
Add-PodeRoute -Method Get -Path '/cpu' -Middleware (Get-PodeAuthMiddleware -Name 'Login') -ScriptBlock {
Write-PodeJsonResponse -Value @{ 'cpu' = 82 }
}
Expand All @@ -89,10 +85,3 @@ Start-PodeServer {
}
}
```

## Use Options

| Name | Description | Default |
| ---- | ----------- | ------- |
| Encoding | Defines which encoding to use when decoding the Authorization header | ISO-8859-1 |
| Name | Defines the name part of the header, in front of the encoded sting, such as the `Basic` part of `Basic <username:password>` | Basic |
65 changes: 31 additions & 34 deletions docs/Tutorials/Authentication/Custom.md
View file
Original file line number Diff line number Diff line change
@@ -1,62 +1,63 @@
# Custom Authentication

Custom authentication works much like the inbuilt types, but allows you to specify your own parsing logic, as well as any custom options that might be required.
Custom authentication works much like the inbuilt types (Basic and Form), but allows you to specify your own parsing logic, as well as any custom options that might be required.

## Setup and Parsing

To setup and start using Custom authentication in Pode you can set `auth use -c <name>` in you server script. The `<name>` can be anything you want, even the name of an inbuilt method (it will still use your custom logic!).
To setup and start using Custom authentication in Pode you use the `New-PodeAuthType -Custom` function, and then pipe this into the `Add-PodeAuth` function.

Let's say we wanted something similar to [`Form`](../Form) authentication but it requires a third piece of information: `ClientName`. To setup Custom authentication for this method, you'll need to specify the parsing scriptblock under `-p`, as well as the validator script too.
Let's say we wanted something similar to [`Form`](../Form) Authentication, but it requires a third piece of information: `ClientName`. To setup Custom Authentication for this method, you'll need to specify the parsing logic within the `-ScriptBlock`.

The parsing script will be passed the current web event (containing the `Request`/`Response` objects, much like a `route`). In this script you can parse the request payload/headers for any credential information that needs validating. Once sourced, the data returned from the script should be either a `hashtable` or an `array`; this data will then `splatted` onto the validator scriptblock ([info](../../../Functions/Helpers/Invoke-PodeScriptBlock)):
The `-ScriptBlock` on `New-PodeAuthType` will be passed the current web event (containing the `Request`/`Response` objects, much like a Route). In this script you can parse the Request payload/headers for any credential information that needs validating. Once sourced, the data returned from the script should be either an `array`, which will then splatted onto the `-ScriptBlock` from your `Add-PodeAuth` function:

```powershell
Start-PodeServer {
# here we're calling the custom method "client"
auth use -c client -p {
# the current web event, and auth method options supplied
param($event, $opts)
# define a new custom authentication type
$custom_type = New-PodeAuthType -Custom -ScriptBlock {
param($e, $opts)
# get client/user/pass field names to get from payload
$clientField = (Protect-PodeValue -Value $opts.ClientField -Default 'client')
$userField = (Protect-PodeValue -Value $opts.UsernameField -Default 'username')
$passField = (Protect-PodeValue -Value $opts.PasswordField -Default 'password')
# get the client/user/pass from the post data
$client = $event.Data.$clientField
$username = $event.Data.$userField
$password = $event.Data.$passField
$client = $e.Data.$clientField
$username = $e.Data.$userField
$password = $e.Data.$passField
# return the data, to be passed to the validator script
return @($client, $username, $password)
} `
-v {
}
# now, add a new custom authentication method
$custom_type | Add-PodeAuth -Name 'Login' -ScriptBlock {
param($client, $username, $password)
# check if the client is valid
return @{ 'user' = $user }
return @{ User = $user }
}
}
```

## Validating

Once configured you can start using the Custom authentication to validate incoming requests. You can either configure the validation to happen on every `route` as global `middleware`, or as custom `route` middleware.
Once configured you can start using the Custom 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 Custom authentication to validate every request on every `route`:
The following will use Custom Authentication to validate every request on every Route:

```powershell
Start-PodeServer {
(auth check client) | Add-PodeMiddleware -Name 'GlobalAuthValidation'
Get-PodeAuthMiddleware -Name 'Login' | Add-PodeMiddleware -Name 'GlobalAuthValidation'
}
```

Whereas the following example will use Custom authentication to only validate requests on specific a `route`:

```powershell
Start-PodeServer {
Add-PodeRoute -Method Get -Path '/info' -Middleware (auth check login) -ScriptBlock {
Add-PodeRoute -Method Get -Path '/info' -Middleware (Get-PodeAuthMiddleware -Name 'Login') -ScriptBlock {
# logic
}
}
Expand All @@ -70,34 +71,35 @@ The following full example of Custom authentication will setup and configure aut
Start-PodeServer {
Add-PodeEndpoint -Address *:8080 -Protocol Http
# here we're calling the custom method "client"
auth use -c client -p {
# the current web event, and auth method options supplied
param($event, $opts)
# define a new custom authentication type
$custom_type = New-PodeAuthType -Custom -ScriptBlock {
param($e, $opts)
# get client/user/pass field names to get from payload
$clientField = (Protect-PodeValue -Value $opts.ClientField -Default 'client')
$userField = (Protect-PodeValue -Value $opts.UsernameField -Default 'username')
$passField = (Protect-PodeValue -Value $opts.PasswordField -Default 'password')
# get the client/user/pass from the post data
$client = $event.Data.$clientField
$username = $event.Data.$userField
$password = $event.Data.$passField
$client = $e.Data.$clientField
$username = $e.Data.$userField
$password = $e.Data.$passField
# return the data, to be passed to the validator script
return @($client, $username, $password)
} `
-v {
}
# now, add a new custom authentication method
$custom_type | Add-PodeAuth -Name 'Login' -ScriptBlock {
param($client, $username, $password)
# check if the client is valid
return @{ 'user' = $user }
return @{ User = $user }
}
# check the request on this route against the authentication
Add-PodeRoute -Method Get -Path '/cpu' -Middleware (auth check client) -ScriptBlock {
Add-PodeRoute -Method Get -Path '/cpu' -Middleware (Get-PodeAuthMiddleware -Name 'Login') -ScriptBlock {
Write-PodeJsonResponse -Value @{ 'cpu' = 82 }
}
Expand Down Expand Up @@ -129,8 +131,3 @@ Below is an example HTML page that would POST the client/username/password to th
</div>
</form>
```

## Use Options

!!! info
There are no `use` options for custom types, unless you define your own.
41 changes: 15 additions & 26 deletions docs/Tutorials/Authentication/Form.md
View file
Original file line number Diff line number Diff line change
@@ -1,69 +1,65 @@
# Form Authentication

Form authentication is for when you're using a `<form>` in HTML, and you submit the form. The method expects a `username` and `password` to be passed from the form input fields.
Form Authentication is for when you're using a `<form>` in HTML, and you submit the form. This Authentication method expects a `username` and `password` to be passed from the form's input fields.

## Setup

To setup and start using Form authentication in Pode you specify `auth use <name> -t form` in your server script, the validator script you need to supply will have the username/password supplied as arguments to the scriptblock:
To setup and start using Form Authentication in Pode you use the `New-PodeAuthType -Form` function, and then pipe this into the `Add-PodeAuth` function:

```powershell
Start-PodeServer {
auth use login -t form -v {
New-PodeAuthType -Form | Add-PodeAuth -Name 'Login' -ScriptBlock {
param($username, $password)
# check if the user is valid
return @{ 'user' = $user }
return @{ User = $user }
}
}
```

By default, Pode will check if the request's payload (from POST) contains a `username` and `password` field. The `auth use` action can be supplied options via `-o` to override the names of these fields for anything custom.
By default, Pode will check if the Request's payload contains a `username` and `password` fields. The `New-PodeAuthType -Form` function can be supplied parameters to allow for custom names of these fields.

For example, to look for the field `email` rather than rather than the default `username` you could do:
For example, to look for the field `email` rather than the default `username` you could do:

```powershell
Start-PodeServer {
auth use login -t form -v {
# check
} -o @{ 'UsernameField' = 'email' }
New-PodeAuthType -Form -UsernameField 'email' | Add-PodeAuth -Name 'Login' -ScriptBlock {}
}
```

More options can be seen further below.

## Validating

Once configured you can start using Form authentication to validate incoming requests. You can either configure the validation to happen on every `route` as global `middleware`, or as custom `route` middleware.
Once configured you can start using Form 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 Form authentication to validate every request on every `route`:
The following will use Form Authentication to validate every request on every Route:

```powershell
Start-PodeServer {
(auth check login) | Add-PodeMiddleware -Name 'GlobalAuthValidation'
Get-PodeAuthMiddleware -Name 'Login' | Add-PodeMiddleware -Name 'GlobalAuthValidation'
}
```

Whereas the following example will use Form authentication to only validate requests on specific a `route`:
Whereas the following example will use Form Authentication to only validate requests on specific a Route:

```powershell
Start-PodeServer {
Add-PodeRoute -Method Get -Path '/info' -Middleware (auth check login) -ScriptBlock {
Add-PodeRoute -Method Get -Path '/info' -Middleware (Get-PodeAuthMiddleware -Name 'Login') -ScriptBlock {
# logic
}
}
```

## Full Example

The following full example of Form authentication will setup and configure authentication, validate that a users username/password is valid, and then validate on a specific `route`:
The following full example of Form authentication will setup and configure authentication, validate that a users username/password is valid, and then validate on a specific Route:

```powershell
Start-PodeServer {
Add-PodeEndpoint -Address *:8080 -Protocol Http
# setup form authentication to validate a user
auth use login -t form -v {
New-PodeAuthType -Form | Add-PodeAuth -Name 'Login' -ScriptBlock {
param($username, $password)
# here you'd check a real user storage, this is just for example
Expand All @@ -79,7 +75,7 @@ Start-PodeServer {
}
# check the request on this route against the authentication
Add-PodeRoute -Method Get -Path '/cpu' -Middleware (auth check login) -ScriptBlock {
Add-PodeRoute -Method Get -Path '/cpu' -Middleware (Get-PodeAuthMiddleware -Name 'Login') -ScriptBlock {
Write-PodeJsonResponse -Value @{ 'cpu' = 82 }
}
Expand Down Expand Up @@ -107,10 +103,3 @@ Below is an example HTML page that would POST the username/password to the serve
</div>
</form>
```

## Use Options

| Name | Description | Default |
| ---- | ----------- | ------- |
| UsernameField | Defines the name of field which the username will be passed in from the `<form>` | username |
| PasswordField | Defines the name of field which the password will be passed in from the `<form>` | password |
Loading

0 comments on commit 97a9eb7

Please sign in to comment.