Get-CsAdPrincipal
Returns information about Active Directory principals. These principals include Active Directory objects such as users, groups, contacts, containers, and organizational units. This cmdlet was introduced in Lync Server 2013.
Syntax
Get-CsAdPrincipal
[[-Identity] <UserIdParameter>]
[-Credential <PSCredential>]
[-DomainController <Fqdn>]
[-Filter <String>]
[-LDAPFilter <String>]
[-OU <OUIdParameter>]
[-ResultSize <Microsoft.Rtc.Management.ADConnect.Core.Unlimited`1[System.UInt32]>]
[<CommonParameters>] Description
The Get-CsAdPrincipal cmdlet returns a collection of Active Directory principals that can be used when constructing Persistent Chat membership lists (see the help information for the AllowedMembers and DeniedMembers parameters for the Set-CsPersistentChatCategory cmdlet for more details). Get-CsAdPrincipal returns information for Active Directory objects such as:
Users (object class = {top, person, organizationalPerson, user})
Groups (object class = {top, group})
Contacts (object class = {top, person, organizationalPerson, contact})
Containers (object class = {top, container})
Organizational Units (object class = {top, organizationalUnit})
Domains (object class = {top, domain, domainDNS})
Among other things, this means that you can use the Get-CsAdPrincipal cmdlet (and the objectClass property) to quickly return information about Active Directory objects such as groups or organizational units. For example, this command returns the names of all your Active Directory OUs:
Get-CsAdPrincipal | Where-Object {$_.ObjectClass -match "organizationalUnit"} | Select-Object Name
The functions carried out by the Get-CsAdPrincipal cmdlet are not available in the Skype for Business Server Control Panel.
Examples
-------------------------- Example 1 --------------------------
Get-CsAdPrincipalThe command shown in Example 1 returns all the Active Directory principals in the organization.
-------------------------- Example 2 --------------------------
Get-CsAdPrincipal -Filter {SipAddress -eq "sip:RedmondMeetingRoom@litwareinc.com"}In Example 2, information is returned for a single Active Directory principal: the principal with the SIP address "sip:RedmondMeetingRoom@litwareinc.com". This is done by including the Filter parameter and a filter value that looks for principals where the SipAddress property is equal to (-eq) "sip:RedmondMeetingRoom@litwareinc.com".
-------------------------- Example 3 --------------------------
Get-CsAdPrincipal | Where-Object {$_.ObjectClass -contains "contact"}In the preceding example, information is returned for all the Active Directory objects. To carry out this task, the command first calls the Get-CsAdPrincipal cmdlet without any parameters; this returns a collection of all the Active Directory principals. That collection is then piped to the Where-Object cmdlet, which selects only those principals where the ObjectClass property contains the string value "contact".
Parameters
-Credential
Enables you to run the Get-CsAdPrincipal cmdlet under alternate credentials. This might be required if the account you used to log on to Windows does not have the necessary privileges required to work with user objects.
To use the Credential parameter you must first create a PSCredential object by using the Get-Credential cmdlet. For details, see the Get-Credential cmdlet help topic.
| Type: | PSCredential |
| Position: | Named |
| Default value: | None |
| Required: | False |
| Accept pipeline input: | False |
| Accept wildcard characters: | False |
| Applies to: | Lync Server 2013, Skype for Business Server 2015, Skype for Business Server 2019 |
-DomainController
Enables you to connect to the specified domain controller in order to retrieve Active Directory principal information. To connect to a particular domain controller, include the DomainController parameter followed by the computer name (for example, atl-dc-001) or its fully qualified domain name (FQDN) (for example, atl-dc-001.litwareinc.com).
| Type: | Fqdn |
| Position: | Named |
| Default value: | None |
| Required: | False |
| Accept pipeline input: | False |
| Accept wildcard characters: | False |
| Applies to: | Lync Server 2013, Skype for Business Server 2015, Skype for Business Server 2019 |
-Filter
Enables you to limit the returned data by filtering on attributes specific to Skype for Business Server.
The Filter parameter uses much of the same Windows PowerShell filtering syntax used by the Where-Object cmdlet. For example, a filter that returns only principals whose sip address equals "RedmondMeetingRoom@litwareinc.com" would look like this:
-Filter {SipAddress -eq "sip:RedmondMeetingRoom@litwareinc.com"}
In that example, SipAddress represents the Skype for Business attribute, -eq represents the comparison operator (equal to "sip:RedmondMeetingRoom@litwareinc.com")
| Type: | String |
| Position: | Named |
| Default value: | None |
| Required: | False |
| Accept pipeline input: | False |
| Accept wildcard characters: | False |
| Applies to: | Lync Server 2013, Skype for Business Server 2015, Skype for Business Server 2019 |
-Identity
Indicates the Identity of the principal account to be retrieved. Identities are typically specified by using one of four formats: 1) the account SIP address; 2) the user's user principal name (UPN); 3) the account domain name and logon name, in the form domain\logon (for example, litwareinc\kenmyer); and, 4) the account Active Directory display name (for example, Ken Myer).
You can also reference a user account by using the user's Active Directory distinguished name.
You can use the asterisk () wildcard character when using the Display Name as the Identity. For example, the Identity " Smith" returns all the users who have a display name that ends with the string value " Smith".
| Type: | UserIdParameter |
| Position: | 1 |
| Default value: | None |
| Required: | False |
| Accept pipeline input: | True |
| Accept wildcard characters: | False |
| Applies to: | Lync Server 2013, Skype for Business Server 2015, Skype for Business Server 2019 |
-LDAPFilter
Enables you to limit the returned data by filtering on generic Active Directory attributes (that is, attributes that are not specific to Skype for Business Server). For example, you can limit returned data to principals who belong to a specific department or who have a specific manager or job title.
The LdapFilter parameter uses the LDAP query language when creating filters. For example, a filter that returns only principals located in the city of Redmond would look like this:
-LdapFilter "l=Redmond"
In that example, the "l" (a lowercase L) represents the Active Directory attribute (locality); "=" represents the comparison operator (equal to); and "Redmond" represents the filter value.
| Type: | String |
| Position: | Named |
| Default value: | None |
| Required: | False |
| Accept pipeline input: | False |
| Accept wildcard characters: | False |
| Applies to: | Lync Server 2013, Skype for Business Server 2015, Skype for Business Server 2019 |
-OU
Enables you to return information about principals in a specific organizational unit (OU) or container. The OU parameter returns data from both the specified OU and any of its child OUs. For example, if the Finance OU has two child OUs -- AccountsPayable and AccountsReceivable - principals will be returned from each of these three OUs.
When specifying an OU, use the distinguished name (DN) of that container; for example:
-OU "OU=Finance,dc=litwareinc,dc=com"
To return principals from the Users container, use this syntax:
-OU "cn=Users,dc=litwareinc,dc=com"
| Type: | OUIdParameter |
| Position: | Named |
| Default value: | None |
| Required: | False |
| Accept pipeline input: | False |
| Accept wildcard characters: | False |
| Applies to: | Lync Server 2013, Skype for Business Server 2015, Skype for Business Server 2019 |
-ResultSize
Enables you to limit the number of records returned by the cmdlet. For example, to return seven principals (regardless of the number of principals that are in your forest) include the ResultSize parameter and set the parameter value to 7. Note that there is no way to guarantee which seven principals will be returned.
The result size can be set to any whole number between 0 and 2147483647, inclusive. If set to 0 the command will run, but no data will be returned. If you set the ResultSize to 7 but you have only three principals in your forest, the command will return those three principals, and then complete without error.
| Type: | Microsoft.Rtc.Management.ADConnect.Core.Unlimited`1[System.UInt32] |
| Position: | Named |
| Default value: | None |
| Required: | False |
| Accept pipeline input: | False |
| Accept wildcard characters: | False |
| Applies to: | Lync Server 2013, Skype for Business Server 2015, Skype for Business Server 2019 |
Inputs
String
String value or object representing an Active Directory user, group, contact, container, and organizational unit. For example, this syntax returns Active Directory principal information for the Redmond and Dublin OUs:
"OU=Redmond,DC=litwareinc,DC=com", "OU=Dublin,DC=litwareinc,DC=com" | Get-CsAdPrincipal
Outputs
Microsoft.Rtc.Management.ADConnect.Schema.OCSADPrincipal