|
| 1 | +--- |
| 2 | +layout: default |
| 3 | +title: Authentication |
| 4 | +type: about |
| 5 | +--- |
| 6 | + |
| 7 | +# Authentication |
| 8 | + |
| 9 | +## about_GettingStarted |
| 10 | + |
| 11 | +# SHORT DESCRIPTION |
| 12 | + |
| 13 | +Authentication is verifying who the consumer of your service or site is. Polaris uses the .Net class [System.Net.HttpListener](https://docs.microsoft.com/en-us/dotnet/api/system.net.httplistener?view=netframework-4.8) under the hood and is thus able to support the following authentication schemes out of the box: |
| 14 | + |
| 15 | +| Authentication Scheme | Description | |
| 16 | +| ------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------- | |
| 17 | +| Basic | Specifies basic authentication. | |
| 18 | +| Digest | Specifies digest authentication. | |
| 19 | +| IntegratedWindowsAuthentication | Specifies Windows authentication. | |
| 20 | +| Negotiate | Negotiates with the client to determine the authentication scheme. If both client and server support Kerberos, it is used; otherwise, NTLM is used. | |
| 21 | +| NTLM | Specifies NTLM authentication. | |
| 22 | +| Anonymous (Default) | Specifies anonymous authentication. | |
| 23 | + |
| 24 | +These authentication methods are global and are declared when you are creating your Polaris object as follows: |
| 25 | + |
| 26 | +```powershell |
| 27 | +# Basic Authentication |
| 28 | +Start-Polaris -Auth Basic |
| 29 | +
|
| 30 | +# Ntml |
| 31 | +Start-Polaris -Auth NTLM |
| 32 | +``` |
| 33 | + |
| 34 | +User information will be available for use inside your scriptblocks via `$Request.User`: |
| 35 | + |
| 36 | +```powershell |
| 37 | +Start-Polaris -Auth Basic |
| 38 | +
|
| 39 | +New-PolarisRoute -Method GET -Path "/whoami" -Scriptblock { |
| 40 | + $Response.json(($Request.User | ConvertTo-Json)) |
| 41 | +} |
| 42 | +``` |
| 43 | + |
| 44 | +Note that with Basic auth all you get is `$Request.User.Identity.Name` and `$Request.User.Identity.Password`. If you are using Basic authentication in any web application you are going to have to write additional logic to validate that username and password are correct and determine whether or not they are authorized for different parts of your application. |
| 45 | + |
| 46 | +The easiest way to implement authentication is if you are in a Windows environment hosting Polaris from a Windows server and are authenticating with domain joined user accounts. If this is the case authentication and authorization are as simple as: |
| 47 | + |
| 48 | +```powershell |
| 49 | +Start-Polaris -Auth Negotiate |
| 50 | +
|
| 51 | +# Here we are checking to see if the user is in the administrator group of the PC where Polaris is hosted from |
| 52 | +# Note: This will return false unless you access Polaris from an elevated web browser |
| 53 | +New-PolarisRoute -Method Get -Path "/TestAdminGroup" -Scriptblock { |
| 54 | + $Response.Send("User is in Administrators Role: $($Request.User.IsInRole('Administrators'))") |
| 55 | +} |
| 56 | +
|
| 57 | +# You can also use IsInRole to test if the user is in any Active Directory security group |
| 58 | +New-PolarisRoute -Method Get -Path "/TestADSecurityGroup" -Scriptblock { |
| 59 | + $MyActiveDirectorySecurityGroup = "SecurityGroup1" |
| 60 | + $Response.Send("User is in $MyActiveDirectorySecurityGroup Role: $($Request.User.IsInRole($MyActiveDirectorySecurityGroup))") |
| 61 | +} |
| 62 | +``` |
| 63 | + |
| 64 | +This is also a very nice experience for end users as on Windows PCs they will not be prompted for credentials unless their PC cannot talk to a domain controller (i.e. off network). |
| 65 | + |
| 66 | +## Additional Authentication Types |
| 67 | + |
| 68 | +Any additional or custom authentication types can be implemented using the `New-PolarisRouteMiddleware`. |
| 69 | + |
| 70 | +# LONG DESCRIPTION |
| 71 | + |
| 72 | +## Basic |
| 73 | + |
| 74 | +Basic authentication strictly validates that a client has passed Polaris a header that looks like this: `Authorization: Basic <Base64Encoded(username:password)>. If the incoming Http request does not have the required headers it will send a response to the client telling them that Basic authentication is required. You can read more about basic authentication on the [Mozilla docs site here](https://developer.mozilla.org/en-US/docs/Web/HTTP/Authentication). |
| 75 | + |
| 76 | +One thing to remember with this authentication scheme though is that it only ensures there is a username and password. Not that the username and password is valid. This leaves it up to you the application developer to validate the username and password. |
| 77 | + |
| 78 | +The most basic implementation of this would be a simple hard coded username and password inside of a Middleware like this: |
| 79 | + |
| 80 | +```powershell |
| 81 | +New-PolarisRouteMiddleware -Name "BasicAuthValidation" -Scriptblock { |
| 82 | + if($Request.User.Identity.Name -ne "Username" -or $Request.User.Identity.Password -ne "Password") { |
| 83 | + $Response.StatusCode = 401; |
| 84 | + $Response.Send("Unauthorized") |
| 85 | + } |
| 86 | +} |
| 87 | +``` |
| 88 | + |
| 89 | +Of course in a production environment you might want to use the username and password to query against a table in a database. |
| 90 | + |
| 91 | +## Digest |
| 92 | + |
| 93 | +Digest authentication is an authentication method that can be used to avoid sending the username and password in clear text. With HTTPS being easy and very prevalent this is less of a need for sites who want to use just username and password for authentication. |
| 94 | + |
| 95 | +You can read more about digest authentication in [the official RFC](https://tools.ietf.org/html/rfc2617#section-3) |
| 96 | + |
| 97 | +## Integrated Windows Authentication & Negotiate & NTLM |
| 98 | + |
| 99 | +All three of these authentication methods are very useful for internal web applications that are being accessed by computers or users on the same domain as the computer that is hosting the web application. Typically you will want to use `Negotiate` as that will ensure the best compatibility with any client that is going to be connecting with Polaris. |
| 100 | + |
| 101 | +It will populate `$Request.User` with an IPrincipal that contains all the Active Directory security groups the authenticated user is a member of. You can test their membership of security groups using `$Request.User.IsInRole`. It can also be used to impersonate the user if Polaris is being executed as a service account that has authorization to impersonate authenticated users by `[WindowsIdentity]::RunImpersonated($Request.User.Identity.AccessToken, [action]{ & whoami })`. |
| 102 | + |
| 103 | +Impersonation offers an excellent solution if you are attempting to create a web based file server as access to the files and folders can be managed using standard file and folder permissions and impersonation will ensure that those security rules are honored. |
| 104 | + |
| 105 | +## Custom Authentication |
| 106 | + |
| 107 | +Since this is not supported out of the box and needs to be implemented in a middlware you will need to start Polaris with `Start-Polaris -Auth Anonymous` or leave Auth unspecified and it will default to Anonymous. |
| 108 | + |
| 109 | +Then authentication can be completely implemented using middleware. Here is an example of implementing Basic authentication as a middleware: |
| 110 | + |
| 111 | +```powershell |
| 112 | +New-PolarisRouteMiddleware -Name "BasicAuthValidation" -Scriptblock { |
| 113 | + $AuthHeader = $Request.Headers.Get("Authorization") |
| 114 | +
|
| 115 | + if($AuthHeader -eq $Null -or $AuthHeader -notmatch "^Basic") { |
| 116 | + $Response.Headers.Add("WWW-Authenticate", "Basic realm=$Env:Computername") |
| 117 | + $Response.StatusCode = 401 |
| 118 | + $Response.Send("Unauthorized. Missing auth header.") |
| 119 | + } |
| 120 | +
|
| 121 | + $DecodedHeader = [system.text.encoding]::UTF8.GetString([system.convert]::FromBase64String(($Request.Headers.Get("Authorization") -split " ")[1])) |
| 122 | + $Username = ($DecodedHeader -split ":")[0] |
| 123 | + $Password = ($DecodedHeader -split ":")[1] |
| 124 | +
|
| 125 | + if($Username -ne "Username" -or $Password -ne "Password") { |
| 126 | + $Response.Headers.Add("WWW-Authenticate", "Basic realm=$Env:Computername") |
| 127 | + $Response.StatusCode = 401; |
| 128 | + $Response.Send("Unauthorized. Incorrect username or password.") |
| 129 | + } |
| 130 | +} |
| 131 | +``` |
| 132 | + |
| 133 | +It is a recommended best practice if you want to store the user's roles and access them throughout the rest of the application to create an IUserPrinciple and assign it to `$Request.User`. |
0 commit comments