AD FS 2.0 for Windows PowerShell Examples

Applies To: Active Directory Federation Services (AD FS) 2.0

This topic provides examples of Windows PowerShell commands that you can use to configure and administer Active Directory Federation Services (AD FS) 2.0.

Configuring AD FS 2.0 federation service properties with Windows PowerShell

You can configure your federation server by using the New and Set operations on the AD FS 2.0 server properties resources.

For example, to update the organization name and contact information that is published in the AD FS 2.0 configuration metadata, you can use the following cmdlet at the Windows PowerShell command prompt:

$orgInfo = New-ADFSOrganization -DisplayName Fabrikam -OrganizationUrl https://fabrikam.com
Set-ADFSProperties -OrganizationInfo $orgInfo

Another property that you might find useful to update is the logging level. For example, to set the log level for the federation server to enable logging of warnings and failure audits, you can use the Set-ADFSProperties cmdlet, as follows:

Set-ADFSProperties -LogLevel  "Warnings", "FailureAudits" -Force

As an alternative, you can explicitly provide an array, as follows:

Set-ADFSProperties -LogLevel  @("Warnings", "FailureAudits") -Force

Similarly, you can set the global interval for monitoring metadata for trust partners in hours, as follows:

Set-ADFSProperties -PartnerMonitoringInterval 24

For a full list of all the AD FS 2.0 property settings, see the cmdlet Help for Set-ADFSProperties. To get the Help, type the following command at the Windows PowerShell command prompt:

get-help Set-ADFSProperties

Reviewing AD FS 2.0 federation service properties with Windows PowerShell

You can review all the global settings for AD FS 2.0 by using the Get-ADFSProperties cmdlet. For example, to review current settings, type the cmdlet as follows:

 Get-ADFSProperties

To obtain the metadata for AD FS 2.0, you can retrieve the actual metadata, as follows, using .NET helper classes:

$mUrl = (Get-ADFSEndpoint | where ($_.Protocol -eq "FederationMetadata")).FullUrl.ToString()
$httpHelper = new-object System.Net.WebClient
$metadataAsString = $httpHelper.DownloadString($mUrl)

Alternately, you can then download the metadata to a file, as follows:

$httpHelper.DownloadFile($mUrl , "C:\metadata.xml")

Managing AD FS 2.0 attribute stores with Windows PowerShell

You can manage attribute stores in AD FS 2.0 by using the ADFSAttributeStore resource at the Windows PowerShell command prompt. For example, to add a SQL-based attribute store, type the following command:

Add-ADFSAttributeStore -name 'LocalSqlStore' –StoreType 'SQL' -Configuration @{"Connection" = "Server=CONTOSOSRV01;Database=UserAttributes;Integrated Security=True"}

You can also define your own attribute store by providing an assembly reference to it. The following example shows how to configure a custom attribute store named MyCustomStore:

Add-ADFSAttributeStore -Name 'MyCustomStore' –TypeQualifiedName 'Contoso.CustomTypes.MyAttributeStore, Contoso.CustomTypes' –Configuration @{"Connection" = "Default"}

You can update the settings for this custom attribute store by using the Set-ADFSAttributeStore cmdlet, as follows:

Set-ADFSAttributeStore –TargetName 'MyCustomStore' -Configuration @("runmode" = "verbose"; configParaName2 = configParaValueNew)

To view the settings for this custom attribute store, you can then use the Get-ADFSAttributeStore cmdlet, as follows:

Get-ADFSAttributeStore  -Name "MyCustomStore"

Managing AD FS 2.0 certificates with Windows PowerShell

You can use the ADFSCertificate cmdlets to manage certificates for AD FS 2.0 at the Windows PowerShell command prompt.

For example, to configure a certificate for token signing, add a reference to a local certificate and then use that reference to set the certificate for the federation server. The following script uses the certificate navigation provider that is implemented in Windows PowerShell.

To add the certificate reference, you use the Add-ADFSCertificate cmdlet, as follows:

cd cert:
$certlist = ls .\LocalMachine\My
Add-ADFSCertificate -CertificateType "Token-Signing" –Thumbprint $certlist[5].thumbprint

You can retrieve and view properties for the certificates that you have configured by using the Get-ADFSCertificate cmdlet, as follows:

$certList = Get-ADFSCertificate -CertificateType "Token-Signing"

Managing AD FS 2.0 endpoints with Windows PowerShell

