PowerShell Universal provides enterprise security features to allow for integrating with existing authentication and authorization methods. It also includes fine grained Permissions that can restrict access the Admin Console for specific features.

Enterprise Security requires a Server or Enterprise license.

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.

Enable Client Certificate Authentication

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.

"Kestrel": {
  "Endpoints": {
    "HTTPS": {
      "Url": "https://*:5000",
      "ClientCertificateMode": "RequireCertificate",
      "Certificate": {
        "Subject": "localhost",
        "Store": "My",
        "Location": "LocalMachine",
        "AllowInvalid": "true"
      }
    }
  },
  "RedirectToHttps": "false"
},

Next, you will need to enable client certificate authentication.

"ClientCertificate": {
  "Enabled": "true"
},

Authorization

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.

param($User)

$User | ConvertTo-Json | Out-File .\user.txt

$true

You will receive information about the certificate within the user object similar to below.

{
  "Claims": [
    {
      "Type": "issuer",
      "Value": "CN=Cert1, OU=Cert2, O=Org, L=Scottsdale, S=Arizona, C=US",
      "ValueType": "http://www.w3.org/2001/XMLSchema#string",
      "Issuer": "LOCAL AUTHORITY",
      "Properties": "System.Collections.Generic.Dictionary`2[System.String,System.String]"
    },
    {
      "Type": "http://schemas.xmlsoap.org/ws/2005/05/identity/claims/thumbprint",
      "Value": "8D2212B6EA170A33055A5",
      "ValueType": "http://www.w3.org/2001/XMLSchema#base64Binary",
      "Issuer": "LOCAL AUTHORITY",
      "Properties": "System.Collections.Generic.Dictionary`2[System.String,System.String]"
    },
    {
      "Type": "http://schemas.xmlsoap.org/ws/2005/05/identity/claims/x500distinguishedname",
      "Value": "CN=*.cert.com, OU=Domain Control Validated",
      "ValueType": "http://www.w3.org/2001/XMLSchema#string",
      "Issuer": "LOCAL AUTHORITY",
      "Properties": "System.Collections.Generic.Dictionary`2[System.String,System.String]"
    },
    {
      "Type": "http://schemas.microsoft.com/ws/2008/06/identity/claims/serialnumber",
      "Value": "009D21369",
      "ValueType": "http://www.w3.org/2001/XMLSchema#string",
      "Issuer": "LOCAL AUTHORITY",
      "Properties": "System.Collections.Generic.Dictionary`2[System.String,System.String]"
    },
    {
      "Type": "http://schemas.xmlsoap.org/ws/2005/05/identity/claims/dns",
      "Value": "*.cert.com",
      "ValueType": "http://www.w3.org/2001/XMLSchema#string",
      "Issuer": "LOCAL AUTHORITY",
      "Properties": "System.Collections.Generic.Dictionary`2[System.String,System.String]"
    },
    {
      "Type": "http://schemas.xmlsoap.org/ws/2005/05/identity/claims/name",
      "Value": "*.cert.com",
      "ValueType": "http://www.w3.org/2001/XMLSchema#string",
      "Issuer": "LOCAL AUTHORITY",
      "Properties": "System.Collections.Generic.Dictionary`2[System.String,System.String]"
    }
  ],
  "Identity": {
    "Name": "*.cert.com"
  }
}

You can evaluate the the claims using the HasClaim method. The following is an example of checking the thumbprint of the certificate.

param($User)

$User.HasClaim('http://schemas.xmlsoap.org/ws/2005/05/identity/claims/thumbprint', '8D2212B6EA170A33055A5')

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 EntraID.

This document will outline the steps necessary to configure EntraID OpenID Connect and use it with Universal.

Configuring Azure Entra ID (Azure Active Directory)

Within the Azure Portal, navigate to your Entra ID blade. Next, click the Enterprise Application node and then click New application.

Next, click Create your own application.

Select a name for your application and select Register an application to integrate with Microsoft Entra ID.

