Skip to content

Get-OpenADComputer.md

Latest commit

 

History

History
397 lines (292 loc) · 12.4 KB

Get-OpenADComputer.md

File metadata and controls

397 lines (292 loc) · 12.4 KB
external help file PSOpenAD.Module.dll-Help.xml
Module Name PSOpenAD
online version https://www.github.com/jborean93/PSOpenAD/blob/main/docs/en-US/Get-OpenADComputer.md
schema 2.0.0

Get-OpenADComputer

SYNOPSIS

Get one or more Active Directory computers.

SYNTAX

ServerLDAPFilter (Default)

Get-OpenADComputer [-Server <String>] [-AuthType <AuthenticationMethod>]
 [-SessionOption <OpenADSessionOptions>] [-StartTLS] [-Credential <PSCredential>] [-LDAPFilter <String>]
 [-SearchBase <String>] [-SearchScope <SearchScope>] [-Property <String[]>]
 [-ProgressAction <ActionPreference>] [<CommonParameters>]

SessionIdentity

Get-OpenADComputer -Session <OpenADSession> [-Identity] <ADPrincipalIdentityWithDollar> [-Property <String[]>]
 [-ProgressAction <ActionPreference>] [<CommonParameters>]

SessionLDAPFilter

Get-OpenADComputer -Session <OpenADSession> [-LDAPFilter <String>] [-SearchBase <String>]
 [-SearchScope <SearchScope>] [-Property <String[]>] [-ProgressAction <ActionPreference>] [<CommonParameters>]

ServerIdentity

Get-OpenADComputer [-Server <String>] [-AuthType <AuthenticationMethod>]
 [-SessionOption <OpenADSessionOptions>] [-StartTLS] [-Credential <PSCredential>]
 [-Identity] <ADPrincipalIdentityWithDollar> [-Property <String[]>] [-ProgressAction <ActionPreference>]
 [<CommonParameters>]

DESCRIPTION

The Get-OpenADComputer cmdlet gets a computer or perforams a search to retrieve multiple computers. Specifying no -Identity or -LDAPFilter parameter will result in a query of just (objectCategory=computer). Otherwise that will be be used as an AND condition of the query specified by the caller, e.g. (&(objectCategory=computer)(...)).

The -Identity parameter specifies the Active Directory computer to retrieve. You can identify a computer by its distinguished name, GUID, security identifier, user principal name, or SAM account name.

The -LDAPFilter parameter can be used to retrieve multiple computer objects using the filter required. The LDAP filter value is in the form of an LDAP filter string.

The cmdlet communicates with the LDAP server in one of three ways:

  • Using the implicit AD connection based on the current environment

  • Using the -Session object specified

  • Using a new or cached connection to the -Server specified

For more information on Open AD sessions, see about_OpenADSessions.

The output for each computer retrieves a default set of computer object properties as documented in the OUTPUT section. Any additional properties can be requested with the -Property parameter in the form of the LDAP property name desired.

EXAMPLES

Example 1: Get all computers in the target LDAP connection

PS C:\> Get-OpenADComputer

This command retrieves all AD computer objects ((objectCategory=computer)) in the implicit AD connection.

Example 2: Get specific computer from a specific LDAP instance using the distinguished name

PS C:\> Get-OpenADComputer -Identity "DN=Workstation,OU=City,DC=domain,DC=test" -Server dc.domain.test

This command retrieves the AD computer object Workstation under OU=City,DC=domain,DC=test from the specific LDAP server dc.domain.test.

Example 3: Get all computers with a name starting with APP

PS C:\> Get-OpenADComputer -LDAPFilter "(name=APP*)"

This commands gets all the computers that have the name LDAP attribute that starts with APP.

Example 4: Get extra properties for a computer

PS C:\> $filter = "(&(sAMAccountName=*SERVER*)(logonCount>=1))"
PS C:\> Get-OpenADComputer -LDAPFilter $filter -Property operatingSystem, 'msDS-SupportedEncryptionTypes'

This command gets all computers that match the filter and also gets the LDAP attributes operatingSystem and msDS-SupportedEncryptionTypes in addition to the default properties.

Example 5: Get all properties for a computer

PS C:\> Get-OpenADComputer -Property *

This command get all the computer objects in addition to all the properties that have a value set.

PARAMETERS

-AuthType

