App tokens for accessing PowerShell Universal APIs.
PowerShell Universal app tokens can be used with both custom API endpoints and the management API. The management API uses the standard Administrator, Operator and Reader roles. The custom API app tokens can utilize custom roles as well as the built in ones.
You can grant App Tokens to using the Admin Console or you can use the Management API directly.
To grant a token in the Admin Console, navigate to Settings Security AppTokens. Click the Grant App Token button to grant an App Token for the current user.
When you click Grant App Token, you will be provided with a dialog that allows you to specify the Identity, Role and expiration time of the token.
You can also grant app tokens to users from the management API. To grant an App Token programmatically using the API, you can do the following.
Administrators can grant app tokens to any user by specifying the user's identity ID. In order to grant an app token to an identity via the REST API, the user needs to have a defined role. The user is defined with the Operator role and thus their App Token will be granted access based on that role.
WS-Federation supports both Active Directory Federation Services and Azure Active Directory.
You first need to configure ADFS or AzureAD to support Universal.
These are the current Federation Service settings for our domain.
You need to configure the following Relying Parties settings for Universal. On the Identifiers tab, provide the URL to the Universal website. HTTPS is required.
On the Endpoints tab. You'll need to include a WS-Federation Passive Endpoint. Make sure to include the trailing slash.
You can configure additional claims you'd like to use if you are using policies in Universal.
Follow the documentation for the Azure Active Directory configuration found on this Microsoft Document.
After configuring ADFS or AAD, you can now provide the properties to Universal for the MetadataAddress and Wtrealm. Read about these settings on the our Settings page.
Here is an example of how to update the appsettings.json file to accommodate the correct settings for WS-Federation.
Configure OpenID Connect with Universal.
OpenID Connect is an authentication layer on top of OAuth 2.0, an authorization framework. It is supported by many vendors and provides the ability to authenticate against systems like AzureAD.
This document will outline the steps necessary to configure AzureAD OpenID Connect and use it with Universal.
Within the Azure Portal, navigate to your Azure Active Directory blade. Next, click the App registrations node and then click New registration.
In the New registration page, enter the name of your application and the reply URL. The URL can be configured in the appsettings.json for Universal but the default value is shown below.
Next, you'll need to configure a client secret. You can click the Certificates & secrets menu and then click New client secret. This secret will need to go into the appsettings.json file.
Now, you will need to take note of your Application (client) ID GUID. This will be used in the appsettings.json file.
Finally, you will have to click the Endpoints button to open the Endpoints drawer. This contains a list of the endpoints. Make note of the OAuth 2.0 authorization endpoint URL. You will need this for the appsettings.json. Note that you will not input the entire endpoint URL. You will need to include the portion of the URL through the GUID but without the path after oauth2 in the Authority setting below (e.g. https://login.microsoftonline.com/fffffff-4b76-4470-a736-8481d7a2ed87).
Read more about appsettings.json on our Settings page.
Now that we have completed the configuration of an AzureAD App Registration, we can update the appsettings.json file with the appropriate settings. For my application, it would look something like this.
Due to changes in the Chromium browser, you may need to disable the Cookies without SameSite must be secure setting to test OpenID Connect when running on localhost without HTTPS.
Navigate to chrome://flags and search for the setting to set it to disabled.
You can use access tokens generated by an OIDC login for other services the user may have access to. Within your OIDC provider, like Azure AD, you can grant additional permissions to the token.
You will also have to enable access tokens within the authentication flow so that the token provides the necessary resource access.
Finally, within your PSU appsettings.json file, you will need to ensure that SaveTokens is enabled, the resource type includes token and the resource you wish to access is included in the Resource setting. The URL that you specify in the resource should be listed in within the provider.
The below example adds a resource for Microsoft O365.
Within your dashboard, you will now have access to an $AccessToken and $IdToken variable that you can use with cmdlets that require authorization.
For example, the Connect-AzureAd cmdlet accepts an access token.
Finally, you'll need to configure a Claim Issuance Policy for the Relying Party Trust. Create an Issuance Transform Rule that sends at least the Name and Name ID to Universal.
When running your server, you should now be prompted for your credentials either via the Internet Explorer single-sign system or you will be forwarded to the WS-Fed login page.
The forms authentication script is only called when users login through the login page. If you use any other authentication method, this script is not called. Role policy scripts are called for all authentication types.
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.
Authentication settings are also stored with authentication.ps1
To update forms authentication, you can click Settings Security and then click the Settings button for the forms authentication.
You can update the PowerShell script found in settings to configure how the user is authenticated. You'll need to return a New-PSUAuthenticationResult from the script to indicate whether the user was successfully authenticated.
You can check the password of the credential by using the GetNetworkCredential() method of PSCredential.
During forms authentication, you can set claims that will be available within role policies. This can provide a performance benefit when interacting with remote systems since you can perform a single claim lookup and then evaluate the claims locally rather than having to make additional calls to the remote system.
This example uses Active Directory to look up group membership and assign the as claims that will be available within the roles scripts.
Within your roles.ps1 file, you will be able to use these claims to validate group membership.
This example checks to see if the user is part of the SOC_Admins group.
You can configure OpenID authentication and authorization by adjusting the settings within the OpenID section of the appsettings.json file. Authorization policies that you configure within Universal will be run on the user's identity after authentication is successful.
Windows Authentication provides single-sign on support for browsers and environments that support it. To enable Windows Authentication, set the WindowsAuthentication enabled setting to true in appsettings.json.
To enable Windows Authentication in IIS, ensure that you enable Windows Authentication and disable anonymous authentication.
Windows Authentication is supported outside of IIS but requires configuration of the account running the Universal service.
On Windows, you should install PowerShell Universal as a Windows Service. Once the service is installed, you will need to create a service account user and set the service to run with that user's account. The Windows authentication setting needs to be set to true.
The service account needs to have a Service Principal Name (spn) configured for the computer account. You can do this using the setspn command. The computer name needs to be the full qualified name of the machine running Universal.
For more information, you can follow the Microsoft documentation for configuring ASP.NET Core Windows Authentication: Configuring a Windows machine for Windows Authentication
Configuring a Linux or Mac OS machine for Windows Authentication
User authorization is accomplished with roles. Roles are either assigned based on the policy script you define or a role is assigned manually to the user.
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.
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.
Full access to the entire PowerShell Universal platform and settings.
Operators have access to add and remove resources such as APIs, Scripts and Dashboards. Operators cannot change settings like environments, roles, or general settings.
The Execute role grants the ability to run scripts and read access for everything else.
The Reader role provides read-only access to PowerShell Universal.
If your users are members of more than about 40 groups you may experience problems logging in. This is due to size limits of the HTTP headers in IIS and Kestrel. The more groups a user is a member of, the more authorization claims they have and the large the header.
You can increase the header limit for Kestrel by using the limits configuration in appsettings.json file. You will need to increase the header size. It is a value in bytes and defaults to 32kb.
Authorization in IIS works as with any other method but you need to be aware of the request header size limit. You may receive errors when you enable claims that include many groups. They can exceed the header size limit and IIS will return errors. We have found that about 40 Azure Active Directory groups will cause this issue on a default IIS installation.
The error you will receive will either be a 400 error with the request is too long.
If you have HTTPS enabled, you will receive an error about a HTTP2 protocol error.
You can increase the IIS request size by setting the following registry keys. You will need to restart you machine in order for them to take affect.
More information can be found on Microsoft's documentation.
As an alternative to increasing the request size, you can also reduce the number of groups sent. In Azure Active Directory, you can set to just the groups assigned to the application to prevent all groups from being sent.
Now go to Enterprise Application > (Select the app) > Users and groups. Assign the group(s) you are interested in including in the claims. (Note: this can also be used as a security boundary if you set “User Assignment Required” to Yes in the ‘Properties’ section of the app)
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.
By default, the forms authentication and policy assignment scripts run within the PowerShell Universal process. You can optional configure an external Environment to run your authentication and authorization scripts. When you configure a security environment, an external PowerShell process will be started and configured use your Environment's settings.
To adjust the environment used by the security process, set the -SecurityEnvironment in settings.ps1.
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.
This example requires an authentication method that will provide group information during the authentication process. Methods like Windows authentication and WS-Federation can provide this information. Forms authentication will not work with this type of policy.
This example takes advantage of the claims that are provided during authentication. You can check to see if the user has a groupsid (group membership) by using the HasClaim method of the $User object. This method will check the Claims array to see if they have a particular groupsid claim. Use the SID of the group to validate whether they are a group member.
For debugging and development purposes, you can check to see what claims a user has been exporting the $User variable to a file.
You should see a JSON file that contains the user's identity and claims array.
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.
In Azure go to App registrations > (Select the app) > Token Configuration, and specify Groups assigned to the application.