In the Register an application page, define a redirect URI. This will be the URL of PowerShell Universal server that Entra ID will redirect the user to. This value is defined in the PowerShell Universal configuration file, appsettings.json.

Now that the application has been created, from the Enterprise Applications page, click Single sign-on and then Go to application. This will bring you to the application registration page.

Certificates and secrets and define a new secret. This will be used with the PowerShell Universal configuration file.

Now, we'll need to capture several points of information from the application to provide to PowerShell Universal. From the application's home page, save the Application (client) and directory (tenant) ID.

Claim Mapping

In order to provide group claims to PowerShell Universal, you will need to expose the group claims from your app registration. Click Token Configuration and then click Add groups claim.

After clicking Add groups claim, you will have the option to select which groups are provided. If you select All Groups, the groups claims will be provided to PowerShell Universal

If you select Groups assigned to the application, ensure that you check the Emit groups as role claims value. This setting requires a paid Entra ID plan.

To assign a group to your app registration, locate your app in Enterprise Applications and click User and Groups. Next, click Add User\Group and select the groups you would like assigned to your application.

Once you have the groups claim configured in Entra ID, you can then update PowerShell Universal claim mappings to the groups provided.

For each role you would like to assign to an Entra ID group, specify the Claim Type and Claim Value for that role. For example, I have a group in my environment with the ID 446832da-d4ad-4972-b0a2-eda736129928. The Claim Type for this object is http://schemas.microsoft.com/ws/2008/06/identity/claims/groups.

To assign this to the administrator group, I would do the following.

Users of this group would now be part of the Administrator role in PowerShell Universal.

Group Overages

For organizations that have users with many groups, you will want to limit the number of groups sent to PowerShell Universal. Sending large numbers of groups can exceed the size of the token and cause authorization failures. If you wish to limit the groups, select Groups assigned to the application.

To add groups to the application, navigate back to the Enterprise application's page and select Users and groups.

Click the Add user/group value to assign these groups to your application. When users login to PowerShell Universal, only these group claims will be provided.

To learn more about Group Overages, click here.

Configuring Universal for Entra ID

Use Appsettings.json

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.

    "OIDC": {
      "Enabled": "true",
      "CallbackPath": "/auth/signin-oidc",
      "ClientID": "<application ID>",
      "ClientSecret": "<client secret>",
      "Resource": "",
      "Authority": "https://login.microsoftonline.com/<directory ID>",
      "ResponseType": "code",
      "SaveTokens": "false",
      "GetUserInfo": false
    },

Use Authentication.ps1

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.

Delegated Access Tokens

You can use access tokens generated by an OIDC login for other services the user may have access to. Within your OIDC provider, like Entra ID, 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.

    "OIDC": {
  "Enabled": "true",
  "CallbackPath": "/auth/signin-oidc",
  "ClientID": "<clientID>",
  "ClientSecret": "<clientSecret>",
  "Resource": "https://manage.office.com/",
  "Authority": "https://login.microsoftonline.com/tenant",
  "ResponseType": "id_token token",
  "SaveTokens": "true",
  "UseTokenLifetime": true
},

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.

Connect-AzureAD
       [-AzureEnvironmentName <EnvironmentName>]
       [-TenantId <String>]
       -AadAccessToken <String>
       [-MsAccessToken <String>]
       -AccountId <String>
       [-LogLevel <LogLevel>]
       [-LogFilePath <String>]
       [-InformationAction <ActionPreference>]
       [-InformationVariable <String>]
       [-WhatIf]
       [-Confirm]
       [<CommonParameters>]

Refresh Tokens

You can configure Azure Active Directory and PowerShell Universal to provide refresh tokens for requesting new tokens if the access token expires. To do so, you will need to enable offline_access in your app registration.

When configuring PowerShell Universal, you need to request the offline_access scope and set SaveTokens to true and use the id_token response type.