The authentication type to use when creating the OpenAD session. This is used when the cmdlet creates a new connection to the -Server specified`.

Type: AuthenticationMethod
Parameter Sets: ServerLDAPFilter, ServerIdentity
Aliases:
Accepted values: Default, Anonymous, Simple, Negotiate, Kerberos, Certificate

Required: False
Position: Named
Default value: Default
Accept pipeline input: False
Accept wildcard characters: False

-Credential

The explicit credentials to use when creating the OpenAD session. This is used when the cmdlet creates a new connection to the -Server specified.

Type: PSCredential
Parameter Sets: ServerLDAPFilter, ServerIdentity
Aliases:

Required: False
Position: Named
Default value: None
Accept pipeline input: False
Accept wildcard characters: False

-Identity

Specifies the Active Directory computer object to search for using one of the following formats:

  • DistinguishedName

  • ObjectGUID

  • ObjectSID

  • UserPrincipalName

  • SamAccountName

The cmdlet writes an error if no, or multiple, objects are found based on the identity specified. In addition the identity is filtered by the LDAP filter (objectCategory=computer) to restrict only computer objects from being searched. The -LDAPFilter parameter can be used instead to query for multiple objects.

Type: ADPrincipalIdentityWithDollar
Parameter Sets: SessionIdentity, ServerIdentity
Aliases:

Required: True
Position: 0
Default value: None
Accept pipeline input: True (ByPropertyName, ByValue)
Accept wildcard characters: False

-LDAPFilter

Used instead of -Identity to specify an LDAP query used to filter computer objects. The filter specified here will be used with an AND condition to (objectCategory=computer).

Type: String
Parameter Sets: ServerLDAPFilter, SessionLDAPFilter
Aliases:

Required: False
Position: Named
Default value: None
Accept pipeline input: True (ByPropertyName)
Accept wildcard characters: False

-ProgressAction

New common parameter introduced in PowerShell 7.4.

Type: ActionPreference
Parameter Sets: (All)
Aliases: proga

Required: False
Position: Named
Default value: None
Accept pipeline input: False
Accept wildcard characters: False

-Property

The attributes to retrieve for each computer object returned. The values of each attribute is in the form of an LDAP attribute name and are case insensitive. When no properties are specified the following attributes are retrieved:

  • distinguishedName

  • name

  • objectClass

  • objectGUID

  • sAMAccountName

  • objectSid

  • userPrincipalName

  • dNSHostName

Any attributes specified by this parameter will be added to the list above. Specify * to display all attributes that are set on the object. Any attributes on the object that do not have a value set will not be returned with * unless they were also explicitly requested. These unset attributes must be explicitly defined for it to return on the output object.

If there has been a successful connection to any LDAP server this option supports tab completion. The possible properties shown in the tab completion are based on the schema returned by the server for the computer object class. If no connection has been created by the client then there is no tab completion available.

Type: String[]
Parameter Sets: (All)
Aliases: Properties

Required: False
Position: Named
Default value: None
Accept pipeline input: False
Accept wildcard characters: False

-SearchBase

The base Active Directory path to search the object for. This defaults to the defaultNamingContext of the session connection which is typically the root of the domain. Combine this with -SearchScope to limit searches to a smaller subset of the domain.

Type: String
Parameter Sets: ServerLDAPFilter, SessionLDAPFilter
Aliases:

Required: False
Position: Named
Default value: None
Accept pipeline input: False
Accept wildcard characters: False

-SearchScope

Specifies the scope of an Active Directory search. This can be set to

  • Base - Only searches the object at the -SearchBase path specified

  • OneLevel - Searches the immediate children of -SearchBase

  • Subtree (default) - Searches the children of -SearchBase and subsquent children of them

Type: SearchScope
Parameter Sets: ServerLDAPFilter, SessionLDAPFilter
Aliases:
Accepted values: Base, OneLevel, Subtree

Required: False
Position: Named
Default value: Subtree
Accept pipeline input: False
Accept wildcard characters: False

-Server

The Active Directory server to connect to. This can either be the name of the server or the LDAP connection uri starting with ldap:// or ldaps://. The derived URI of this value is used to find any existing connections that are available for use or will be used to create a new session if no cached session exists. If both -Server and -Session are not specified then the default Kerberos realm is used if available otherwise it will generate an error. This option supports tab completion based on the existing OpenADSessions that have been created.

This option is mutually exclusive with -Session.

Type: String
Parameter Sets: ServerLDAPFilter, ServerIdentity
Aliases:

Required: False
Position: Named
Default value: None
Accept pipeline input: False
Accept wildcard characters: False

-Session

The OpenAD session to use for the query rather than trying to create a new connection or reuse a cached connection. This session is generated by New-OpenADSession and can be used in situations where the global defaults should not be used.

This option is mutually exclusive with -Server.

Type: OpenADSession
Parameter Sets: SessionIdentity, SessionLDAPFilter
Aliases:

Required: True
Position: Named
Default value: None
Accept pipeline input: False
Accept wildcard characters: False

-SessionOption

Advanced session options used when creating a new session with -Server. These options can be generated with New-OpenADSessionOption.

Type: OpenADSessionOptions
Parameter Sets: ServerLDAPFilter, ServerIdentity
Aliases:

Required: False
Position: Named
Default value: None
Accept pipeline input: False
Accept wildcard characters: False

-StartTLS

Use StartTLS when creating a new session with -Server.

Type: SwitchParameter
Parameter Sets: ServerLDAPFilter, ServerIdentity
Aliases:

Required: False
Position: Named
Default value: None
Accept pipeline input: False
Accept wildcard characters: False

CommonParameters

This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable, -InformationAction, -InformationVariable, -OutVariable, -OutBuffer, -PipelineVariable, -Verbose, -WarningAction, and -WarningVariable. For more information, see about_CommonParameters.

INPUTS

System.String

PSOpenAD.ADPrincipalIdentityWithDollar

The identity in it's various forms can be piped into the cmdlet.

OUTPUTS

PSOpenAD.OpenADComputer

The OpenADComputer representing the object(s) found. This object will always have the following properties set:

  • DistinguishedName

  • Name

  • ObjectClass

  • ObjectGuid

  • SamAccountName

  • SID

  • Enabled

  • UserPrincipalName

  • DNSHostName

  • DomainController: This is set to the domain controller that processed the request

Any explicit attributes requested through -Property are also present on the object.

If an LDAP attribute on the underlying object did not have a value set but was explicitly requested then the property will be set to $null.

NOTES

Unlike Get-ADComputer, if an computer object cannot be found based on the -Identity requested this cmdlet will emit an error record. Setting -ErrorAction Stop on the call can turn this error into an exception and have it act like Get-ADComputer.

RELATED LINKS

Active Directory: LDAP Syntax Filters LDAP Filters