AD FS 2.0 for Windows PowerShell Common Concepts

Article
07/02/2012

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

The following sections explain concepts that are common to all cmdlets for Active Directory Federation Services (AD FS) 2.0 in Windows PowerShell and the resources that they represent.

Multiple identifiers for resources

There are certain AD FS 2.0 resources that can be identified by multiple parameters. For example, a claims provider trust can be uniquely identified by its friendly name, its Uniform Resource Identifier (URI), or any of its certificates. Similarly, a relying party trust can be identified by its name or URI.

Parameter sets in Windows PowerShell make it possible to identify the target object through any of its identifying parameters. For Get-<object> cmdlets, a parameter set is defined for each identifying parameter. Therefore, the following are two different supported command examples that can be used to validly identify a relying party trust:

Get-ADFSRelyingPartyTrust –Name SampleIDFXApp
Get-ADFSRelyingPartyTrust –Identifier https://SampleApp.SampleServer.org

Specifying both Name and Identifier parameters in a Get cmdlet for a relying party trust is not allowed. Therefore, the following would not be valid command syntax.

Get-ADFSRelyingPartyTrust –Name SampleIDFXApp –Identifier https://SampleApp.SampleServer.org

For Set-<object> cmdlets, parameter sets comprise one identifying parameter and all the writeable properties as common parameters. The identifying parameter has the prefix Target to distinguish it from the value being set.

Consequently, the following two cmdlets are supported. Each cmdlet is being used to set a new URI for a relying party trust. In the first cmdlet, a relying party trust is identified by its friendly name and the URI that is set. In the second cmdlet, a relying party trust is retrieved by its existing URI, and the value of the URI is being updated.

Set-ADFSRelyingPartyTrust –TargetName SampleIDFXApp -Identifier  https://SampleApp.SampleServerNew.org

Set-ADFSRelyingPartyTrust –TargetIdentifier https://SampleApp.SampleServer.org -Identifier https://SampleApp.SampleServerNew.org

Set-<object> cmdlets also support the use of a relying party trust object as the identifying parameter. For more information, see the section entitled "Managing trust partner settings" in AD FS 2.0 for Windows PowerShell Examples.

Viewing resources

A Get- call on a resource—when it is invoked without any identifying parameter—lists all instances of that resource. For example, at a Windows PowerShell command prompt, type the following command to list all trust relationships with a claims provider trust or a relying party trust, respectively:

Get-ADFSClaimProviderTrust
Get-ADFSRelyingPartyTrust

Disabling and enabling resources

You can disable resources, such as endpoints, without losing configuration details. You can then enable them again at a later time. To disable these resources, you can use the supported Disable- cmdlets that AD FS 2.0 provides. (See the following example.)

Disable-ADFSEndpoint -TargetAddress /adfs/services/trust/13/Windows

Objects for all cmdlets

All cmdlets, except for Get- cmdlets, support a parameter set in which the object type of the resource itself can be provided as an identifying parameter.

This makes it possible for scripts that use the piped output from Get- cmdlets to configure a resource. To refresh metadata for all the relying parties that have not been updated in the last 24 hours, type the following command:

Get-ADFSRelyingPartyTrust | Where-Object{ $_.LastUpdateTime  -le  (get-date).subtract((new-timespan –hours 24))} | Update-ADFSRelyingPartyTrust

In this example, the Update-ADFSRelyingPartyTrust cmdlet uses the ADFSRelyingPartyTrust object, which flows down the input/output pipeline as its identifying parameter.

Using .NET objects

Using .NET native objects can enable some very powerful operations through AD FS 2.0 in Windows PowerShell. For example, if you have a partner who has updated their claim set to accept a new claim type (such as https://newdomain.com/type1 instead of https://olddomain.com/type1), you can use a command, similar to the following, to modify the policy for this partner:

Note

For simplification, assume that, in the issue statement, the claim type always appears as issue(type="https://olddomain.com/type1", value="NewValue"). The example would then be as follows:

$rSet= (Get-ADFSClaimProviderTrust –name SamplePartner.com).ClaimRulesPolicy
$newRSet = $rSet -Replace 'issue\(type="https://olddomain.com/type1"','issue\(type="https://newdomain.com/type1"'
Set-ADFSClaimProviderTrust –TargetName SamplePartner.com –ClaimRulesPolicy $newRset

Using pipes

Cmdlets that accept another Windows PowerShell resource for AD FS 2.0 as input typically support the acceptance of that resource as part of an input pipe (by type or by property name).

To see a detailed list of pipe-enabled inputs for a cmdlet, get the full Help for the cmdlet. The following example gets the full Help for the Set-ADFSRelyingPartyTrust cmdlet:

Get-Help Set-ADFSRelyingPartyTrust -full

Partager via