"OIDC": {
    "Enabled": "true",
    "CallbackPath": "/auth/signin-oidc",
    "ClientID": "----",
    "ClientSecret": "---",
    "Resource": "https://graph.microsoft.com",
    "Authority": "https://login.microsoftonline.com/----",
    "ResponseType": "code id_token",
    "SaveTokens": "true",
    "CorrelationCookieSameSite": "",
    "UseTokenLifetime": true,
    "Scope": "openid profile groups offline_access",
    "GetUserInfo": false
},

Once configured, you can access the $RefreshToken variable in your scripts and apps.

Configuring Okta

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.

Configurating Universal for Okta

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.

    "OIDC": {
      "Enabled": "true",
      "CallbackPath": "/authorization-code/callback",
      "ClientID": "6f006906-643a-40fe-af00-9060cea5d6ef",
      "ClientSecret": "M~.rE56.md_MOpB2I5kwj_voFuX-i891N0",
      "Resource": "",
      "Authority": "https://poshtools.okta.com",
      "ResponseType": "code",
      "SaveTokens": "true",
      "CorrelationCookieSameSite": "",
      "UseTokenLifetime": true,
      "Scope": "openid profile groups",
      "GetUserInfo": true
    },

Role-Based Access

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.

param($User)

$UserInfo.groups -contains 'Administrators'

Delegated Access Tokens

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.

Invoke-RestMethod https://poshtools.okta.com/oauth2/v1/userinfo -Headers @{
    Authorization = "Bearer $AccessToken"
}

Viewing Claim Information

If you are unsure about what claim information is being sent to PowerShell Universal from your identity provider, you can use the View Claim Information button on the Security \ Roles page to view all the roles that have been provided to PSU from the remote system.

PowerShell Universal can be configured to integrate with a SAML2 identity provider. This documentation provides the details for configuring PSU with such a system.

Automatically Loading Metadata

PowerShell Universal provides a mechanism to load the metadata document directly from the SAML2 identity provider rather than manually providing configuration options. This will collect as much information as possible. The Entity ID will still need to be provided.

The callback path will be displayed at the top of the property's modal.

Manually Providing Values

Identity Provider Settings

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.

http://schemas.xmlsoap.org/ws/2005/05/identity/claims/name

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 role evaluation. You will find an example of configuring Shibboleth below.

Entity ID Settings

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.

Additional Settings

In addition to the settings available within the admin console, you can also set the following within the authentication.ps1 config file.

ServiceCertificatePassword

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.

Set-PSUAuthenticationMethod `
-Type "Saml2" `
-EntityId "http://psu.ironman.local/sp" `
-IdentityProviderEntityId 'https://ironman.local/idp' `
-MetadataAddress 'https://idp.ironman.local/idp/shibboleth' `
-CallbackPath "https://localhost:5000/" `
-ServiceCertificate cert.pfx `
-ServiceCertificatePassword (Get-Secret -Name 'certPassword')

Configure

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.

The object is of the type Saml2Options. The sub object of SPOptions can be found here.

Set-PSUAuthenticationMethod `
-Type "Saml2" `
-EntityId "http://psu.ironman.local/sp" `
-IdentityProviderEntityId 'https://ironman.local/idp' `
-MetadataAddress 'https://idp.ironman.local/idp/shibboleth' `
-Configure {
  $options = $args[0]
  $options.SPOptions.DiscoveryServiceUrl = 'https://idp.ironman.local/discovery'
}

Example: Entra ID

Setup an Entra ID Enterprise Application within Azure. You can find a step-by-step guide here. You will need to retrieve the application ID and the Federation metadata document as well as the SAML-P sign-on endpoint. Within your Application Registration, click the Endpoints button.

Step by Step

Within PowerShell Universal:

1. Click Security \ Authentication.

2. Add SAML2 authentication provider.

3. Click the Edit Properties button.

For Entity ID, you will need to put the Entra ID 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 URL 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 /Saml/Acs path.

https://localhost/Saml2/Acs

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.

https://localhost/admin

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.

Claim Mapping

In order to provide group claims to PowerShell Universal, you will need to expose the group claims from your app registration. Click Token Configuration and then click Add groups claim.

