AD FS 2.0 for Windows PowerShell Cmdlets Overview
Applies To: Active Directory Federation Services (AD FS) 2.0
The Active Directory Federation Services (AD FS) 2.0 snap-in for Windows PowerShell provides a set of resources that you can use to configure or administer a federation server or federation server proxy. A resource is implemented as an object type that is used to derive one or more cmdlets. Cmdlets are formed by pairing various standard “verb” actions that are supported by each resource.
Viewing properties of resources
All AD FS 2.0 cmdlets return the object type of the resource on which the cmdlet operates. Therefore, to view the full list of properties (data members and methods) that are supported on a particular resource, you can use the Get-Member cmdlet on any cmdlet for that resource. The format of the command that you use to view properties for any resource is as follows:
<verb>-<resource> | Get-Member
For example, to view the members for the
ADFSRelyingPartyTrust resource, type the following command:
Get-ADFSRelyingPartyTrust | Get-Member
Some cmdlets might require you to supply mandatory parameters.
The following sections provide a brief overview of each Windows PowerShell resource that AD FS 2.0 provides.
This resource enables administration of trust relationships with relying parties. Relying parties are entities or organizations that rely on claims providers such as AD FS 2.0 for claims.
You can add or remove a new relying party trust relationship by using the Add-ADFSRelyingPartyTrust and Remove-ADFSRelyingPartyTrust cmdlets. You can establish the trust relationship by either importing the trust partner’s metadata (from a file or URL) or using the Set-ADFSRelyingPartyTrust cmdlet to configure each of the properties manually.
You can also enable or disable the trust partner, without losing its configuration, by using the corresponding cmdlets, Enable-ADFSRelyingPartyTrust and Disable-ADFSRelyingPartyTrust. This resource also supports the Update-ADFSRelyingPartyTrust cmdlet. If a metadata URL for the trust partner is set, calling the update causes the federation server to pull the metadata and refresh the configuration information (for example, for certificates, endpoints, and claim types) that is available in the metadata.
This resource enables administration of trust relationships with other entities or organizations that act as claims providers to the federation server. The cmdlets for this resource are similar to the cmdlets for ADFSRelyingPartyTrust.
You can use this resource for managing the attribute stores that AD FS 2.0 supports, including adding (Add-ADFSAttributeStore), removing (Remove-ADFSAttributeStore), configuring (Set-ADFSAttributeStore), and inspecting (Get-ADFSAttributeStore) the properties of an attribute store.
The Add-ADFSAttributeStore cmdlet supports two parameter sets. AD FS 2.0 has built-in support for using Active Directory, Lightweight Directory Access Protocol (LDAP) or Structured Query Language (SQL) as attribute stores. You can create these stores with the Add-ADFSAttributeStore cmdlet by specifying a store type.
With AD FS 2.0, you can use custom attributes as well. You can create custom attributes by specifying an assembly reference for the attribute store as the value of the TypeQualifiedName parameter when you use the Add-ADFSAttributeStore cmdlet.
You can use this resource for managing the claim types that AD FS 2.0 supports, including configuring the properties of a claim, such as whether it is an accepted claim or an emitted claim, whether it is required or optional, and so on.
The ADFSClaimDescription resource provides access to the collection of claims that are published in AD FS 2.0 metadata. The issuance rules for these claims is not set through this resource. The issuance rules are specific to a trust partner. Therefore, the rules are set on the corresponding ADFSRelyingPartyTrust or ADFSClaimsProviderTrust resource.
You can use this resource for managing the endpoints that AD FS 2.0 exposes. The bindings for the endpoints are predefined, and they cannot be changed. However, you can use this resource to configure which endpoints are enabled and whether or not they will be available.
You can use this resource for managing the certificates for which AD FS 2.0 has the private keys. Partner certificates are managed through the relevant trust partner resource, that is, ADFSRelyingPartyTrust or ADFSClaimsProviderTrust.
You can add or update one or more certificates for different functions, such as token-signing, decryption, and others. The AutoCertificateRollover property of the ADFSProperties resource can be used to control if certificate rollover is performed automatically by the Federation Service or if manual rollover is required. If this property is enabled, you can no longer change certificates as AD FS 2.0 manages them instead and will block any attempt to access certificates to administer them manually.
You can use this resource to maintain the properties of a federation server proxy. This resource can only be used on the AD FS 2.0 federation server proxy, where the rest of the commands are invalid, since they run on the AD FS 2.0 federation server.
This resource collects all global configuration settings for a federation server. For a full list of the properties that are supported, you can inspect the ADFSProperties object by using Get-Member.
ADFSClaimRuleSet is one of the seven auxiliary resources that are supported by the Windows PowerShell snap-in for AD FS 2.0. This resource does not correspond directly to an administrative setting. However, it helps make management of the core Federation Service easier by providing convenience functions.
For flexibility, the ADFSRelyingPartyTrust and ADFSClaimsProviderTrust resources have a generic interface for configuring a policy that takes a string or a text file.
The AD FS 2.0 policy language is a collection of rules that are executed sequentially to issue or process claims. The ADFSClaimRuleSet resource is a convenience resource that is optimized for authoring and updating policy. The policy as it is authored can be piped directly to the Set cmdlets for ADFSRelyingPartyTrust and ADFSClaimProviderTrust.
ADFSClaimRuleSet is essentially an ordered collection of rules to which you can append rules, insert rules at a specified index, or remove a particular rule at an index.
Convenience methods for serialization and deserialization of ADFSClaimRuleSet are supported. The New-ADFSClaimRuleSet cmdlet supports the creation of ADFSClaimRuleSet from a file, while an existing ADFSClaimRuleSet can be converted to a string, which in turn can be written to a file or passed to a cmdlet. Like all other auxiliary resources in the AD FS 2.0 snap-in for Windows PowerShell, the ADFSClaimRuleSet resource is not persisted. Therefore, no Get cmdlets are supported. Any manipulation of the resource after its creation must occur on the pipeline. All cmdlets that accept or manipulate ADFSClaimRuleSet accept it as input that can be piped.
This resource encapsulates the Security Assertion Markup Language (SAML) endpoints that are exposed by a trust partner, and endpoint bindings for the trust partner. A New-ADFSSamlEndpoint cmdlet is also supported for creating an endpoint object that can be piped to ADFSRelyingPartyTrust or ADFSClaimProviderTrust cmdlets if a trust partner is configured manually instead of being configured with imported metadata.
This resource encapsulates the contact information for a trust partner. A New-ADFSContactPerson cmdlet is supported for manual configuration.
This resource encapsulates organization information for a trust partner. A New-ADFSOrganization cmdlet is supported for creating and configuring this resource.
You can use this resource to manage the service account that is used to share the private keys of the certificates that AD FS 2.0 generates and manages, if that option is enabled on the server. When the administrator manages the certificates, this command becomes inactive
You can use this resource to change the frequency of configuration database synchronization when using the Windows Internal Database, instead of an external SQL database. You can also use it to specify which federation server is the primary federation server in the federation server farm and check when the last synchronization was preformed.