Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Access controls for PowerShell Universal.
Access controls requires a license.
Access controls allow you to define who has access to particular resources inside PowerShell Universal. Currently, access controls only apply to scripts.
There are three types of access controls.
Global
Resource
Tag
PowerShell Universal uses a least-privileged model and users have no access without an access control that applies to their role.
Access controls are defined within the accessControls.ps1 file within your PowerShell Universal configuration repository.
You can define access controls in the admin console under Security \ Access Controls.
There are five different privileges that can be granted to users. These values are available on the [PowerShellUniversal.AccessControlType] enumeration.
View (1)
Edit (2)
Create (4)
Delete (8)
Execute (16)
You can define multiple access control types on a single access control by using a binary or operator.
For example, this creates a privilege for both Create and View.
You can also use the integer values for a more terse syntax. This creates the same Create and View privileges.
Global access controls allow you to define an access for a role for all resources of the chosen type.
For example, to allow any user with the ScriptBuilder role to create a script, you can define an access control using the following command. You'll also want to grant the View privilege so that the user can also view scripts.
Resource access controls allow you to specify access controls directly on a resource.
This example defines the execute privilege on the OnBoarding.ps1 script to the ScriptRunner role.
Tag access controls allow you to specify an access control based on a tag. All tagged resources will have this access control defined. This allows you to group resources and apply access controls to the group.
The following example provides the edit privilege to the ScriptEditor role and the HR tag.
Client certificate authentication for PowerShell Universal.
Client certificate authentication ensures that client machines hold a particular certificate when connecting to PowerShell Universal. The certificate check is handled during the HTTP negotiation so it affects the entire webserver and cannot be configured per route.
For detailed information about client certificate authentication in ASP.NET Core 5.0, you can visit the Microsoft documentation here.
You will need to enable HTTPS hosting and turn on client certificate authentication. First, ensure that you have an HTTP certificate selected and you have set the ClientCertificateMode to RequireCertificate. These settings can be set within the appsettings.json file.
Next, you will need to enable client certificate authentication.
You can use the roles.ps1 file to evaluate the certificate provided by the client. This can be used to determine which roles the user will receive when connecting to PSU.
To evaluate the properties that are available during authorization, you can serialize the $user variable provided to the role policy functions.
You will receive information about the certificate within the user object similar to below.
You can evaluate the the claims using the HasClaim method. The following is an example of checking the thumbprint of the certificate.
Security best practices for PowerShell Universal
This document provides security best practices and hardening options for PowerShell Universal.
We recommend enabling app token enhanced security. App tokens generated within PowerShell Universal will be hashed and stored in the database rather than persisted in plaintext. As app tokens are used, they are hashed and compared against the hashed values. Tokens are hashed with SHA256.
We recommend adjusting the default app token signing key. This setting is present in appsettings.json. Changing the signing key will invalidate existing app tokens.
Consider using authentication.ps1 for configuring authentication methods that require secrets. When using authenticaiton.ps1, you can use secret variables and, in turn, secret vaults to load these values when starting up.
We recommend changing the default admin account password. By default, this password is stored within the PowerShell Universal database. You will receive a warning on the login page if the admin password is the default.
Ensure that role scripts are either disabled or do not simply return true. Returning true from a role script will grant any user access to that role. With authentication methods like Windows Authentication, any user that is a capable of logging into the domain will have acecss to PowerShell Universal if the roles are not properly configured.
Consider using a least privileged access model for roles within PowerShell Universal. Much of PowerShell Universal can be used with the execute or operator role. It isn't necessary to assign the administrator role to all users.
It may be desirable to limit identities to ones created within PowerShell Universal. This will prevent users from accessing PowerShell Universal if they have not been added on the identities page.
Consider creating triggers that will notify you of potential issues with authentication and authorization. The following triggers may be useful:
Revoked App Token Usage
User Login
New User Login
API Authentication Failed
By default, job runs are stored as sequential big integers. This means that bad actors can guess job runs by incrementing a number from the current job ID. As of PowerShell Universal 3.8, an experimental feature can be enabled to only allow access of jobs by run ID. Run IDs are globally unique identifiers and cannot be guessed.
Avoid running long running event handlers directly within dashboards. This can be an avenue for a denial-of-service attack. Consider running long running processes as jobs to take advantage of queuing.
If using the Database or PSUSecretStore vaults, we recommend changing the default passwords. Both systems use a symmetric encryption method for storing secrets. The Database secret stored encrypts values using the specified key into the database persistence layer. The PSUSecretStore creates a local file in the service account's profile with the secret values.
PowerShell Universal integrates with the Microsoft Secret Management module. This module provides the ability to interact with an extensible set of vaults. Many vault implementations can be found on the PowerShell Gallery.
We recommend using a secure vault, such as Cyberark or Azure KeyVault, to store secrets in an enterprise ready fashion.
Follow the documentation for secret variable vaults to learn how to configure an alternate vault.
Enabling HTTPS for the web server is highly recommended. If possible, we recommend storing a certificate within the Certificate Manager to avoid having to include a clear-text password for a local PFX file. Certificates are configured within appsettings.json.
Consider configuring rate limiting to avoid denial of service attacks. PowerShell Universal executes PowerShell in many different ways. PowerShell can be slower to execute than compiled languages so rate limiting can be very beneficial, especially for PowerShell Universal instances accessible externally.
Learn more about rate limiting here.
Consider configuring the CORS hosts setting in appsettings.json . You can learn more about the benefits of the CORS hosts setting here.
Consider utilizing service accounts with a least-privileged access model. It's possible to configure the PowerShell Universal service to run as a service account that does not have access to certain resources and utilize alternate accounts when running scripts that need to access resources.
Learn more about service accounts here.
We recommend the use of SQL server with integrated security or Azure managed identities. This avoids having to store passwords locally.
By default, the LiteDB database is not password protected. Actors that can physically access the PowerShell Universal server can copy the database file from disk and open it elsewhere. Consider providing an encryption key to the LiteDB connection string to enable encryption.
PowerShell Universal exposes PowerShell scripts remotely in different ways. It's important to follow strict PowerShell script security best practices to guard against potentional attacks such as script injection.
Some recommendations include:
Use of param blocks to validate input
Avoiding Invoke-Expression to help prevent injection
Code and security review processes on scripts
Learn more about scripting security here.
Consider using one-way git sync for changes in your production environment. This ensures that PowerShell Universal is read-only, and only validated changes will be picked up in production environments.
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 Security \ Tokens. Click the Add New App Token button to grant an App Token.
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.
You can migrate app tokens between systems by using the management API. This is helpful when developing for high availability scenarios.
The following is an example of the POST that is required to create an existing app token in any PSU instance. Note that the signing key must be the same between the instances. You need a valid app token in the target system to create the migrated tokens.
When enhanced app token security is enabled, token values are only accessible once they are created. They are hashed and the hash value is stored in the database rather than the token. You will use the token the same way as any other token.
PowerShell Protect integration for PowerShell Universal.
PowerShell Protect is a feature of PowerShell Pro Tools. It allows you to audit and block PowerShell scripts and PowerShell command lines that are executed on your machine. You can deploy the client piece and then configure it using PowerShell Universal. PowerShell Universal can also be used as a collection mechanism for events generated by PowerShell Protect. Additionally, PowerShell Universal can trigger scripts when certain rules are triggered.
You can access PowerShell Protect tooling by navigating to Security \ Protect.
PowerShell Protect is configured via XML. PowerShell Universal can be used to create this XML. Navigate to the PowerShell Protect page and then click Configurations. Click Create New Configuration and name the configuration you are creating.
Default rules are configured that will block certain behaviors without additional configuration. You can choose to disable any rules you may not desire to enforce.
Actions are the result of custom rules triggering based on scripts being run. You can take actions such as blocking the script, sending the event to the event log or sending the event to PowerShell Universal.
Depending on the action selected, you will need to include additional settings. For example, to integrate with PowerShell Universal, you will need to define the HTTP address of the PSU server and an app token used to authenticate against PSU.
Custom rules can be defined to match features of a script being run. For example, you can match the user, script content, variables and domain being used to run a script. If the custom rule matches, you can then execute one or more rules that you have defined.
PowerShell Protect requires a PowerShell Pro Tools license for each user that will have the client installed. You can include the license information on the license tab. It will be included as part of the configuration file.
Once you have completed your configuration, you can navigate back to the Configurations page and download the XML.
You can learn how to install PowerShell Protect configurations here.
When you configure a rule to use the Universal action, events will be populated within the Events tab of PowerShell Universal.
When you configure a rule to use the Universal action, events can also trigger scripts. From the Automation \ Triggers page, create a new trigger and set the Event to PowerShell Protect Event. Then, you can choose to filter down which rule causes the trigger to fire.
The $ProtectEvent parameter will be passed to your script. This object contains the following properties.
Rule
String
The name of the rule that trigger this script.
Script
String
The content of the script executed.
ContentPath
String
The script path. If run from the command line, this will be null.
ApplicationName
String
An application name identifier. This may include the application version.
UserName
String
The user that ran the script.
ComputerName
String
The computer name of where the script ran.
Administrator
Boolean
Whether or not the user had admin access while running the script.
DomainName
String
The domain name of where the script was run.
Timestamp
DateTime
When the script was run.
Configure OpenID Connect with Universal.
OpenID Connect requires a license.
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.
If you are using Chrome, you will also need to enable HTTPS. You will see a 500 error without HTTPS enabled.
Available in PowerShell Universal 2.5 or later.
You can use the admin console to configure OpenID Connect. We recommend this method as you will not need to restart the PowerShell Universal service after configuring OIDC.
To add a new authentication method, navigate to Security \ Authentication and add the OpenID Connect provider.
Once the provider has been added, you can click the details button to enter the settings you'll need to authenticate against your OIDC provider. After setting the OIDC options, set the provider to enabled and log out. When visiting the /admin page, you'll be prompted for OIDC login.
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.
Okta supports OpenID Connect. You can configure an application to allow authentication against PowerShell Universal instances.
Within your Okta admin console, expand Applications and click Applications. Then click Create App Integration.
Select OIDC and Web Application.
Name your application and define the Sign-In redirect URL used to call your PowerShell Universal server. You will need to specify this callback URL within your PowerShell Universal configuration.
Once you've created your application, take note of your Client ID and Client Secret. You will specify these within your PowerShell Universal configuration.
Within the Sign On tab, specify the group claims filter to use for providing claims to PowerShell Universal. These claims can be used to assign roles based on group membership. The following filter returns all claims.
Once you have your Application configured, you can configure PowerShell Universal.
Once you have defined your Okta application, you can set your appsettings.json file to use the provider for logins. Below is an example of the section required for Okta to function. Take note of the scope functionality as it is required for retrieving group membership.
In order to look up group membership for Okta, you will need to use the $UserInfo variable that is available within roles.ps1. This variable provides additional information about the user logging in.
The groups property will contain a list of groups the user is a member of. You can validate membership by checking whether the list contains the desired group.
Access tokens are available for users within their scripts. You can use access tokens in jobs started by users and dashboards.
For example, you could return the current user's information by using the access token provided by Okta.
Security features of PowerShell Universal.
Local accounts are created and stored in the PowerShell Universal database. By default, credentials are stored in the local database vault.
To create a local account, you can navigate to Security \ Identities and create a new identity. Ensure that the Local Account switch is enabled and set a password.
If you have a licensed instance of PowerShell Universal, you can use a different credential vault.
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 a password of Admin. 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, click Security (below Settings) then Authentication. Click the 'Edit Details' button from there to review (or update) the forms authentication code.
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.
These are the variables defined within the security scripts.
$Cookies
Cookies provided in the client's HTTP request.
hashtable
$Headers
Headers provided in the client's HTTP request.
hashtable
$LocalIpAddress
The local IP address of the request.
string
$LocalPort
The local port of the request.
string
$RemoteIpAddress
The remote IP address of the request.
string
$RemotePort
The remote port of the request.
string
You can use the live log view on the authentication page to view information about the script execution. The live log view will display PowerShell streams.
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.
You can enable Windows authentication by adding a new authentication provider in Security \ Authentication. Select Windows and enable the authentication.
Once Windows set to authenticated, Windows authentication can now be used against Universal. You will have to log out in order to use Windows authentication.
To enable Windows Authentication in IIS, ensure that you enable Windows Authentication and disable anonymous authentication.
In the web.config file that is included with PowerShell Universal, ensure that you have set the forwardWindowsAuthToken to true.
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
PowerShell Universal will cache group membership claims when using Windows Authentication. Claims are cached for the configured session timeout value (default is 25 minutes).
To clear the cache manually, navigate to Security \ Roles and click the Clear Cached Claims button.
Depending on your local environment, you may need to configure your browser to properly pass credentials to PowerShell Universal.
User authorization is accomplished with roles. Roles can either be assigned through claims mapping, a policy script or by assigning the role directly to the identity.
By default, users will receive all roles when logging in. Multiple role assignments are valid in PowerShell Universal. While you configure roles, you can choose to disable roles you are not yet or do not plan to use.
Disabling the Administrators role will prevent you from making changes to roles within the Admin Console.
You can map roles to a claim (such as a group membership) by using the -ClaimType and -ClaimValue parameters of New-PSURole. Settings are also available in the role properties dialog within Security \ Roles.
For example, with Windows authentication, if you wanted to map a group to a role, you could configure it such that the group SID maps to the administrator role.
Mapping roles to claims in this manner is faster than Policy scripts because it does not require PowerShell to be run when the user is logging in.
To help develop policy scripts or assign roles to claims, you can view claim information by clicking View Claim Information in Security \ Roles.
You can map an Azure Active Directory group to a role by looking up the group Object ID in Azure. For example, within the Ironman Software domain, we have a group called Dashboard Administrators. This group has an object ID of 61849bf2-e44b-4057-b589-6cd1812d7545.
Within PowerShell Universal, I can assign users of this group to the Administrator group by setting up the claim mapping. The Claim Type will be groups and the Claim Value will be 61849bf2-e44b-4057-b589-6cd1812d7545. Once I have mapped the claim, users of the Dashboard Administrators group will be part of the PowerShell Universal Administrators group. The resulting roles.ps1 will look like this.
All other roles are disabled.
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 page. 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 claim mapping or 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.
You can change which page the user sees when logging in by setting the Default Route property for the role. For example, you may want HR users to go to the Human Resources dashboard while you want IT users to go to the IT Dashboard.
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 optionally 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 claim mappings. Map the groupid claim type to the value you want to assign the role to.
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.
This example takes advantage of OpenID Connect and Azure Active Directory.
Once you have configured PowerShell Universal and Azure Active Directory, you can configure role scripts to verify whether users are members of groups found in Azure AD. You can take advantage of claims mappings to map from the Azure AD Group ID to a PowerShell Universal role.
First, ensure that you have group membership claims enabled in the manifest for your application registration. This will include all group membership, so it is accessible in PowerShell Universal.
Once configured, you can update your role script to check for a group membership. First make note of the object ID of the group you are looking to check within Azure AD.
Next, within your roles.ps1 script, you can validate a user has a particular role by using claims mapping.
As users login, their group membership will be validated against their claims and a role will be assigned.
WS-Federation requires a .
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.
Here is an example of how to update the appsettings.json file to accommodate the correct settings for WS-Federation.
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.
You can configure WS-Federation authentication in the admin console. To do so, navigate to Security \ Authentication. Add the WS-Federation provider by selecting it from the drop down in the top right.
Next, edit the properties of the authentication provider and specify the configuration details for your ADFS setup.
Once configured, enable the WS-Federation provider. Then, log out and navigate to /admin You will be prompted to login to your WS-Federation provider.
SAML2 authentication for PowerShell Universal.
SAML2 requires a .
PowerShell Universal can be configured to integrate with a SAML2 identity provider. This documentation provides the details for configuring PSU with such a system.
You will need to configure your identity provider for the PowerShell Universal application. You will need to setup an acceptable entity ID and map attributes. PowerShell Universal requires that the name attribute is mapped. The attribute name needs to be the following.
You should map this to the user identity you wish to be used within PowerShell Universal.
Additional attributes can be mapped and will be available during . You will find an example of configuring Shibboleth below.
is required for SAML2 authentication.
There are several basic settings you can configure in the PowerShell Universal admin console. To add SAML2 support, click Security \ Authentication. In the top right corner, you can select SAML2 from the drop down.
Once the SAML2 integration has been added, you can configure the basic settings for communicating with your identity provider. You will need at least the Entity ID and Identity Provider Entity ID configured.
Typically, these entity IDs are URLs configured within your identity provider.
The service certificate is used for signing requests. It is not required. This can either be a path local to the PSU service or the distinguished name of a certificate installed in the Personal Computer Certificate store.
In addition to the settings available within the admin console, you can also set the following within the authentication.ps1 config file.
If you are using a file path for your certificate and it requires a password, you can specify it via the -ServiceCertificatePassword of Set-PSUAuthenticationMethod. The value of this parameter is a SecureString. You can take advantage of the SecretManagement module to load secrets.
The -Configure parameter is a script block that can be used to set additional settings not exposed by the Set-PSUAuthenticationMethod. The script block will be called when the provider is configured and will receive a single parameter that contains an object with the options for the SAML2 authentication.
You will need the following information from Azure AD.
Application (client) ID - Found on the Overview page.
Federation metadata document - Click Endpoints on the Overview page.
SAML-P sign-on endpoint - Click Endpoints on the Overview page.
Click Security \ Authentication.
Add SAML2 authentication provider.
Click the Edit Properties button.
For Entity ID, you will need to put the Azure AD application ID prefixed with spn:
For example: spn:2cf33625-e312-4659-a7bd-66ade51a0ea2
For Identity Provider Entity ID, you will need to retrieve the entity ID from the Federation metadata document. Open the document in a web browser.
For Metadata Address, insert the Federation metadata document URL.
For the Return URL, insert the URL of your PowerShell Universal server with the /Saml2/Acs path.
For Single Sign-On Service URL, insert the SAML-P sign-on endpoint from Azure.
Once complete, save the settings and enable the SAML provider. Click sign out and navigate to your admin console URL.
You will be forwarded to Azure for login and redirected back to PowerShell Universal after authentication.
Any errors that occur will be listed in the PowerShell Universal log. If you fail to login, you can navigate to /login to login with a local account.
This example shows how to configure Okta SAML2 authentication for use with PowerShell Universal.
Within Okta, you will need to configure your application similar to the following. HTTPS is required by SAML2, and you will need to include the URL for your PSU instance in the Single Sign On URL, followed by /Saml2/Acs. The path is case sensitive.
The Audience Restriction should be the URL of your PowerShell Universal server.
In order for your users to access PowerShell Universal, you will need to ensure they have been assigned to the Okta application.
Within the Sign On tab of your application, click the View SAML setup instructions button.
You will need to capture the two URLs and download the certificate for configuring PowerShell Universal. See the next step on how to use these URLs within the authentication.ps1 file.
The authentication.ps1 file is used for configuring PowerShell Universal.
This example shows how to configure Shibboleth for use with PowerShell Universal. It provides the very basic configuration and does not necessarily follow best practices.
This assumes that you have installed Shibboleth Identity Provider v4 with Active Directory integration.
LDAP properties have been configured to authentication against the local domain using a Domain Administrator account. The LDAP URL has been configured and TLS has been disabled.
Below you will find the full example of the ldap.properties file.
The relying-party.xml file has been updated to enable open IdP. This means that any entity ID can communicate with the identity provider. You can also configure this to enforce specific entity IDs. The default configure has also been adjusted to use the SAML2.AttributeQuery bean.
The attribute-resolver.xml file has been updated to use the LDAPDirectory Data Connector. It loads the email address, given name, SN, and display name from Active Directory. It then maps the Principal Name, which will be the username of the user logging in, to the required claim type using an attribute encoder.
The attribute-filter.xml file has been updated to release several of the attributes mapped by the LDAPDirectory data connector as well as the user name that will be used as the identity within PowerShell Universal.
In Azure go to App registrations > (Select the app) > Token Configuration, and specify Groups assigned to the application.
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.
Follow the documentation for the Azure Active Directory configuration found on this .
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 page.
The object is of the type . The sub object of SPOptions can be found .
EntityId
This value should match what you put in Audience Restriction within Okta.
string
IdentityProviderEntityId
This is the value that was presented in the View SAML setup instructions page.
string
CallbackPath
This is the path that the user will be redirected to if no redirect path was provided
string
SigningKey
This is the certificate file that was downloaded on the View SAML setup instructions page.
string
SingleSignOnServiceUrl
This is the sign on URL that was provided on the View SAML setup instructions page.
string
