< Back
ConvertTo-ADObject
Post
NAME ConvertTo-ADObject
SYNOPSIS
Takes an identity and an optional domain and returns information about a matching AD object.
SYNTAX
ConvertTo-ADObject [-Identity] <String> [[-Domain] <String>] [-Credential <PSCredential>] [<CommonParameters>]
DESCRIPTION
The cmdlet takes the identity and matches it against properties to include:
-Name
-SamAccountName
-CN
-DistinguishedName
-Display Name
-ObjectSID
-ObjectGUID
Only user, computer, group, and foreignSecurityPrincipal object types are searched and returned. If there
are multiple matches to the identity
value, only the first match is returned. Additionally, information about the object's domain and forest
are also included in the return object.
PARAMETERS
-Identity <String>
The identity to convert to an AD object. This is a string that is matched against AD object properties:
-Name
-SamAccountName
-CN
-DistinguishedName
-Display Name
-ObjectSID
-ObjectGUID
For user objects, the identity can be provided as a User Principal Name (UPN) or domain\\username format. In
these cases, the domain will be extracted
from the identity and does not need to be specified.
If this parameter is not specified, the current windows identity principal is utilized, which could be a user
or system account, which is translated to the corresponding
computer object.
Required? true
Position? 1
Default value [System.String]::Empty
Accept pipeline input? true (ByValue)
Accept wildcard characters? false
-Domain <String>
Optionally indicates the domain the object exists in. If this parameter is not specified, the domain of the
local user or computer is used, depending on what is specified for
the Identity parameter. If the identity parameter is specified, the current user domain is used. If the
identity parameter is not specified, and the current windows identity is
the system account, the local computer domain is used, otherwise the current user domain is used.
If the Identity parameter is specified with a domain\\username or UPN value, this parameter is ignored.
Required? false
Position? 2
Default value [System.String]::Empty
Accept pipeline input? false
Accept wildcard characters? false
-Credential <PSCredential>
Specifies a user account that has permission to perform this action. The default is the current user.
Type a user name, such as "User01" or "Domain01\\User01", or enter a PSCredential object, such as one generated
by the Get-Credential cmdlet. If you type a user name, you will be prompted for a password.
Required? false
Position? named
Default value [PSCredential]::Empty
Accept pipeline input? false
Accept wildcard characters? false
<CommonParameters>
This cmdlet supports the common parameters: Verbose, Debug,
ErrorAction, ErrorVariable, WarningAction, WarningVariable,
OutBuffer, PipelineVariable, and OutVariable. For more information, see
about_CommonParameters (https:/go.microsoft.com/fwlink/?LinkID=113216).
INPUTS
System.String
OUTPUTS
System.Management.Automation.PSCustomObject
NOTES
AUTHOR: Michael Haken
LAST UPDATE: 1/7/2017
-------------------------- EXAMPLE 1 --------------------------
PS C:\\>ConvertTo-ADObject -Identity "Domain Admins" -Domain contoso
Gets information about the AD object in contoso that matches "Domain Admins"
RELATED LINKS
SYNOPSIS
Takes an identity and an optional domain and returns information about a matching AD object.
SYNTAX
ConvertTo-ADObject [-Identity] <String> [[-Domain] <String>] [-Credential <PSCredential>] [<CommonParameters>]
DESCRIPTION
The cmdlet takes the identity and matches it against properties to include:
-Name
-SamAccountName
-CN
-DistinguishedName
-Display Name
-ObjectSID
-ObjectGUID
Only user, computer, group, and foreignSecurityPrincipal object types are searched and returned. If there
are multiple matches to the identity
value, only the first match is returned. Additionally, information about the object's domain and forest
are also included in the return object.
PARAMETERS
-Identity <String>
The identity to convert to an AD object. This is a string that is matched against AD object properties:
-Name
-SamAccountName
-CN
-DistinguishedName
-Display Name
-ObjectSID
-ObjectGUID
For user objects, the identity can be provided as a User Principal Name (UPN) or domain\\username format. In
these cases, the domain will be extracted
from the identity and does not need to be specified.
If this parameter is not specified, the current windows identity principal is utilized, which could be a user
or system account, which is translated to the corresponding
computer object.
Required? true
Position? 1
Default value [System.String]::Empty
Accept pipeline input? true (ByValue)
Accept wildcard characters? false
-Domain <String>
Optionally indicates the domain the object exists in. If this parameter is not specified, the domain of the
local user or computer is used, depending on what is specified for
the Identity parameter. If the identity parameter is specified, the current user domain is used. If the
identity parameter is not specified, and the current windows identity is
the system account, the local computer domain is used, otherwise the current user domain is used.
If the Identity parameter is specified with a domain\\username or UPN value, this parameter is ignored.
Required? false
Position? 2
Default value [System.String]::Empty
Accept pipeline input? false
Accept wildcard characters? false
-Credential <PSCredential>
Specifies a user account that has permission to perform this action. The default is the current user.
Type a user name, such as "User01" or "Domain01\\User01", or enter a PSCredential object, such as one generated
by the Get-Credential cmdlet. If you type a user name, you will be prompted for a password.
Required? false
Position? named
Default value [PSCredential]::Empty
Accept pipeline input? false
Accept wildcard characters? false
<CommonParameters>
This cmdlet supports the common parameters: Verbose, Debug,
ErrorAction, ErrorVariable, WarningAction, WarningVariable,
OutBuffer, PipelineVariable, and OutVariable. For more information, see
about_CommonParameters (https:/go.microsoft.com/fwlink/?LinkID=113216).
INPUTS
System.String
OUTPUTS
System.Management.Automation.PSCustomObject
NOTES
AUTHOR: Michael Haken
LAST UPDATE: 1/7/2017
-------------------------- EXAMPLE 1 --------------------------
PS C:\\>ConvertTo-ADObject -Identity "Domain Admins" -Domain contoso
Gets information about the AD object in contoso that matches "Domain Admins"
RELATED LINKS