After clicking Add groups claim, you will have the option to select which groups are provided. If you select All Groups, the groups claims will be provided to PowerShell Universal

If you select Groups assigned to the application, ensure that you check the Emit groups as role claims value. This setting requires a paid Entra ID plan.

To assign a group to your app registration, locate your app in Enterprise Applications and click User and Groups. Next, click Add User\Group and select the groups you would like assigned to your application.

Once you have the groups claim configured in Entra ID, you can then update PowerShell Universal claim mappings to the groups provided.

For each role you would like to assign to an Entra ID group, specify the Claim Type and Claim Value for that role. For example, I have a group in my environment with the ID 446832da-d4ad-4972-b0a2-eda736129928. The Claim Type for this object is http://schemas.microsoft.com/ws/2008/06/identity/claims/groups.

To assign this to the administrator group, I would do the following.

Users of this group would now be part of the Administrator role in PowerShell Universal. If you selected a different SAML group property, the value may be different (e.g. sAMAccountName).

Group Overages

For organizations with many groups, you will want to limit the number of groups provided to PowerShell Universal. This can alleviate authorization issues that arise from having too many groups provide causing it to exceed limits within the application. Within the Enterprise application settings, click Single sign-on and then click the Edit button under Attributes & Claims.

Click the groups claim to view the options. The advanced options will allow you to filter the groups that are provided to the PowerShell Universal server. You can also configure group claims through the token configuration on the Application Registration for the Enterprise Application.

Example: Okta

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.

authentication.ps1

The authentication.ps1 file is used for configuring PowerShell Universal.