You can manage endpoints by using operations on the ADFSEndpoint cmdlet resources. For example, to view endpoint properties for an endpoint with the /adfs/services/trust/2005/certificate path, use the following command at the Windows PowerShell prompt:

Get-ADFSEndpoint –Address /adfs/services/trust/2005/certificate

To set a certain endpoint to be available outside the AD FS 2.0 security realm, type the following command:

Set-ADFSEndpoint –Address /adfs/services/trust/2005/certificate –Proxy $true

You can use the following commands to enable or disable endpoints, as follows:

Enable-ADFSEndpoint –Address /adfs/services/trust/2005/certificate
Disable-ADFSEndpoint –Address /adfs/services/trust/2005/certificate

To retrieve an endpoint object for a specific protocol, use the following command:

Get-ADFSEndpoint | where ($_.Protocol -eq "Federation Metadata")

Managing AD FS 2.0 proxy settings with Windows PowerShell

To establish trust between the AD FS 2.0federation server proxy and the AD FS 2.0federation server, the administrator must use the AD FS 2.0 Proxy Configuration Wizard on the federation server proxy. Once configured using the wizard, you can manage the relationship on the federation server side by using the ADFSProperties resource.

$p = Get-ADFSProperties
$p. AddProxyAuthorizationRules
Set-ADFSProperties –AddProxyAuthorizationRules (cat myProxyRules.txt)

To manage the relationship on the federation server proxy side, you manage proxy properties with the ADFSProxyProperties resource.

Get-ADFSProxyProperties
Set-ADFSProxyProperties –HttpPort 80

Managing AD FS 2.0 trust partners with Windows PowerShell

Trust partners in AD FS 2.0 can be either claim providers or relying parties. You can use AD FS 2.0 cmdlets that are specific to each of these types of partners to manage them at the Windows PowerShell command prompt in the following ways:

• Add trust partners

• Add SAML 2.0 federation trust partners

• Manage trust partner settings

• Configure claim types and AD FS 2.0 server policy

• Manage policy using more complex sets of stored rules

• Monitor partner metadata

Adding trust partners

Multiple parameters sets are supported for adding trust partners. To create a trust partner named Fabrikam by importing metadata from a URL, use the following command:

Add-ADFSRelyingPartyTrust –Name 'Fabrikam' –MetadataURL 'https://fabrikam.com/federationmetadata/2007-06/federationmetadata.xml'

To create a trust partner named Fabrikam by importing metadata from a file, use the following command:

Add-ADFSClaimProviderTrust –Name 'Fabrikam' –MetadataFile 'C:\metadata.xml'

To create a trust partner named Fabrikam by entering data manually, use the following command:

$cert = Get-PfxCertificate "C:\IPcert.cer"
Add-ADFSClaimProviderTrust –Name 'Fabrikam' –SigningCerts $cert -IdentifierUri 'https://fabrikam.com'

You can add an identity provider in a similar manner. If you add a relying party by using a metadata file or a metadata URL, you can review its SAML endpoints and requested claim types, as follows:

(Get-ADFSRelyingPartyTrust –name 'Fabrikam').SamlEndpoints
(Get-ADFSRelyingPartyTrust –name 'Fabrikam').Claims

You can use the requested claims to set an appropriate issuance policy for the federation server.

Add SAML 2.0 federation trust partners

To create a federation trust with a custom or third party SAML 2.0 partner you can use the New-ADFSSamlEndpoint cmdlet together with the Set-ADFSRelyingPartyTrust cmdlet to add and configure the appropriate SAML 2.0 endpoints for an existing relying party trust

For example, the following command sequence uses New-ADFSSamlEndpoint to create four SAML 2.0 endpoints for a custom SAML 2.0 federation server at https://samlsts1.contoso.com:

$samlEndpoint1 = New-ADFSSamlEndpoint -Protocol 'SAMLAssertionConsumer' -Uri 'https://samlsts1.contoso.com/samlprp-0/' -Binding 'POST' -IsDefault $false -Index 0
$samlEndpoint2 = New-ADFSSamlEndpoint -Protocol 'SAMLAssertionConsumer' -Uri ''https://samlsts1.contoso.com/samlprp-0/samlprp-0/Consumer.aspx' -Binding 'POST' -IsDefault $true -Index 1
$samlEndpoint3 = New-ADFSSamlEndpoint -Protocol 'SAMLLogout' -Uri ''https://samlsts1.contoso.com/samlprp-0/Logout.aspx' -ResponseUri ''https://samlsts1.contoso.com/samlprp-0/LogoutResponse.aspx' -Binding 'Redirect'
$samlEndpoint4 = New-ADFSSamlEndpoint -Protocol 'SAMLLogout' -Uri ''https://samlsts1.contoso.com/samlprp-0/Logout.aspx' -ResponseUri ''https://samlsts1.contoso.com/samlprp-0/LogoutResponse.aspx' -Binding 'POST'

You can then use the use the Set-ADFSRelyingPartyTrust cmdlet to add and set these endpoints for an existing relying party trust.

Set-ADFSRelyingPartyTrust -TargetName samlpsite3-0 -SamlEndpoint @($samlEndpoint1, $samlEndpoint2, $samlEndpoint3, $samlEndpoint4)

Once you have set the SAML endpoints, you can return the endpoints and their URI settings for them as follows:

$rp = Get-ADFSRelyingPartyTrust –Name 'Fabrikam'
$rp.SamlEndpoints
$rp.SamlEndpoints.Location

Managing trust partner settings

You can use Set cmdlets for managing the settings of a relying party, as shown in the following example:

Set-ADFSRelyingPartyTrust -TargetName 'Fabrikam' –Identifier 'https://uri1.appserver.com'

Set-ADFSRelyingPartyTrust -TargetName SampleApp -Identifier  "https://uri1.appserver.com" ,  "https://uri2.appserver.com"

The mechanism for removing identifiers or other settings stored in arrays is as follows:

$rp     = Get-ADFSRelyingPartyTrust –name 'Fabrikam'
$uris   = [System.Collections.ArrayList] $rp.Identifier
$uris.remove("https://uri1.appserver.com")
Set-ADFSSRelyingPartyTrust –TargetName 'Fabrikam' –Identifier $uris.ToArray

Configuring claim types and AD FS 2.0 server policy

You can view the claim types that the trust partner requires and then set the claim issuance policy accordingly.

(Get-ADFSRelyingPartyTrust –Name 'Fabrikam').Claims | where-object {$_.IsRequired}

Manage policy with the AD FS 2.0 claims language

You can apply a policy that is stored in a file directly to a trust relationship, as follows:

Set-ADFSRelyingPartyTrust –Name Fabrikam –IssuanceTransformRulesFile 'C:\ADFSClaimRuleSet.txt'

You can set a policy containing a single rule, as follows:

Set-ADFSRelyingPartyTrust –name Fabrikam -IssuanceTransformRules 'issue(type = "origin", value = "Microsoft");'

To further facilitate policy definition through the AD FS 2.0 policy language, you can use the auxiliary resource ADFSClaimRuleSet. The following example adds a simple set of rules:

$rp = Get-ADFSRelyingPartyTrust -name Fabrikam
$rules = (New-ADFSClaimRuleSet -ClaimRule $rp.ClaimRulesPolicy).ClaimRules
$rules + 
'c:[type == "Name"] => issue(type = "Greeting", value = "Hello " + c.value);'
$rSet = New-ADFSClaimRuleSet –ClaimRules $rules
Set-ADFSRelyingPartyTrust –TargetName Fabrikam –ClaimRulesPolicy $rSet.ClaimRulesString

You can also create ADFSClaimRuleSet from a file for editing by using the following command:

$rSet = New-ADFSClaimRuleSet -ClaimRuleFile 'C:\ruleset.txt'

You can also initialize ADFSClaimRuleSet directly by providing the policy text, as follows:

$rSet = New-ADFSClaimRuleSet –ClaimRule 'exists([issuer == "MSFT"]) => issue(type = "origin", value = "Microsoft"); c:[type == "Name"] => issue(type = "Greeting", value = "Hello " + c.value);'

Monitor partner metadata

You can control automated monitoring and updating of metadata information for a trust partner by using cmdlet options. For example, the following command turns automatic monitoring on but turns automatic updates off:

Set-ADFSRelyingPartyTrust –TargetName 'Fabrikam' –MonitoringEnabled $true –AutoUpdateEnabled $false

Later, you can trigger an on-demand automatic update of the metadata for this partner (Fabrikam), as follows:

Update-ADFSRelyingPartyTrust –TargetName 'Fabrikam'