Security

Forms Authentication

By default, the forms authentication script is configured to accept the user Admin and any password. You can configure this authentication policy to interact with whatever system you like. The script will receive a PSCredential object that contains the user name and password entered by the user at the login page.

Authorization

User authorization can be achieved in two different ways: Role Assignment or Policy Assignment.

Policy Assignment

By default, roles are assigned by policies. Policies are run when the user logs in. You can change the policy scripts by visiting the Security / Roles tab. Click the Edit Policy button to configure the Policy script.

Policy scripts will receive a ClaimsPrincipal object as a parameter and need to return true or false. Policies that throw errors will be assumed to be false. The ClaimsPrincipal object contains the user's identity and the claims that the user has received. These may include group assignments or other features of a user's account.

You can expect an object with this structure.

public class ClaimsPrincipal
{
public List<Claim> Claims { get; set; } = new List<Claim>();
public Identity Identity { get; set; } = new Identity();
}
public class Identity
{
public string Name { get ;set; }
}
public class Claim
{
public string Type { get; set; }
public string Value { get; set; }
public string ValueType { get; set; }
public string Issuer { get; set; }
public Dictionary<string, string> Properties { get; set; } = new Dictionary<string, string>();
}

Role Assignment

To assign a role to a user, you can create their identity within Universal and then select the role in the drop down on the Identities page. By default, identities receive a role through policy.

App Tokens

App Tokens can be assigned to services that cannot login interactively. You can grant a new app token to your account by clicking the Grant App Token button within the Security / App Tokens tab.

The token will have a expiration of one year and have the valid roles for your account. To copy the App Token to your account, click the Copy action. To revoke an App Token, click the Revoke action.

You can use App Tokens with the Universal cmdlets or by using web requests directly using Bearer authorization.

Example: Forms Authentication with Active Directory

The following example shows performing a simple "LDAP BIND" in order to validate a users Active Directory Credentials. If a user attempting to access PowerShell Universal is not the Default Admin User they will have to successfully authenticate their credentials with Active Directory via a simple LDAP bind. This can be combined with a AD Group Member check in the Admin, Operator, and Reader role policies to effectively use Active Directory Authentication AND Active Directory Group membership to provide Role Based Access to PowerShell Universal.

param(
[PSCredential]$Credential
)
#
# You can call whatever cmdlets you like to conduct authentication here.
# Just make sure to return the $Result with the Success property set to $true
#
$Result = [Security.AuthenticationResult]::new()
if ($Credential.UserName -eq 'Admin')
{
#Maintain the out of box admin user
$Result.UserName = 'Default Admin'
$Result.Success = $true
}
else
{
# Get current domain using logged-on user's credentials - this validates their credential
$CurrentDomain = "LDAP://DC=mydemodomain,DC=com" # Insert Your Domain Here
$domain = New-Object System.DirectoryServices.DirectoryEntry($CurrentDomain,($Credential.UserName),$Credential.GetNetworkCredential().password)
if ($domain.name -eq $null)
{
"Authentication failed for $($Credential.UserName)!" | Out-File "C:\test\adlogin.txt"
write-host "Authentication failed - please verify your username and password."
$Result.UserName = ($Credential.UserName)
$Result.Success = $false
}
else
{
write-host "Successfully authenticated with domain $($domain.name)"
"Authentication success for $($Credential.UserName)!" | Out-File "C:\test\adlogin.txt"
$Result.UserName = ($Credential.UserName)
$Result.Success = $true
}
}
$Result

Example: Policy based on Active Directory Group Membership

In this example we will configure out Administrator Policy Script to use LDAP to retrieve the membership of an Active Directory Group. Here we have created a group called "PowerShell Universal Admins" where members of the group should be granted Administrator Access in PowerShell Universal. Here we are doing a simple samaccountname check for the user to ensure they are a member of the group. For more robust environments a SID/DN/ObjectGUID check would be more appropriate.

param(
$User
)
$UserName = ($User.Identity.Name)
$UserName = $UserName.Substring($UserName.IndexOf('\')+1,($UserName.Length -($UserName.IndexOf('\')+1)))
$IsMember = $false;
# Perform LDAP Group Member Lookup
$Searcher = New-Object DirectoryServices.DirectorySearcher
$Searcher.SearchRoot = 'LDAP://CN=Users,DC=berg,DC=com' # INSERT ROOT LDAP HERE
$Searcher.Filter = "(&(objectCategory=person)(memberOf=CN=PowerShell Universal Admins,OU=Information Technology,DC=berg,DC=com))" #GROUP INSERT DN TO CHECK HERE
$Users = $Searcher.FindAll()
$Users | ForEach-Object{
If($_.Properties.samaccountname -eq $UserName)
{
$IsMember = $true;
"$UserName is a member of admin group!" | Out-File "C:\test\adgroup.txt"
}
else {
"$UserName is NOT member of admin group!" | Out-File "C:\test\adgroup.txt"
}
}
return $IsMember