Set-PSUAuthenticationMethod -Type "Saml2" `
-EntityId "https://localhost:5001" `
-IdentityProviderEntityId "http://www.okta.com/exk5dvbyzgASPiOFp5d7" `
-CallbackPath "https://localhost:5001" `
-SigningKey "C:\Users\adamr\Downloads\okta.cert" `
-SingleSignOnServiceUrl "https://dev-36706648.okta.com/app/dev-36706648_psusaml_1/exk5dvbyzgASPiOFp5d7/sso/saml"

Example: Shibboleth

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

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.

# LDAP authentication (and possibly attribute resolver) configuration
# Note, this doesn't apply to the use of JAAS authentication via LDAP

## Authenticator strategy, either anonSearchAuthenticator, bindSearchAuthenticator, directAuthenticator, adAuthenticator
idp.authn.LDAP.authenticator=adAuthenticator

## Connection properties ##
idp.authn.LDAP.ldapURL=ldap://ironman.local:389
idp.authn.LDAP.useStartTLS                     = false
# Time in milliseconds that connects will block
#idp.authn.LDAP.connectTimeout                  = PT3S
# Time in milliseconds to wait for responses
#idp.authn.LDAP.responseTimeout                 = PT3S
# Connection strategy to use when multiple URLs are supplied, either ACTIVE_PASSIVE, ROUND_ROBIN, RANDOM
#idp.authn.LDAP.connectionStrategy               = ACTIVE_PASSIVE

## SSL configuration, either jvmTrust, certificateTrust, or keyStoreTrust
idp.authn.LDAP.sslConfig                       = jvmTrust
## If using certificateTrust above, set to the trusted certificate's path
idp.authn.LDAP.trustCertificates=%{idp.home}/credentials/ldap-server.crt
## If using keyStoreTrust above, set to the truststore path
idp.authn.LDAP.trustStore=%{idp.home}/credentials/ldap-server.truststore

## Return attributes during authentication
idp.authn.LDAP.returnAttributes=passwordExpirationTime,loginGraceRemaining,sn,mail

## DN resolution properties ##

# Search DN resolution, used by anonSearchAuthenticator, bindSearchAuthenticator
# for AD: CN=Users,DC=example,DC=org
idp.authn.LDAP.baseDN=CN=Users,DC=ironman, DC=local
idp.authn.LDAP.subtreeSearch                   = true
idp.authn.LDAP.userFilter=(sAMAccountName={user})
# bind search configuration
# for AD: idp.authn.LDAP.bindDN=adminuser@domain.com
idp.authn.LDAP.bindDN=administrator@ironman.local

# Format DN resolution, used by directAuthenticator, adAuthenticator
# for AD use idp.authn.LDAP.dnFormat=%s@domain.com
idp.authn.LDAP.dnFormat=%s@ironman.local

# pool passivator, either none, bind or anonymousBind
#idp.authn.LDAP.bindPoolPassivator                  = none

# LDAP attribute configuration, see attribute-resolver.xml
# Note, this likely won't apply to the use of legacy V2 resolver configurations
idp.attribute.resolver.LDAP.ldapURL=%{idp.authn.LDAP.ldapURL}
idp.attribute.resolver.LDAP.connectTimeout=%{idp.authn.LDAP.connectTimeout:PT3S}
idp.attribute.resolver.LDAP.responseTimeout=%{idp.authn.LDAP.responseTimeout:PT3S}
idp.attribute.resolver.LDAP.connectionStrategy=%{idp.authn.LDAP.connectionStrategy:ACTIVE_PASSIVE}
idp.attribute.resolver.LDAP.baseDN=%{idp.authn.LDAP.baseDN:undefined}
idp.attribute.resolver.LDAP.bindDN=%{idp.authn.LDAP.bindDN:undefined}
idp.attribute.resolver.LDAP.useStartTLS=%{idp.authn.LDAP.useStartTLS:true}
idp.attribute.resolver.LDAP.trustCertificates=%{idp.authn.LDAP.trustCertificates:undefined}
idp.attribute.resolver.LDAP.searchFilter=(sAMAccountName=$resolutionContext.principal)

# LDAP pool configuration, used for both authn and DN resolution
#idp.pool.LDAP.minSize                          = 3
#idp.pool.LDAP.maxSize                          = 10
#idp.pool.LDAP.validateOnCheckout               = false
#idp.pool.LDAP.validatePeriodically             = true
#idp.pool.LDAP.validatePeriod                   = PT5M
#idp.pool.LDAP.validateDN                       =
#idp.pool.LDAP.validateFilter                   = (objectClass=*)
#idp.pool.LDAP.prunePeriod                      = PT5M
#idp.pool.LDAP.idleTime                         = PT10M
#idp.pool.LDAP.blockWaitTime                    = PT3S

relying-party.xml

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.

<?xml version="1.0" encoding="UTF-8"?>
<beans xmlns="http://www.springframework.org/schema/beans"
       xmlns:context="http://www.springframework.org/schema/context"
       xmlns:util="http://www.springframework.org/schema/util"
       xmlns:p="http://www.springframework.org/schema/p"
       xmlns:c="http://www.springframework.org/schema/c"
       xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
       xsi:schemaLocation="http://www.springframework.org/schema/beans http://www.springframework.org/schema/beans/spring-beans.xsd
                           http://www.springframework.org/schema/context http://www.springframework.org/schema/context/spring-context.xsd
                           http://www.springframework.org/schema/util http://www.springframework.org/schema/util/spring-util.xsd"
                           
       default-init-method="initialize"
       default-destroy-method="destroy">

    <!--
    Unverified RP configuration, defaults to no support for any profiles. Add <ref> elements to the list
    to enable specific default profile settings (as below), or create new beans inline to override defaults.
    
    "Unverified" typically means the IdP has no metadata, or equivalent way of assuring the identity and
    legitimacy of a requesting system. To run an "open" IdP, you can enable profiles here.
    -->
    <bean id="shibboleth.UnverifiedRelyingParty" parent="RelyingParty">
        <property name="profileConfigurations">
            <list>
			<bean parent="SAML2.SSO" p:encryptAssertions="false" />
            </list>
        </property>
    </bean>

    <!-- Default configuration, with default settings applied for all profiles. -->
    <bean id="shibboleth.DefaultRelyingParty" parent="RelyingParty">
        <property name="profileConfigurations">
            <list>
                <!-- SAML 1.1 and SAML 2.0 AttributeQuery are disabled by default. -->
                <!--
                <bean parent="Shibboleth.SSO" />
                <ref bean="SAML1.AttributeQuery" />
                <ref bean="SAML1.ArtifactResolution" />
                -->
                <bean parent="SAML2.SSO" />
                <ref bean="SAML2.ECP" />
                <ref bean="SAML2.Logout" />
                <ref bean="SAML2.AttributeQuery" />
                <ref bean="SAML2.ArtifactResolution" />
                <ref bean="Liberty.SSOS" />
            </list>
        </property>
    </bean>
</beans>

attribute-resolver.xml

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.

<?xml version="1.0" encoding="UTF-8"?>
<!--
    This file is an EXAMPLE configuration file containing some example attributes
    based on some commonly used approaches when LDAP is the principal data source.
     
    Not all attribute definitions or data connectors are demonstrated, but some
    LDAP attributes common to Shibboleth deployments (and some not so common) are
    included.

    This example is in no way usable as a substitute for reading the documentation.    
-->
<AttributeResolver
        xmlns="urn:mace:shibboleth:2.0:resolver"
        xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
        xsi:schemaLocation="urn:mace:shibboleth:2.0:resolver http://shibboleth.net/schema/idp/shibboleth-attribute-resolver.xsd">

    <!-- ========================================== -->
    <!--      Attribute Definitions                 -->
    <!-- ========================================== -->

    <!-- Simple attributes are exported directly from the LDAP connector. -->

    <AttributeDefinition id="uid" xsi:type="PrincipalName" />
    <AttributeDefinition id="username" xsi:type="PrincipalName">
         <AttributeEncoder xsi:type="SAML2String" name="http://schemas.xmlsoap.org/ws/2005/05/identity/claims/name" friendlyName="displayName" encodeType="false" />
    </AttributeDefinition>

    <!-- ========================================== -->
    <!--      Data Connectors                       -->
    <!-- ========================================== -->

    <!-- Example LDAP Connector -->

    <DataConnector id="myLDAP" xsi:type="LDAPDirectory"
        ldapURL="%{idp.attribute.resolver.LDAP.ldapURL}"
        baseDN="%{idp.attribute.resolver.LDAP.baseDN}" 
        principal="%{idp.attribute.resolver.LDAP.bindDN}"
        principalCredential="%{idp.attribute.resolver.LDAP.bindDNCredential}"
        useStartTLS="%{idp.attribute.resolver.LDAP.useStartTLS:true}"
        connectTimeout="%{idp.attribute.resolver.LDAP.connectTimeout}"
        responseTimeout="%{idp.attribute.resolver.LDAP.responseTimeout}"
        connectionStrategy="%{idp.attribute.resolver.LDAP.connectionStrategy}"
        noResultIsError="true"
        multipleResultsIsError="true"
        excludeResolutionPhases="c14n/attribute"
        exportAttributes="mail displayName sn givenName">
        <FilterTemplate>
            <![CDATA[
                %{idp.attribute.resolver.LDAP.searchFilter}
            ]]>
        </FilterTemplate>
        <ConnectionPool
            minPoolSize="%{idp.pool.LDAP.minSize:3}"
            maxPoolSize="%{idp.pool.LDAP.maxSize:10}"
            blockWaitTime="%{idp.pool.LDAP.blockWaitTime:PT3S}"
            validatePeriodically="%{idp.pool.LDAP.validatePeriodically:true}"
            validateTimerPeriod="%{idp.pool.LDAP.validatePeriod:PT5M}"
            validateDN="%{idp.pool.LDAP.validateDN:}"
            validateFilter="%{idp.pool.LDAP.validateFilter:(objectClass=*)}"
            expirationTime="%{idp.pool.LDAP.idleTime:PT10M}"/>
    </DataConnector>

</AttributeResolver>

attribute-filter.xml

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.

<?xml version="1.0" encoding="UTF-8"?>
<!-- 
    This file is an EXAMPLE policy file.  While the policy presented in this 
    example file is illustrative of some simple cases, it relies on the names of
    non-existent example services and the example attributes demonstrated in the
    default attribute-resolver.xml file.

    This example does contain some usable "general purpose" policies that may be
    useful in conjunction with specific deployment choices, but those policies may
    not be applicable to your specific needs or constraints.    
-->
<AttributeFilterPolicyGroup id="ShibbolethFilterPolicy"
        xmlns="urn:mace:shibboleth:2.0:afp"
        xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
        xsi:schemaLocation="urn:mace:shibboleth:2.0:afp http://shibboleth.net/schema/idp/shibboleth-afp.xsd">

<AttributeFilterPolicy id="example1">
        <PolicyRequirementRule xsi:type="ANY" />
        <AttributeRule attributeID="username">
            <PermitValueRule xsi:type="ANY" />
        </AttributeRule>
        <AttributeRule attributeID="displayName">
            <PermitValueRule xsi:type="ANY" />
        </AttributeRule>
        <AttributeRule attributeID="uid">
            <PermitValueRule xsi:type="ANY" />
        </AttributeRule>
        <AttributeRule attributeID="mail">
            <PermitValueRule xsi:type="ANY" />
        </AttributeRule>
        <AttributeRule attributeID="sn">
            <PermitValueRule xsi:type="ANY" />
        </AttributeRule>
    </AttributeFilterPolicy>
 


</AttributeFilterPolicyGroup>

WS-Federation supports both Active Directory Federation Services and Azure Active Directory.

You first need to configure ADFS or AzureAD to support Universal.

Configuring ADFS for Universal

Service Settings

First, you will need to gather the Federation Service Properties from ADFS. Open the AD FS app (Microsoft.IdentityServer.msc). Next, click Service and then Edit Federation Service Properties.

This will open a dialog with the values for your ADFS service. You will need these values for configuring PowerShell Universal.

Relying Parties

If you have no Reply Party Trusts configured, click Add Replying Party Trust. Select Claims aware.

Select Enter data about the relying party manually.

Specify a name for the relying party.

Enable WS-Federation Passive protocol. Enter the PowerShell Universal server URL with a trailing slash.

Enter the URL of your PowerShell Universal server.

After finishing your Replying Party Trust configuration, you will need to setup a Claim Issuance Policy. Create an Issuance Transform Rule that sends at least the Name and Name ID to Universal.

You can configure additional claims you'd like to use if you are using policies in Universal.

Troubleshooting

MSIS7065: There are no registered protocol handlers on path /adfs/ls to process the incoming request.

This issue can be caused if the IDP Initiated Sign On page is disabled. This is the default. Run the following command from an administrative console.

 Set-AdfsProperties -EnableIdPInitiatedSignonPage $true

MSIS7001: The passive protocol context was not found or not valid. If the context was stored in cookies, the cookies that were presented by the client were not valid. Ensure that the client browser is configured to accept cookies from this website and retry this request.

Configuring For Azure Active Directory

Follow the documentation for the Azure Active Directory configuration found on this Microsoft Document.

Configuring Universal

Use Appsettings.json

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.

{
  "Kestrel": {
    "Endpoints": {
      "HTTP": {
        "Url": "http://*:5000"
      }
    },
    "RedirectToHttps": "false"
  },
  "ApplicationInsights": {
    "InstrumentationKey": ""
  },
  "Logging": {
    "Path": "%PROGRAMDATA%/PowerShellUniversal/log.txt",
    "RetainedFileCountLimit": 31,
    "LogLevel": {
      "Default": "Information",
      "Microsoft": "Warning",
      "Microsoft.Hosting.Lifetime": "Information"
    }
  },
  "AllowedHosts": "*",
  "CorsHosts": "",
  "Data": {
    "RepositoryPath": "%ProgramData%\\UniversalAutomation\\Repository",
    "ConnectionString": "%ProgramData%\\UniversalAutomation\\database.db",
    "GitRemote": "",
    "GitUserName": "",
    "GitPassword": "", 
    "ConfigurationScript": ""
  },
  "Api": {
    "Url": ""
  },
  "Authentication" : {
    "Windows": {
      "Enabled": "false"
    },
    "WSFed": {
        "Enabled": "true",
        "MetadataAddress": "https://ironman.local:443/FederationMetadata/2007-06/FederationMetadata.xml",
        "Wtrealm": "https://ironman.local:12345",
        "CallbackPath": "/auth/signin-wsfed"
    },
    "OIDC": {
      "Enabled": "false",
      "CallbackPath": "/auth/signin-oidc",
      "ClientID": "",
      "ClientSecret": "",
      "Resource": "",
      "Authority": "",
      "ResponseType": "",
      "SaveTokens": "false"
    },
    "SessionTimeout": "25"
  },
  "Jwt": {  
    "SigningKey": "PleaseUseYourOwnSigningKeyHere",  
    "Issuer": "IronmanSoftware",
    "Audience": "PowerShellUniversal"
  },
  "UniversalDashboard": {
    "AssetsFolder": "%ProgramData%\\PowerShellUniversal\\Dashboard"
  },
  "ShowDevTools": false,
  "HideAdminConsole": false
}

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.

Use Authentication.ps1

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.

Windows Authentication, also know as Negotiate authentication, uses Kerberos or NTLM to authenticate without prompting the user for a password. It is primarily supported on Windows domains but can be configured in Linux and Mac OS.

appsettings.json

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.

"Windows": {
  "Enabled": "true"
},

Authentication.ps1

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.

Windows Authentication in IIS

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.

<aspNetCore processPath="Universal.Server.exe" arguments="" forwardWindowsAuthToken="true" stdoutLogEnabled="true" stdoutLogFile=".\logs\log" hostingModel="OutOfProcess"/>

Windows Authentication outside of IIS

Windows Authentication is supported outside of IIS but requires configuration of the account running the Universal service.

Windows

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.

"Windows": {
  "Enabled": "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.

setspn -S HTTP/myservername.mydomain.com myuser

For more information, you can follow the Microsoft documentation for configuring ASP.NET Core Windows Authentication: Configuring a Windows machine for Windows Authentication

Linux

Configuring a Linux or Mac OS machine for Windows Authentication

Cached Claims

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.

Browser Configuration

Depending on your local environment, you may need to configure your browser to properly pass credentials to PowerShell Universal.

• Google Chrome

• Microsoft Edge

PowerShell Universal leverages permissions throughout the platform to provide fine-grained authorization against different scopes and resources. Built-in roles have a read-only set of permissions that are automatically applied to users with those roles. Custom roles can have custom permissions set. Additionally, individual users can have their own set of permissions.

Permissions are stored in the database and not as part of the .universal configuration files.

Permission Identifiers

Each permission uses an identifier to authorize a user to access a resource. They are strings that utilize the scope and resource type, followed by an access type.

For example, the following would provide read access to all API features.

apis/read

Wildcards can be used in permission identifiers to include sub-scopes over multiple access types. The following provides access to all script features.

automation.scripts/*

Managing Permissions

Permissions can be managed for an identity by clicking Security \ Permissions. You can select the identity and define a permission identifier to grant to the identity. This will blend with the permissions granted by any role assignments they may have.

Roles currently cannot be assigned permissions in the permission UI.

Example: Scheduler Role

In this example, we'll define a role that can only manage schedules.

First, create a role name Scheduler. This can be done in the Admin Console by clicking Security \ Roles and then Create New Role. Set the role name and click Ok.

Next, define the following permission for the role. Click the Properties button on the Scheduler role. This grants full access to scheduling and read access to automation.

• automation.schedules/*

• automation/read

The resulting role definition is below.

New-PSURole -Name "Scheduler" -Permission @('automation.schedules/*', 'automation/read') 

Finally, assign the role to a user. You can do so statically, with a policy script or via role to claim mapping.

Default Role Permissions

Below are the default role permissions.

Administrator

Operator

Execute

Reader

API Editor

API Reader

App Editor

App Reader