Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
- Loading branch information
Showing
6 changed files
with
207 additions
and
28 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,98 @@ | ||
# Digest | ||
|
||
Digest Authentication lets you authenticate a user without actually sending the password to the server. Instead the a request is made to the server, and a challenge issued back for credentials. The authentication is then done by comparing hashes generated by the client and server. | ||
|
||
## Setup | ||
|
||
To setup and start using Digest Authentication in Pode you use the `New-PodeAuthType -Digest` function, and then pipe this into the [`Add-PodeAuth`](../../../../Functions/Authentication/Add-PodeAuth) function. The parameters supplied to the [`Add-PodeAuth`](../../../../Functions/Authentication/Add-PodeAuth) functions's ScriptBlock are the `$username`, and a HashTable containing the parameters from the Authorization header: | ||
|
||
```powershell | ||
Start-PodeServer { | ||
New-PodeAuthType -Digest | Add-PodeAuth -Name 'Authenticate' -ScriptBlock { | ||
param($username, $params) | ||
# check if the user is valid | ||
return @{ User = $user; Password = $password } | ||
} | ||
} | ||
``` | ||
|
||
Unlike other forms of authentication where you only need return the User on success. Digest requires you to also return the Password of the user as a separate property. This password is what is used as the secret key to generate the client's response hash, and allows the server to re-generate the hash for validation. (Not returning the password will result in an HTTP 401 challenge response). | ||
|
||
By default, Pode will check if the Request's header contains an `Authorization` key, and whether the value of that key starts with `Digest`. Pode will also gather the rest of the parameters in the header such as the Nonce, NonceCount, etc. An HTTP 401 challenge will be sent back if the Authorization header is invalid. | ||
|
||
The HashTable of parameters sent to the [`Add-PodeAuth`](../../../../Functions/Authentication/Add-PodeAuth) functions's ScriptBlock are the following: | ||
|
||
| Parameter | Description | | ||
| --------- | ----------- | | ||
| cnonce | A nonce value generated by the client | | ||
| nc | The count of time the client has used the server nonce | | ||
| nonce | A nonce value generated by the server | | ||
| qop | Fixed to 'auth' | | ||
| realm | The realm description from the server's HTTP 401 challenge | | ||
| response | The generated hash value of all these parameters from the client | | ||
| uri | The URI path that needs authentication | | ||
| username | The username of the user that needs authenticating | | ||
|
||
## Middleware | ||
|
||
Once configured you can start using Digest 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 Digest Authentication to validate every request on every Route: | ||
|
||
```powershell | ||
Start-PodeServer { | ||
Get-PodeAuthMiddleware -Name 'Login' | Add-PodeMiddleware -Name 'GlobalAuthValidation' | ||
} | ||
``` | ||
|
||
Whereas the following example will use Digest authentication to only validate requests on specific a Route: | ||
|
||
```powershell | ||
Start-PodeServer { | ||
Add-PodeRoute -Method Get -Path '/info' -Middleware (Get-PodeAuthMiddleware -Name 'Login') -ScriptBlock { | ||
# logic | ||
} | ||
} | ||
``` | ||
|
||
## Full Example | ||
|
||
The following full example of Digest authentication will setup and configure authentication, validate that a user's username is valid, and then validate on a specific Route: | ||
|
||
```powershell | ||
Start-PodeServer { | ||
Add-PodeEndpoint -Address * -Port 8080 -Protocol Http | ||
# setup digest authentication to validate a user | ||
New-PodeAuthType -Digest | Add-PodeAuth -Name 'Authenticate' -ScriptBlock { | ||
param($username, $params) | ||
# here you'd check a real user storage, this is just for example | ||
if ($username -eq 'morty') { | ||
return @{ | ||
User = @{ | ||
'ID' ='M0R7Y302' | ||
'Name' = 'Morty'; | ||
'Type' = 'Human'; | ||
} | ||
Password = 'pickle' | ||
} | ||
} | ||
# authentication failed | ||
return $null | ||
} | ||
# check the request on this route against the authentication | ||
Add-PodeRoute -Method Get -Path '/cpu' -Middleware (Get-PodeAuthMiddleware -Name 'Authenticate') -ScriptBlock { | ||
Write-PodeJsonResponse -Value @{ 'cpu' = 82 } | ||
} | ||
# this route will not be validated against the authentication | ||
Add-PodeRoute -Method Get -Path '/memory' -ScriptBlock { | ||
Write-PodeJsonResponse -Value @{ 'memory' = 14 } | ||
} | ||
} | ||
``` |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters