en-US/PSOpenAD.dll-Help.xml
|
<?xml version="1.0" encoding="utf-8"?>
<helpItems schema="maml" xmlns="http://msh"> <command:command xmlns:maml="http://schemas.microsoft.com/maml/2004/10" xmlns:command="http://schemas.microsoft.com/maml/dev/command/2004/10" xmlns:dev="http://schemas.microsoft.com/maml/dev/2004/10" xmlns:MSHelp="http://msdn.microsoft.com/mshelp"> <command:details> <command:name>Get-OpenADAuthSupport</command:name> <command:verb>Get</command:verb> <command:noun>OpenADAuthSupport</command:noun> <maml:description> <maml:para>Get client authentication capabilities.</maml:para> </maml:description> </command:details> <maml:description> <maml:para>Get the authentication methods the client can use and display the availability of optional features.</maml:para> </maml:description> <command:syntax> <command:syntaxItem> <maml:name>Get-OpenADAuthSupport</maml:name> </command:syntaxItem> </command:syntax> <command:parameters /> <command:inputTypes> <command:inputType> <dev:type> <maml:name>None</maml:name> </dev:type> <maml:description> <maml:para></maml:para> </maml:description> </command:inputType> </command:inputTypes> <command:returnValues> <command:returnValue> <dev:type> <maml:name>PSOpenAD.AuthenticationProvider</maml:name> </dev:type> <maml:description> <maml:para>The details of each authentication object. This object has the following properties:</maml:para> <maml:para>+ `Method`: The authentication method</maml:para> <maml:para>+ `SaslId`: The SASL mechanism name that this provider represents</maml:para> <maml:para>+ `Available`: Whether this authentication method can be used by the client</maml:para> <maml:para>+ `CanSign`: Whether this authentication method can sign or encrypt data over a non-TLS connection</maml:para> <maml:para>+ `Details`: Extra details on why a feature may not be available</maml:para> </maml:description> </command:returnValue> </command:returnValues> <maml:alertSet> <maml:alert> <maml:para>The `Anonymous` and `Simple` authentication methods are always available to the client. These methods do not support signatures or encryption over a non-TLS connection so should be avoided in those scenarios. The `Negotiate` and `Kerberos` methods are always available on Windows but relies on a working `GSSAPI` library on non-Windows hosts.</maml:para> </maml:alert> </maml:alertSet> <command:examples> <command:example> <maml:title>-------------------------- Example 1 --------------------------</maml:title> <dev:code>PS C:\> Get-OpenADAuthSupport</dev:code> <dev:remarks> <maml:para>Get the authentication support information for the current client.</maml:para> </dev:remarks> </command:example> </command:examples> <command:relatedLinks> <maml:navigationLink> <maml:linkText>Online Version:</maml:linkText> <maml:uri>https://www.github.com/jborean93/PSOpenAD/blob/main/docs/en-US/Get-OpenADAuthSupport.md</maml:uri> </maml:navigationLink> </command:relatedLinks> </command:command> <command:command xmlns:maml="http://schemas.microsoft.com/maml/2004/10" xmlns:command="http://schemas.microsoft.com/maml/dev/command/2004/10" xmlns:dev="http://schemas.microsoft.com/maml/dev/2004/10" xmlns:MSHelp="http://msdn.microsoft.com/mshelp"> <command:details> <command:name>Get-OpenADComputer</command:name> <command:verb>Get</command:verb> <command:noun>OpenADComputer</command:noun> <maml:description> <maml:para>Get one or more Active Directory computers.</maml:para> </maml:description> </command:details> <maml:description> <maml:para>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)(...))`.</maml:para> <maml:para>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.</maml:para> <maml:para>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.</maml:para> <maml:para>The cmdlet communicates with the LDAP server in one of three ways:</maml:para> <maml:para>+ Using the implicit AD connection based on the current environment</maml:para> <maml:para>+ Using the `-Session` object specified</maml:para> <maml:para>+ Using a new or cached connection to the `-Server` specified</maml:para> <maml:para>For more information on Open AD sessions, see about_OpenADSessions (./about_OpenADSessions.md).</maml:para> <maml:para>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.</maml:para> </maml:description> <command:syntax> <command:syntaxItem> <maml:name>Get-OpenADComputer</maml:name> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="none"> <maml:name>AuthType</maml:name> <maml:description> <maml:para>The authentication type to use when creating the `OpenAD` session. This is used when the cmdlet creates a new connection to the `-Server` specified`.</maml:para> </maml:description> <command:parameterValueGroup> <command:parameterValue required="false" command:variableLength="false">Default</command:parameterValue> <command:parameterValue required="false" command:variableLength="false">Anonymous</command:parameterValue> <command:parameterValue required="false" command:variableLength="false">Simple</command:parameterValue> <command:parameterValue required="false" command:variableLength="false">Negotiate</command:parameterValue> <command:parameterValue required="false" command:variableLength="false">Kerberos</command:parameterValue> </command:parameterValueGroup> <command:parameterValue required="true" variableLength="false">AuthenticationMethod</command:parameterValue> <dev:type> <maml:name>AuthenticationMethod</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>Default</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="none"> <maml:name>Credential</maml:name> <maml:description> <maml:para>The explicit credentials to use when creating the `OpenAD` session. This is used when the cmdlet creates a new connection to the `-Server` specified.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">PSCredential</command:parameterValue> <dev:type> <maml:name>PSCredential</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>None</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="True (ByPropertyName)" position="named" aliases="none"> <maml:name>LDAPFilter</maml:name> <maml:description> <maml:para>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)`.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">String</command:parameterValue> <dev:type> <maml:name>String</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>None</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="Properties"> <maml:name>Property</maml:name> <maml:description> <maml:para>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:</maml:para> <maml:para>+ `distinguishedName`</maml:para> <maml:para>+ `name`</maml:para> <maml:para>+ `objectClass`</maml:para> <maml:para>+ `objectGUID`</maml:para> <maml:para>+ `sAMAccountName`</maml:para> <maml:para>+ `objectSid`</maml:para> <maml:para>+ `userPrincipalName`</maml:para> <maml:para>+ `dNSHostName`</maml:para> <maml:para>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.</maml:para> <maml:para>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.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">String[]</command:parameterValue> <dev:type> <maml:name>String[]</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>None</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="none"> <maml:name>SearchBase</maml:name> <maml:description> <maml:para>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.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">String</command:parameterValue> <dev:type> <maml:name>String</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>None</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="none"> <maml:name>SearchScope</maml:name> <maml:description> <maml:para>Specifies the scope of an Active Directory search. This can be set to</maml:para> <maml:para>+ `Base` - Only searches the object at the `-SearchBase` path specified</maml:para> <maml:para>+ `OneLevel` - Searches the immediate children of `-SearchBase`</maml:para> <maml:para>+ `Subtree` (default) - Searches the children of `-SearchBase` and subsquent children of them</maml:para> </maml:description> <command:parameterValueGroup> <command:parameterValue required="false" command:variableLength="false">Base</command:parameterValue> <command:parameterValue required="false" command:variableLength="false">OneLevel</command:parameterValue> <command:parameterValue required="false" command:variableLength="false">Subtree</command:parameterValue> </command:parameterValueGroup> <command:parameterValue required="true" variableLength="false">SearchScope</command:parameterValue> <dev:type> <maml:name>SearchScope</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>Subtree</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="none"> <maml:name>Server</maml:name> <maml:description> <maml:para>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.</maml:para> <maml:para>This option is mutually exclusive with `-Session`.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">String</command:parameterValue> <dev:type> <maml:name>String</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>None</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="none"> <maml:name>SessionOption</maml:name> <maml:description> <maml:para>Advanced session options used when creating a new session with `-Server`. These options can be generated with `New-OpenADSessionOption`.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">OpenADSessionOptions</command:parameterValue> <dev:type> <maml:name>OpenADSessionOptions</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>None</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="none"> <maml:name>StartTLS</maml:name> <maml:description> <maml:para>Use `StartTLS` when creating a new session with `-Server`.</maml:para> </maml:description> <dev:type> <maml:name>SwitchParameter</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>False</dev:defaultValue> </command:parameter> </command:syntaxItem> <command:syntaxItem> <maml:name>Get-OpenADComputer</maml:name> <command:parameter required="true" variableLength="true" globbing="false" pipelineInput="True (ByPropertyName, ByValue)" position="0" aliases="none"> <maml:name>Identity</maml:name> <maml:description> <maml:para>Specifies the Active Directory computer object to search for using one fo the following formats:</maml:para> <maml:para>+ `DistinguishedName`</maml:para> <maml:para>+ `ObjectGUID`</maml:para> <maml:para>+ `ObjectSID`</maml:para> <maml:para>+ `UserPrincipalName`</maml:para> <maml:para>+ `SamAccountName`</maml:para> <maml:para>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.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">ADPrincipalIdentityWithDollar</command:parameterValue> <dev:type> <maml:name>ADPrincipalIdentityWithDollar</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>None</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="none"> <maml:name>AuthType</maml:name> <maml:description> <maml:para>The authentication type to use when creating the `OpenAD` session. This is used when the cmdlet creates a new connection to the `-Server` specified`.</maml:para> </maml:description> <command:parameterValueGroup> <command:parameterValue required="false" command:variableLength="false">Default</command:parameterValue> <command:parameterValue required="false" command:variableLength="false">Anonymous</command:parameterValue> <command:parameterValue required="false" command:variableLength="false">Simple</command:parameterValue> <command:parameterValue required="false" command:variableLength="false">Negotiate</command:parameterValue> <command:parameterValue required="false" command:variableLength="false">Kerberos</command:parameterValue> </command:parameterValueGroup> <command:parameterValue required="true" variableLength="false">AuthenticationMethod</command:parameterValue> <dev:type> <maml:name>AuthenticationMethod</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>Default</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="none"> <maml:name>Credential</maml:name> <maml:description> <maml:para>The explicit credentials to use when creating the `OpenAD` session. This is used when the cmdlet creates a new connection to the `-Server` specified.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">PSCredential</command:parameterValue> <dev:type> <maml:name>PSCredential</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>None</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="Properties"> <maml:name>Property</maml:name> <maml:description> <maml:para>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:</maml:para> <maml:para>+ `distinguishedName`</maml:para> <maml:para>+ `name`</maml:para> <maml:para>+ `objectClass`</maml:para> <maml:para>+ `objectGUID`</maml:para> <maml:para>+ `sAMAccountName`</maml:para> <maml:para>+ `objectSid`</maml:para> <maml:para>+ `userPrincipalName`</maml:para> <maml:para>+ `dNSHostName`</maml:para> <maml:para>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.</maml:para> <maml:para>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.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">String[]</command:parameterValue> <dev:type> <maml:name>String[]</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>None</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="none"> <maml:name>Server</maml:name> <maml:description> <maml:para>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.</maml:para> <maml:para>This option is mutually exclusive with `-Session`.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">String</command:parameterValue> <dev:type> <maml:name>String</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>None</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="none"> <maml:name>SessionOption</maml:name> <maml:description> <maml:para>Advanced session options used when creating a new session with `-Server`. These options can be generated with `New-OpenADSessionOption`.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">OpenADSessionOptions</command:parameterValue> <dev:type> <maml:name>OpenADSessionOptions</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>None</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="none"> <maml:name>StartTLS</maml:name> <maml:description> <maml:para>Use `StartTLS` when creating a new session with `-Server`.</maml:para> </maml:description> <dev:type> <maml:name>SwitchParameter</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>False</dev:defaultValue> </command:parameter> </command:syntaxItem> <command:syntaxItem> <maml:name>Get-OpenADComputer</maml:name> <command:parameter required="true" variableLength="true" globbing="false" pipelineInput="True (ByPropertyName, ByValue)" position="0" aliases="none"> <maml:name>Identity</maml:name> <maml:description> <maml:para>Specifies the Active Directory computer object to search for using one fo the following formats:</maml:para> <maml:para>+ `DistinguishedName`</maml:para> <maml:para>+ `ObjectGUID`</maml:para> <maml:para>+ `ObjectSID`</maml:para> <maml:para>+ `UserPrincipalName`</maml:para> <maml:para>+ `SamAccountName`</maml:para> <maml:para>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.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">ADPrincipalIdentityWithDollar</command:parameterValue> <dev:type> <maml:name>ADPrincipalIdentityWithDollar</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>None</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="Properties"> <maml:name>Property</maml:name> <maml:description> <maml:para>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:</maml:para> <maml:para>+ `distinguishedName`</maml:para> <maml:para>+ `name`</maml:para> <maml:para>+ `objectClass`</maml:para> <maml:para>+ `objectGUID`</maml:para> <maml:para>+ `sAMAccountName`</maml:para> <maml:para>+ `objectSid`</maml:para> <maml:para>+ `userPrincipalName`</maml:para> <maml:para>+ `dNSHostName`</maml:para> <maml:para>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.</maml:para> <maml:para>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.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">String[]</command:parameterValue> <dev:type> <maml:name>String[]</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>None</dev:defaultValue> </command:parameter> <command:parameter required="true" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="none"> <maml:name>Session</maml:name> <maml:description> <maml:para>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.</maml:para> <maml:para>This option is mutually exclusive with `-Server`.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">OpenADSession</command:parameterValue> <dev:type> <maml:name>OpenADSession</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>None</dev:defaultValue> </command:parameter> </command:syntaxItem> <command:syntaxItem> <maml:name>Get-OpenADComputer</maml:name> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="True (ByPropertyName)" position="named" aliases="none"> <maml:name>LDAPFilter</maml:name> <maml:description> <maml:para>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)`.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">String</command:parameterValue> <dev:type> <maml:name>String</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>None</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="Properties"> <maml:name>Property</maml:name> <maml:description> <maml:para>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:</maml:para> <maml:para>+ `distinguishedName`</maml:para> <maml:para>+ `name`</maml:para> <maml:para>+ `objectClass`</maml:para> <maml:para>+ `objectGUID`</maml:para> <maml:para>+ `sAMAccountName`</maml:para> <maml:para>+ `objectSid`</maml:para> <maml:para>+ `userPrincipalName`</maml:para> <maml:para>+ `dNSHostName`</maml:para> <maml:para>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.</maml:para> <maml:para>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.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">String[]</command:parameterValue> <dev:type> <maml:name>String[]</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>None</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="none"> <maml:name>SearchBase</maml:name> <maml:description> <maml:para>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.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">String</command:parameterValue> <dev:type> <maml:name>String</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>None</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="none"> <maml:name>SearchScope</maml:name> <maml:description> <maml:para>Specifies the scope of an Active Directory search. This can be set to</maml:para> <maml:para>+ `Base` - Only searches the object at the `-SearchBase` path specified</maml:para> <maml:para>+ `OneLevel` - Searches the immediate children of `-SearchBase`</maml:para> <maml:para>+ `Subtree` (default) - Searches the children of `-SearchBase` and subsquent children of them</maml:para> </maml:description> <command:parameterValueGroup> <command:parameterValue required="false" command:variableLength="false">Base</command:parameterValue> <command:parameterValue required="false" command:variableLength="false">OneLevel</command:parameterValue> <command:parameterValue required="false" command:variableLength="false">Subtree</command:parameterValue> </command:parameterValueGroup> <command:parameterValue required="true" variableLength="false">SearchScope</command:parameterValue> <dev:type> <maml:name>SearchScope</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>Subtree</dev:defaultValue> </command:parameter> <command:parameter required="true" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="none"> <maml:name>Session</maml:name> <maml:description> <maml:para>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.</maml:para> <maml:para>This option is mutually exclusive with `-Server`.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">OpenADSession</command:parameterValue> <dev:type> <maml:name>OpenADSession</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>None</dev:defaultValue> </command:parameter> </command:syntaxItem> </command:syntax> <command:parameters> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="none"> <maml:name>AuthType</maml:name> <maml:description> <maml:para>The authentication type to use when creating the `OpenAD` session. This is used when the cmdlet creates a new connection to the `-Server` specified`.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">AuthenticationMethod</command:parameterValue> <dev:type> <maml:name>AuthenticationMethod</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>Default</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="none"> <maml:name>Credential</maml:name> <maml:description> <maml:para>The explicit credentials to use when creating the `OpenAD` session. This is used when the cmdlet creates a new connection to the `-Server` specified.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">PSCredential</command:parameterValue> <dev:type> <maml:name>PSCredential</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>None</dev:defaultValue> </command:parameter> <command:parameter required="true" variableLength="true" globbing="false" pipelineInput="True (ByPropertyName, ByValue)" position="0" aliases="none"> <maml:name>Identity</maml:name> <maml:description> <maml:para>Specifies the Active Directory computer object to search for using one fo the following formats:</maml:para> <maml:para>+ `DistinguishedName`</maml:para> <maml:para>+ `ObjectGUID`</maml:para> <maml:para>+ `ObjectSID`</maml:para> <maml:para>+ `UserPrincipalName`</maml:para> <maml:para>+ `SamAccountName`</maml:para> <maml:para>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.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">ADPrincipalIdentityWithDollar</command:parameterValue> <dev:type> <maml:name>ADPrincipalIdentityWithDollar</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>None</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="True (ByPropertyName)" position="named" aliases="none"> <maml:name>LDAPFilter</maml:name> <maml:description> <maml:para>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)`.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">String</command:parameterValue> <dev:type> <maml:name>String</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>None</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="Properties"> <maml:name>Property</maml:name> <maml:description> <maml:para>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:</maml:para> <maml:para>+ `distinguishedName`</maml:para> <maml:para>+ `name`</maml:para> <maml:para>+ `objectClass`</maml:para> <maml:para>+ `objectGUID`</maml:para> <maml:para>+ `sAMAccountName`</maml:para> <maml:para>+ `objectSid`</maml:para> <maml:para>+ `userPrincipalName`</maml:para> <maml:para>+ `dNSHostName`</maml:para> <maml:para>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.</maml:para> <maml:para>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.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">String[]</command:parameterValue> <dev:type> <maml:name>String[]</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>None</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="none"> <maml:name>SearchBase</maml:name> <maml:description> <maml:para>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.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">String</command:parameterValue> <dev:type> <maml:name>String</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>None</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="none"> <maml:name>SearchScope</maml:name> <maml:description> <maml:para>Specifies the scope of an Active Directory search. This can be set to</maml:para> <maml:para>+ `Base` - Only searches the object at the `-SearchBase` path specified</maml:para> <maml:para>+ `OneLevel` - Searches the immediate children of `-SearchBase`</maml:para> <maml:para>+ `Subtree` (default) - Searches the children of `-SearchBase` and subsquent children of them</maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">SearchScope</command:parameterValue> <dev:type> <maml:name>SearchScope</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>Subtree</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="none"> <maml:name>Server</maml:name> <maml:description> <maml:para>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.</maml:para> <maml:para>This option is mutually exclusive with `-Session`.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">String</command:parameterValue> <dev:type> <maml:name>String</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>None</dev:defaultValue> </command:parameter> <command:parameter required="true" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="none"> <maml:name>Session</maml:name> <maml:description> <maml:para>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.</maml:para> <maml:para>This option is mutually exclusive with `-Server`.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">OpenADSession</command:parameterValue> <dev:type> <maml:name>OpenADSession</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>None</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="none"> <maml:name>SessionOption</maml:name> <maml:description> <maml:para>Advanced session options used when creating a new session with `-Server`. These options can be generated with `New-OpenADSessionOption`.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">OpenADSessionOptions</command:parameterValue> <dev:type> <maml:name>OpenADSessionOptions</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>None</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="none"> <maml:name>StartTLS</maml:name> <maml:description> <maml:para>Use `StartTLS` when creating a new session with `-Server`.</maml:para> </maml:description> <command:parameterValue required="false" variableLength="false">SwitchParameter</command:parameterValue> <dev:type> <maml:name>SwitchParameter</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>False</dev:defaultValue> </command:parameter> </command:parameters> <command:inputTypes> <command:inputType> <dev:type> <maml:name>PSOpenAD.ADPrincipalIdentity</maml:name> </dev:type> <maml:description> <maml:para></maml:para> </maml:description> </command:inputType> <command:inputType> <dev:type> <maml:name>System.String</maml:name> </dev:type> <maml:description> <maml:para>The identity in it's various forms can be piped into the cmdlet.</maml:para> </maml:description> </command:inputType> </command:inputTypes> <command:returnValues> <command:returnValue> <dev:type> <maml:name>PSOpenAD.OpenADComputer</maml:name> </dev:type> <maml:description> <maml:para>The `OpenADComputer` representing the object(s) found. This object will always have the following properties set:</maml:para> <maml:para>+ `DistinguishedName`</maml:para> <maml:para>+ `Name`</maml:para> <maml:para>+ `ObjectClass`</maml:para> <maml:para>+ `ObjectGuid`</maml:para> <maml:para>+ `SamAccountName`</maml:para> <maml:para>+ `SID`</maml:para> <maml:para>+ `Enabled`</maml:para> <maml:para>+ `UserPrincipalName`</maml:para> <maml:para>+ `DNSHostName`</maml:para> <maml:para>+ `DomainController`: This is set to the domain controller that processed the request</maml:para> <maml:para>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`.</maml:para> </maml:description> </command:returnValue> </command:returnValues> <maml:alertSet> <maml:alert> <maml:para>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`.</maml:para> </maml:alert> </maml:alertSet> <command:examples> <command:example> <maml:title>-- Example 1: Get all computers in the target LDAP connection --</maml:title> <dev:code>PS C:\> Get-OpenADComputer</dev:code> <dev:remarks> <maml:para>This command retrieves all AD computer objects (`(objectCategory=computer)`) in the implicit AD connection.</maml:para> </dev:remarks> </command:example> <command:example> <maml:title>Example 2: Get specific computer from a specific LDAP instance using the distinguished name</maml:title> <dev:code>PS C:\> Get-OpenADComputer -Identity "DN=Workstation,OU=City,DC=domain,DC=test" -Server dc.domain.test</dev:code> <dev:remarks> <maml:para>This command retrieves the AD computer object `Workstation` under `OU=City,DC=domain,DC=test` from the specific LDAP server `dc.domain.test`.</maml:para> </dev:remarks> </command:example> <command:example> <maml:title>-- Example 3: Get all computers with a name starting with APP --</maml:title> <dev:code>PS C:\> Get-OpenADComputer -LDAPFilter "(name=APP*)"</dev:code> <dev:remarks> <maml:para>This commands gets all the computers that have the `name` LDAP attribute that starts with `APP`.</maml:para> </dev:remarks> </command:example> <command:example> <maml:title>-------- Example 4: Get extra properties for a computer --------</maml:title> <dev:code>PS C:\> $filter = "(&(sAMAccountName=*SERVER*)(logonCount>=1))" PS C:\> Get-OpenADComputer -LDAPFilter $filter -Property operatingSystem, 'msDS-SupportedEncryptionTypes'</dev:code> <dev:remarks> <maml:para>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.</maml:para> </dev:remarks> </command:example> <command:example> <maml:title>--------- Example 5: Get all properties for a computer ---------</maml:title> <dev:code>PS C:\> Get-OpenADComputer -Property *</dev:code> <dev:remarks> <maml:para>This command get all the computer objects in addition to all the properties that have a value set.</maml:para> </dev:remarks> </command:example> </command:examples> <command:relatedLinks> <maml:navigationLink> <maml:linkText>Online Version:</maml:linkText> <maml:uri>https://www.github.com/jborean93/PSOpenAD/blob/main/docs/en-US/Get-OpenADComputer.md</maml:uri> </maml:navigationLink> <maml:navigationLink> <maml:linkText>Active Directory: LDAP Syntax Filters</maml:linkText> <maml:uri>https://social.technet.microsoft.com/wiki/contents/articles/5392.active-directory-ldap-syntax-filters.aspx</maml:uri> </maml:navigationLink> <maml:navigationLink> <maml:linkText>LDAP Filters</maml:linkText> <maml:uri>https://ldap.com/ldap-filters/</maml:uri> </maml:navigationLink> </command:relatedLinks> </command:command> <command:command xmlns:maml="http://schemas.microsoft.com/maml/2004/10" xmlns:command="http://schemas.microsoft.com/maml/dev/command/2004/10" xmlns:dev="http://schemas.microsoft.com/maml/dev/2004/10" xmlns:MSHelp="http://msdn.microsoft.com/mshelp"> <command:details> <command:name>Get-OpenADGroup</command:name> <command:verb>Get</command:verb> <command:noun>OpenADGroup</command:noun> <maml:description> <maml:para>Gets one or more Active Directory groups.</maml:para> </maml:description> </command:details> <maml:description> <maml:para>The `Get-OpenADGroup` cmdlet gets a group or perforams a search to retrieve multiple groups. Specifying no `-Identity` or `-LDAPFilter` parameter will result in a query of just `(objectCategory=group)`. Otherwise that will be be used as an AND condition of the query specified by the caller, e.g. `(&(objectCategory=group)(...))`.</maml:para> <maml:para>The `-Identity` parameter specifies the Active Directory group to retrieve. You can identify a group by its distinguished name, GUID, security identifier, user principal name, or SAM account name.</maml:para> <maml:para>The `-LDAPFilter` parameter can be used to retrieve multiple group objects using the filter required. The LDAP filter value is in the form of an LDAP filter string.</maml:para> <maml:para>The cmdlet communicates with the LDAP server in one of three ways:</maml:para> <maml:para>+ Using the implicit AD connection based on the current environment</maml:para> <maml:para>+ Using the `-Session` object specified</maml:para> <maml:para>+ Using a new or cached connection to the `-Server` specified</maml:para> <maml:para>For more information on Open AD sessions, see about_OpenADSessions (./about_OpenADSessions.md).</maml:para> <maml:para>The output for each group retrieves a default set of group 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.</maml:para> </maml:description> <command:syntax> <command:syntaxItem> <maml:name>Get-OpenADGroup</maml:name> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="none"> <maml:name>AuthType</maml:name> <maml:description> <maml:para>The authentication type to use when creating the `OpenAD` session. This is used when the cmdlet creates a new connection to the `-Server` specified`.</maml:para> </maml:description> <command:parameterValueGroup> <command:parameterValue required="false" command:variableLength="false">Default</command:parameterValue> <command:parameterValue required="false" command:variableLength="false">Anonymous</command:parameterValue> <command:parameterValue required="false" command:variableLength="false">Simple</command:parameterValue> <command:parameterValue required="false" command:variableLength="false">Negotiate</command:parameterValue> <command:parameterValue required="false" command:variableLength="false">Kerberos</command:parameterValue> </command:parameterValueGroup> <command:parameterValue required="true" variableLength="false">AuthenticationMethod</command:parameterValue> <dev:type> <maml:name>AuthenticationMethod</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>Default</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="none"> <maml:name>Credential</maml:name> <maml:description> <maml:para>The explicit credentials to use when creating the `OpenAD` session. This is used when the cmdlet creates a new connection to the `-Server` specified.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">PSCredential</command:parameterValue> <dev:type> <maml:name>PSCredential</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>None</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="True (ByPropertyName)" position="named" aliases="none"> <maml:name>LDAPFilter</maml:name> <maml:description> <maml:para>Used instead of `-Identity` to specify an LDAP query used to filter group objects. The filter specified here will be used with an `AND` condition to `(objectCategory=group)`.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">String</command:parameterValue> <dev:type> <maml:name>String</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>None</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="Properties"> <maml:name>Property</maml:name> <maml:description> <maml:para>The attributes to retrieve for each group 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:</maml:para> <maml:para>+ `distinguishedName`</maml:para> <maml:para>+ `name`</maml:para> <maml:para>+ `objectClass`</maml:para> <maml:para>+ `objectGUID`</maml:para> <maml:para>+ `sAMAccountName`</maml:para> <maml:para>+ `objectSid`</maml:para> <maml:para>+ `groupType`</maml:para> <maml:para>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.</maml:para> <maml:para>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 `group` object class. If no connection has been created by the client then there is no tab completion available.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">String[]</command:parameterValue> <dev:type> <maml:name>String[]</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>None</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="none"> <maml:name>SearchBase</maml:name> <maml:description> <maml:para>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.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">String</command:parameterValue> <dev:type> <maml:name>String</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>None</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="none"> <maml:name>SearchScope</maml:name> <maml:description> <maml:para>Specifies the scope of an Active Directory search. This can be set to</maml:para> <maml:para>+ `Base` - Only searches the object at the `-SearchBase` path specified</maml:para> <maml:para>+ `OneLevel` - Searches the immediate children of `-SearchBase`</maml:para> <maml:para>+ `Subtree` (default) - Searches the children of `-SearchBase` and subsquent children of them</maml:para> </maml:description> <command:parameterValueGroup> <command:parameterValue required="false" command:variableLength="false">Base</command:parameterValue> <command:parameterValue required="false" command:variableLength="false">OneLevel</command:parameterValue> <command:parameterValue required="false" command:variableLength="false">Subtree</command:parameterValue> </command:parameterValueGroup> <command:parameterValue required="true" variableLength="false">SearchScope</command:parameterValue> <dev:type> <maml:name>SearchScope</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>Subtree</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="none"> <maml:name>Server</maml:name> <maml:description> <maml:para>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.</maml:para> <maml:para>This option is mutually exclusive with `-Session`.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">String</command:parameterValue> <dev:type> <maml:name>String</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>None</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="none"> <maml:name>SessionOption</maml:name> <maml:description> <maml:para>Advanced session options used when creating a new session with `-Server`. These options can be generated with `New-OpenADSessionOption`.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">OpenADSessionOptions</command:parameterValue> <dev:type> <maml:name>OpenADSessionOptions</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>None</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="none"> <maml:name>StartTLS</maml:name> <maml:description> <maml:para>Use `StartTLS` when creating a new session with `-Server`.</maml:para> </maml:description> <dev:type> <maml:name>SwitchParameter</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>False</dev:defaultValue> </command:parameter> </command:syntaxItem> <command:syntaxItem> <maml:name>Get-OpenADGroup</maml:name> <command:parameter required="true" variableLength="true" globbing="false" pipelineInput="True (ByPropertyName, ByValue)" position="0" aliases="none"> <maml:name>Identity</maml:name> <maml:description> <maml:para>Specifies the Active Directory group object to search for using one fo the following formats:</maml:para> <maml:para>+ `DistinguishedName`</maml:para> <maml:para>+ `ObjectGUID`</maml:para> <maml:para>+ `ObjectSID`</maml:para> <maml:para>+ `UserPrincipalName`</maml:para> <maml:para>+ `SamAccountName`</maml:para> <maml:para>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=group)` to restrict only group objects from being searched. The `-LDAPFilter` parameter can be used instead to query for multiple objects.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">ADPrincipalIdentity</command:parameterValue> <dev:type> <maml:name>ADPrincipalIdentity</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>None</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="none"> <maml:name>AuthType</maml:name> <maml:description> <maml:para>The authentication type to use when creating the `OpenAD` session. This is used when the cmdlet creates a new connection to the `-Server` specified`.</maml:para> </maml:description> <command:parameterValueGroup> <command:parameterValue required="false" command:variableLength="false">Default</command:parameterValue> <command:parameterValue required="false" command:variableLength="false">Anonymous</command:parameterValue> <command:parameterValue required="false" command:variableLength="false">Simple</command:parameterValue> <command:parameterValue required="false" command:variableLength="false">Negotiate</command:parameterValue> <command:parameterValue required="false" command:variableLength="false">Kerberos</command:parameterValue> </command:parameterValueGroup> <command:parameterValue required="true" variableLength="false">AuthenticationMethod</command:parameterValue> <dev:type> <maml:name>AuthenticationMethod</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>Default</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="none"> <maml:name>Credential</maml:name> <maml:description> <maml:para>The explicit credentials to use when creating the `OpenAD` session. This is used when the cmdlet creates a new connection to the `-Server` specified.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">PSCredential</command:parameterValue> <dev:type> <maml:name>PSCredential</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>None</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="Properties"> <maml:name>Property</maml:name> <maml:description> <maml:para>The attributes to retrieve for each group 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:</maml:para> <maml:para>+ `distinguishedName`</maml:para> <maml:para>+ `name`</maml:para> <maml:para>+ `objectClass`</maml:para> <maml:para>+ `objectGUID`</maml:para> <maml:para>+ `sAMAccountName`</maml:para> <maml:para>+ `objectSid`</maml:para> <maml:para>+ `groupType`</maml:para> <maml:para>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.</maml:para> <maml:para>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 `group` object class. If no connection has been created by the client then there is no tab completion available.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">String[]</command:parameterValue> <dev:type> <maml:name>String[]</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>None</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="none"> <maml:name>Server</maml:name> <maml:description> <maml:para>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.</maml:para> <maml:para>This option is mutually exclusive with `-Session`.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">String</command:parameterValue> <dev:type> <maml:name>String</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>None</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="none"> <maml:name>SessionOption</maml:name> <maml:description> <maml:para>Advanced session options used when creating a new session with `-Server`. These options can be generated with `New-OpenADSessionOption`.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">OpenADSessionOptions</command:parameterValue> <dev:type> <maml:name>OpenADSessionOptions</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>None</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="none"> <maml:name>StartTLS</maml:name> <maml:description> <maml:para>Use `StartTLS` when creating a new session with `-Server`.</maml:para> </maml:description> <dev:type> <maml:name>SwitchParameter</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>False</dev:defaultValue> </command:parameter> </command:syntaxItem> <command:syntaxItem> <maml:name>Get-OpenADGroup</maml:name> <command:parameter required="true" variableLength="true" globbing="false" pipelineInput="True (ByPropertyName, ByValue)" position="0" aliases="none"> <maml:name>Identity</maml:name> <maml:description> <maml:para>Specifies the Active Directory group object to search for using one fo the following formats:</maml:para> <maml:para>+ `DistinguishedName`</maml:para> <maml:para>+ `ObjectGUID`</maml:para> <maml:para>+ `ObjectSID`</maml:para> <maml:para>+ `UserPrincipalName`</maml:para> <maml:para>+ `SamAccountName`</maml:para> <maml:para>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=group)` to restrict only group objects from being searched. The `-LDAPFilter` parameter can be used instead to query for multiple objects.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">ADPrincipalIdentity</command:parameterValue> <dev:type> <maml:name>ADPrincipalIdentity</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>None</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="Properties"> <maml:name>Property</maml:name> <maml:description> <maml:para>The attributes to retrieve for each group 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:</maml:para> <maml:para>+ `distinguishedName`</maml:para> <maml:para>+ `name`</maml:para> <maml:para>+ `objectClass`</maml:para> <maml:para>+ `objectGUID`</maml:para> <maml:para>+ `sAMAccountName`</maml:para> <maml:para>+ `objectSid`</maml:para> <maml:para>+ `groupType`</maml:para> <maml:para>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.</maml:para> <maml:para>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 `group` object class. If no connection has been created by the client then there is no tab completion available.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">String[]</command:parameterValue> <dev:type> <maml:name>String[]</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>None</dev:defaultValue> </command:parameter> <command:parameter required="true" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="none"> <maml:name>Session</maml:name> <maml:description> <maml:para>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.</maml:para> <maml:para>This option is mutually exclusive with `-Server`.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">OpenADSession</command:parameterValue> <dev:type> <maml:name>OpenADSession</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>None</dev:defaultValue> </command:parameter> </command:syntaxItem> <command:syntaxItem> <maml:name>Get-OpenADGroup</maml:name> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="True (ByPropertyName)" position="named" aliases="none"> <maml:name>LDAPFilter</maml:name> <maml:description> <maml:para>Used instead of `-Identity` to specify an LDAP query used to filter group objects. The filter specified here will be used with an `AND` condition to `(objectCategory=group)`.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">String</command:parameterValue> <dev:type> <maml:name>String</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>None</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="Properties"> <maml:name>Property</maml:name> <maml:description> <maml:para>The attributes to retrieve for each group 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:</maml:para> <maml:para>+ `distinguishedName`</maml:para> <maml:para>+ `name`</maml:para> <maml:para>+ `objectClass`</maml:para> <maml:para>+ `objectGUID`</maml:para> <maml:para>+ `sAMAccountName`</maml:para> <maml:para>+ `objectSid`</maml:para> <maml:para>+ `groupType`</maml:para> <maml:para>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.</maml:para> <maml:para>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 `group` object class. If no connection has been created by the client then there is no tab completion available.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">String[]</command:parameterValue> <dev:type> <maml:name>String[]</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>None</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="none"> <maml:name>SearchBase</maml:name> <maml:description> <maml:para>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.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">String</command:parameterValue> <dev:type> <maml:name>String</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>None</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="none"> <maml:name>SearchScope</maml:name> <maml:description> <maml:para>Specifies the scope of an Active Directory search. This can be set to</maml:para> <maml:para>+ `Base` - Only searches the object at the `-SearchBase` path specified</maml:para> <maml:para>+ `OneLevel` - Searches the immediate children of `-SearchBase`</maml:para> <maml:para>+ `Subtree` (default) - Searches the children of `-SearchBase` and subsquent children of them</maml:para> </maml:description> <command:parameterValueGroup> <command:parameterValue required="false" command:variableLength="false">Base</command:parameterValue> <command:parameterValue required="false" command:variableLength="false">OneLevel</command:parameterValue> <command:parameterValue required="false" command:variableLength="false">Subtree</command:parameterValue> </command:parameterValueGroup> <command:parameterValue required="true" variableLength="false">SearchScope</command:parameterValue> <dev:type> <maml:name>SearchScope</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>Subtree</dev:defaultValue> </command:parameter> <command:parameter required="true" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="none"> <maml:name>Session</maml:name> <maml:description> <maml:para>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.</maml:para> <maml:para>This option is mutually exclusive with `-Server`.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">OpenADSession</command:parameterValue> <dev:type> <maml:name>OpenADSession</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>None</dev:defaultValue> </command:parameter> </command:syntaxItem> </command:syntax> <command:parameters> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="none"> <maml:name>AuthType</maml:name> <maml:description> <maml:para>The authentication type to use when creating the `OpenAD` session. This is used when the cmdlet creates a new connection to the `-Server` specified`.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">AuthenticationMethod</command:parameterValue> <dev:type> <maml:name>AuthenticationMethod</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>Default</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="none"> <maml:name>Credential</maml:name> <maml:description> <maml:para>The explicit credentials to use when creating the `OpenAD` session. This is used when the cmdlet creates a new connection to the `-Server` specified.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">PSCredential</command:parameterValue> <dev:type> <maml:name>PSCredential</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>None</dev:defaultValue> </command:parameter> <command:parameter required="true" variableLength="true" globbing="false" pipelineInput="True (ByPropertyName, ByValue)" position="0" aliases="none"> <maml:name>Identity</maml:name> <maml:description> <maml:para>Specifies the Active Directory group object to search for using one fo the following formats:</maml:para> <maml:para>+ `DistinguishedName`</maml:para> <maml:para>+ `ObjectGUID`</maml:para> <maml:para>+ `ObjectSID`</maml:para> <maml:para>+ `UserPrincipalName`</maml:para> <maml:para>+ `SamAccountName`</maml:para> <maml:para>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=group)` to restrict only group objects from being searched. The `-LDAPFilter` parameter can be used instead to query for multiple objects.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">ADPrincipalIdentity</command:parameterValue> <dev:type> <maml:name>ADPrincipalIdentity</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>None</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="True (ByPropertyName)" position="named" aliases="none"> <maml:name>LDAPFilter</maml:name> <maml:description> <maml:para>Used instead of `-Identity` to specify an LDAP query used to filter group objects. The filter specified here will be used with an `AND` condition to `(objectCategory=group)`.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">String</command:parameterValue> <dev:type> <maml:name>String</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>None</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="Properties"> <maml:name>Property</maml:name> <maml:description> <maml:para>The attributes to retrieve for each group 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:</maml:para> <maml:para>+ `distinguishedName`</maml:para> <maml:para>+ `name`</maml:para> <maml:para>+ `objectClass`</maml:para> <maml:para>+ `objectGUID`</maml:para> <maml:para>+ `sAMAccountName`</maml:para> <maml:para>+ `objectSid`</maml:para> <maml:para>+ `groupType`</maml:para> <maml:para>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.</maml:para> <maml:para>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 `group` object class. If no connection has been created by the client then there is no tab completion available.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">String[]</command:parameterValue> <dev:type> <maml:name>String[]</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>None</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="none"> <maml:name>SearchBase</maml:name> <maml:description> <maml:para>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.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">String</command:parameterValue> <dev:type> <maml:name>String</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>None</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="none"> <maml:name>SearchScope</maml:name> <maml:description> <maml:para>Specifies the scope of an Active Directory search. This can be set to</maml:para> <maml:para>+ `Base` - Only searches the object at the `-SearchBase` path specified</maml:para> <maml:para>+ `OneLevel` - Searches the immediate children of `-SearchBase`</maml:para> <maml:para>+ `Subtree` (default) - Searches the children of `-SearchBase` and subsquent children of them</maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">SearchScope</command:parameterValue> <dev:type> <maml:name>SearchScope</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>Subtree</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="none"> <maml:name>Server</maml:name> <maml:description> <maml:para>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.</maml:para> <maml:para>This option is mutually exclusive with `-Session`.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">String</command:parameterValue> <dev:type> <maml:name>String</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>None</dev:defaultValue> </command:parameter> <command:parameter required="true" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="none"> <maml:name>Session</maml:name> <maml:description> <maml:para>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.</maml:para> <maml:para>This option is mutually exclusive with `-Server`.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">OpenADSession</command:parameterValue> <dev:type> <maml:name>OpenADSession</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>None</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="none"> <maml:name>SessionOption</maml:name> <maml:description> <maml:para>Advanced session options used when creating a new session with `-Server`. These options can be generated with `New-OpenADSessionOption`.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">OpenADSessionOptions</command:parameterValue> <dev:type> <maml:name>OpenADSessionOptions</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>None</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="none"> <maml:name>StartTLS</maml:name> <maml:description> <maml:para>Use `StartTLS` when creating a new session with `-Server`.</maml:para> </maml:description> <command:parameterValue required="false" variableLength="false">SwitchParameter</command:parameterValue> <dev:type> <maml:name>SwitchParameter</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>False</dev:defaultValue> </command:parameter> </command:parameters> <command:inputTypes> <command:inputType> <dev:type> <maml:name>PSOpenAD.ADPrincipalIdentity</maml:name> </dev:type> <maml:description> <maml:para></maml:para> </maml:description> </command:inputType> <command:inputType> <dev:type> <maml:name>System.String</maml:name> </dev:type> <maml:description> <maml:para>The identity in it's various forms can be piped into the cmdlet.</maml:para> </maml:description> </command:inputType> </command:inputTypes> <command:returnValues> <command:returnValue> <dev:type> <maml:name>PSOpenAD.OpenADGroup</maml:name> </dev:type> <maml:description> <maml:para>The `OpenADGroup` representing the object(s) found. This object will always have the following properties set:</maml:para> <maml:para>+ `DistinguishedName`</maml:para> <maml:para>+ `Name`</maml:para> <maml:para>+ `ObjectClass`</maml:para> <maml:para>+ `ObjectGuid`</maml:para> <maml:para>+ `SamAccountName`</maml:para> <maml:para>+ `SID`</maml:para> <maml:para>+ `GroupCategory`</maml:para> <maml:para>+ `GroupScope`</maml:para> <maml:para>+ `DomainController`: This is set to the domain controller that processed the request</maml:para> <maml:para>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`.</maml:para> </maml:description> </command:returnValue> </command:returnValues> <maml:alertSet> <maml:alert> <maml:para>Unlike `Get-ADGroup`, if a group 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-ADGroup`.</maml:para> </maml:alert> </maml:alertSet> <command:examples> <command:example> <maml:title>--- Example 1: Get all groups in the target LDAP connection ---</maml:title> <dev:code>PS C:\> Get-OpenADGroup</dev:code> <dev:remarks> <maml:para>This command retrieves all AD groups objects (`(objectCategory=group)`) in the implicit AD connection.</maml:para> </dev:remarks> </command:example> <command:example> <maml:title>Example 2: Get specific group from a specific LDAP instance using the distinguished name</maml:title> <dev:code>PS C:\> Get-OpenADGroup -Identity "CN=Domain Admins,CN=Users,DC=domain,DC=test" -Server dc.domain.test</dev:code> <dev:remarks> <maml:para>This command retrieves the AD group object `Domain Admins` under `CN=Users,DC=domain,DC=test` from the specific LDAP server `dc.domain.test`.</maml:para> </dev:remarks> </command:example> <command:example> <maml:title>--- Example 3: Get all groups with a name starting with APP ---</maml:title> <dev:code>PS C:\> Get-OpenADGroup -LDAPFilter "(name=APP*)"</dev:code> <dev:remarks> <maml:para>This commands gets all the groups that have the `name` LDAP attribute that starts with `APP`.</maml:para> </dev:remarks> </command:example> <command:example> <maml:title>--------- Example 4: Get extra properties for a group ---------</maml:title> <dev:code>PS C:\> $filter = "(&(SAMAccountName=*TEST*)(adminCount>=5))" PS C:\> Get-OpenADGroup -LDAPFilter $filter -Property adminCount, description</dev:code> <dev:remarks> <maml:para>This command gets all groups that match the filter and also gets the LDAP attributes `adminCount` and `description` in addition to the default properties.</maml:para> </dev:remarks> </command:example> <command:example> <maml:title>---------- Example 5: Get all properties for a group ----------</maml:title> <dev:code>PS C:\> Get-OpenADGroup -Property *</dev:code> <dev:remarks> <maml:para>This command get all the group objects in addition to all the properties that have a value set.</maml:para> </dev:remarks> </command:example> </command:examples> <command:relatedLinks> <maml:navigationLink> <maml:linkText>Online Version:</maml:linkText> <maml:uri>https://www.github.com/jborean93/PSOpenAD/blob/main/docs/en-US/Get-OpenADGroup.md</maml:uri> </maml:navigationLink> <maml:navigationLink> <maml:linkText>Active Directory: LDAP Syntax Filters</maml:linkText> <maml:uri>https://social.technet.microsoft.com/wiki/contents/articles/5392.active-directory-ldap-syntax-filters.aspx</maml:uri> </maml:navigationLink> <maml:navigationLink> <maml:linkText>LDAP Filters</maml:linkText> <maml:uri>https://ldap.com/ldap-filters/</maml:uri> </maml:navigationLink> </command:relatedLinks> </command:command> <command:command xmlns:maml="http://schemas.microsoft.com/maml/2004/10" xmlns:command="http://schemas.microsoft.com/maml/dev/command/2004/10" xmlns:dev="http://schemas.microsoft.com/maml/dev/2004/10" xmlns:MSHelp="http://msdn.microsoft.com/mshelp"> <command:details> <command:name>Get-OpenADObject</command:name> <command:verb>Get</command:verb> <command:noun>OpenADObject</command:noun> <maml:description> <maml:para>Gets one or more Active Directory objects.</maml:para> </maml:description> </command:details> <maml:description> <maml:para>The `Get-OpenADObject` cmdlet gets an Active Directory object or performs a search to get multiple objects. Specifying no `-Identity` or `-LDAPFilter` parameter will result in a query of just `(objectClass=*)`. Otherwise that will be be used as an AND condition of the query specified by the caller, e.g. `(&(objectClass=*)(...))`.</maml:para> <maml:para>The `-Identity` parameter specifies an individual object to retreive. The identity for this cmdlet can either be the distinguished name or GUID.</maml:para> <maml:para>The `-LDAPFilter` parameter can be used to search for multiple obejcts using the LDAP query language. The filter can be combined with `-SearchBase` and `-SearchScope` to refine the search parameters used.</maml:para> <maml:para>The cmdlet communicates in one of three way:</maml:para> <maml:para>+ Using the implicit AD connection based on the current environment</maml:para> <maml:para>+ Using the `-Session` object specified</maml:para> <maml:para>+ Using a new or cached connection to the `-Server` specified</maml:para> <maml:para>For more information on Open AD sessions, see about_OpenADSessions (./about_OpenADSessions.md).</maml:para> <maml:para>The output for each object retrieves a default set of 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.</maml:para> </maml:description> <command:syntax> <command:syntaxItem> <maml:name>Get-OpenADObject</maml:name> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="none"> <maml:name>AuthType</maml:name> <maml:description> <maml:para>The authentication type to use when creating the `OpenAD` session. This is used when the cmdlet creates a new connection to the `-Server` specified`.</maml:para> </maml:description> <command:parameterValueGroup> <command:parameterValue required="false" command:variableLength="false">Default</command:parameterValue> <command:parameterValue required="false" command:variableLength="false">Anonymous</command:parameterValue> <command:parameterValue required="false" command:variableLength="false">Simple</command:parameterValue> <command:parameterValue required="false" command:variableLength="false">Negotiate</command:parameterValue> <command:parameterValue required="false" command:variableLength="false">Kerberos</command:parameterValue> </command:parameterValueGroup> <command:parameterValue required="true" variableLength="false">AuthenticationMethod</command:parameterValue> <dev:type> <maml:name>AuthenticationMethod</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>Default</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="none"> <maml:name>Credential</maml:name> <maml:description> <maml:para>The explicit credentials to use when creating the `OpenAD` session. This is used when the cmdlet creates a new connection to the `-Server` specified.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">PSCredential</command:parameterValue> <dev:type> <maml:name>PSCredential</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>None</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="none"> <maml:name>IncludeDeletedObjects</maml:name> <maml:description> <maml:para>Include objects that have been deleted and are sitting in the Active Directory recycling bin. Setting this option will include the following LDAP control codes on the query:</maml:para> <maml:para>+ Show Deleted Objects `1.2.840.113556.1.4.417`</maml:para> <maml:para>+ Show Deactivated Links `1.2.840.113556.1.4.2065`</maml:para> </maml:description> <dev:type> <maml:name>SwitchParameter</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>False</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="True (ByPropertyName)" position="named" aliases="none"> <maml:name>LDAPFilter</maml:name> <maml:description> <maml:para>Used instead of `-Identity` to specify an LDAP query used to filter objects.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">String</command:parameterValue> <dev:type> <maml:name>String</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>None</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="Properties"> <maml:name>Property</maml:name> <maml:description> <maml:para>The attributes to retrieve for each 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:</maml:para> <maml:para>+ `distinguishedName`</maml:para> <maml:para>+ `name`</maml:para> <maml:para>+ `objectClass`</maml:para> <maml:para>+ `objectGUID`</maml:para> <maml:para>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.</maml:para> <maml:para>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 `top` object class. If no connection has been created by the client then there is no tab completion available.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">String[]</command:parameterValue> <dev:type> <maml:name>String[]</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>None</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="none"> <maml:name>SearchBase</maml:name> <maml:description> <maml:para>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.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">String</command:parameterValue> <dev:type> <maml:name>String</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>None</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="none"> <maml:name>SearchScope</maml:name> <maml:description> <maml:para>Specifies the scope of an Active Directory search. This can be set to</maml:para> <maml:para>+ `Base` - Only searches the object at the `-SearchBase` path specified</maml:para> <maml:para>+ `OneLevel` - Searches the immediate children of `-SearchBase`</maml:para> <maml:para>+ `Subtree` (default) - Searches the children of `-SearchBase` and subsquent children of them</maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">SearchScope</command:parameterValue> <dev:type> <maml:name>SearchScope</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>Subtree</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="none"> <maml:name>Server</maml:name> <maml:description> <maml:para>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.</maml:para> <maml:para>This option is mutually exclusive with `-Session`.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">String</command:parameterValue> <dev:type> <maml:name>String</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>None</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="none"> <maml:name>SessionOption</maml:name> <maml:description> <maml:para>Advanced session options used when creating a new session with `-Server`. These options can be generated with `New-OpenADSessionOption`.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">OpenADSessionOptions</command:parameterValue> <dev:type> <maml:name>OpenADSessionOptions</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>None</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="none"> <maml:name>StartTLS</maml:name> <maml:description> <maml:para>Use `StartTLS` when creating a new session with `-Server`.</maml:para> </maml:description> <dev:type> <maml:name>SwitchParameter</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>False</dev:defaultValue> </command:parameter> </command:syntaxItem> <command:syntaxItem> <maml:name>Get-OpenADObject</maml:name> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="none"> <maml:name>AuthType</maml:name> <maml:description> <maml:para>The authentication type to use when creating the `OpenAD` session. This is used when the cmdlet creates a new connection to the `-Server` specified`.</maml:para> </maml:description> <command:parameterValueGroup> <command:parameterValue required="false" command:variableLength="false">Default</command:parameterValue> <command:parameterValue required="false" command:variableLength="false">Anonymous</command:parameterValue> <command:parameterValue required="false" command:variableLength="false">Simple</command:parameterValue> <command:parameterValue required="false" command:variableLength="false">Negotiate</command:parameterValue> <command:parameterValue required="false" command:variableLength="false">Kerberos</command:parameterValue> </command:parameterValueGroup> <command:parameterValue required="true" variableLength="false">AuthenticationMethod</command:parameterValue> <dev:type> <maml:name>AuthenticationMethod</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>Default</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="none"> <maml:name>Credential</maml:name> <maml:description> <maml:para>The explicit credentials to use when creating the `OpenAD` session. This is used when the cmdlet creates a new connection to the `-Server` specified.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">PSCredential</command:parameterValue> <dev:type> <maml:name>PSCredential</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>None</dev:defaultValue> </command:parameter> <command:parameter required="true" variableLength="true" globbing="false" pipelineInput="True (ByPropertyName, ByValue)" position="named" aliases="none"> <maml:name>Identity</maml:name> <maml:description> <maml:para>Specifies the Active Directory object to search for using one fo the following formats:</maml:para> <maml:para>+ `DistinguishedName`</maml:para> <maml:para>+ `ObjectGUID`</maml:para> <maml:para>The cmdlet writes an error if no, or multiple, objects are found based on the identity specified. The `-LDAPFilter` parameter can be used instead to query for multiple objects.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">ADObjectIdentity</command:parameterValue> <dev:type> <maml:name>ADObjectIdentity</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>None</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="none"> <maml:name>IncludeDeletedObjects</maml:name> <maml:description> <maml:para>Include objects that have been deleted and are sitting in the Active Directory recycling bin. Setting this option will include the following LDAP control codes on the query:</maml:para> <maml:para>+ Show Deleted Objects `1.2.840.113556.1.4.417`</maml:para> <maml:para>+ Show Deactivated Links `1.2.840.113556.1.4.2065`</maml:para> </maml:description> <dev:type> <maml:name>SwitchParameter</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>False</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="Properties"> <maml:name>Property</maml:name> <maml:description> <maml:para>The attributes to retrieve for each 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:</maml:para> <maml:para>+ `distinguishedName`</maml:para> <maml:para>+ `name`</maml:para> <maml:para>+ `objectClass`</maml:para> <maml:para>+ `objectGUID`</maml:para> <maml:para>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.</maml:para> <maml:para>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 `top` object class. If no connection has been created by the client then there is no tab completion available.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">String[]</command:parameterValue> <dev:type> <maml:name>String[]</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>None</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="none"> <maml:name>Server</maml:name> <maml:description> <maml:para>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.</maml:para> <maml:para>This option is mutually exclusive with `-Session`.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">String</command:parameterValue> <dev:type> <maml:name>String</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>None</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="none"> <maml:name>SessionOption</maml:name> <maml:description> <maml:para>Advanced session options used when creating a new session with `-Server`. These options can be generated with `New-OpenADSessionOption`.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">OpenADSessionOptions</command:parameterValue> <dev:type> <maml:name>OpenADSessionOptions</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>None</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="none"> <maml:name>StartTLS</maml:name> <maml:description> <maml:para>Use `StartTLS` when creating a new session with `-Server`.</maml:para> </maml:description> <dev:type> <maml:name>SwitchParameter</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>False</dev:defaultValue> </command:parameter> </command:syntaxItem> <command:syntaxItem> <maml:name>Get-OpenADObject</maml:name> <command:parameter required="true" variableLength="true" globbing="false" pipelineInput="True (ByPropertyName, ByValue)" position="named" aliases="none"> <maml:name>Identity</maml:name> <maml:description> <maml:para>Specifies the Active Directory object to search for using one fo the following formats:</maml:para> <maml:para>+ `DistinguishedName`</maml:para> <maml:para>+ `ObjectGUID`</maml:para> <maml:para>The cmdlet writes an error if no, or multiple, objects are found based on the identity specified. The `-LDAPFilter` parameter can be used instead to query for multiple objects.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">ADObjectIdentity</command:parameterValue> <dev:type> <maml:name>ADObjectIdentity</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>None</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="none"> <maml:name>IncludeDeletedObjects</maml:name> <maml:description> <maml:para>Include objects that have been deleted and are sitting in the Active Directory recycling bin. Setting this option will include the following LDAP control codes on the query:</maml:para> <maml:para>+ Show Deleted Objects `1.2.840.113556.1.4.417`</maml:para> <maml:para>+ Show Deactivated Links `1.2.840.113556.1.4.2065`</maml:para> </maml:description> <dev:type> <maml:name>SwitchParameter</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>False</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="Properties"> <maml:name>Property</maml:name> <maml:description> <maml:para>The attributes to retrieve for each 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:</maml:para> <maml:para>+ `distinguishedName`</maml:para> <maml:para>+ `name`</maml:para> <maml:para>+ `objectClass`</maml:para> <maml:para>+ `objectGUID`</maml:para> <maml:para>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.</maml:para> <maml:para>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 `top` object class. If no connection has been created by the client then there is no tab completion available.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">String[]</command:parameterValue> <dev:type> <maml:name>String[]</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>None</dev:defaultValue> </command:parameter> <command:parameter required="true" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="none"> <maml:name>Session</maml:name> <maml:description> <maml:para>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.</maml:para> <maml:para>This option is mutually exclusive with `-Server`.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">OpenADSession</command:parameterValue> <dev:type> <maml:name>OpenADSession</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>None</dev:defaultValue> </command:parameter> </command:syntaxItem> <command:syntaxItem> <maml:name>Get-OpenADObject</maml:name> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="none"> <maml:name>IncludeDeletedObjects</maml:name> <maml:description> <maml:para>Include objects that have been deleted and are sitting in the Active Directory recycling bin. Setting this option will include the following LDAP control codes on the query:</maml:para> <maml:para>+ Show Deleted Objects `1.2.840.113556.1.4.417`</maml:para> <maml:para>+ Show Deactivated Links `1.2.840.113556.1.4.2065`</maml:para> </maml:description> <dev:type> <maml:name>SwitchParameter</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>False</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="True (ByPropertyName)" position="named" aliases="none"> <maml:name>LDAPFilter</maml:name> <maml:description> <maml:para>Used instead of `-Identity` to specify an LDAP query used to filter objects.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">String</command:parameterValue> <dev:type> <maml:name>String</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>None</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="Properties"> <maml:name>Property</maml:name> <maml:description> <maml:para>The attributes to retrieve for each 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:</maml:para> <maml:para>+ `distinguishedName`</maml:para> <maml:para>+ `name`</maml:para> <maml:para>+ `objectClass`</maml:para> <maml:para>+ `objectGUID`</maml:para> <maml:para>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.</maml:para> <maml:para>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 `top` object class. If no connection has been created by the client then there is no tab completion available.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">String[]</command:parameterValue> <dev:type> <maml:name>String[]</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>None</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="none"> <maml:name>SearchBase</maml:name> <maml:description> <maml:para>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.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">String</command:parameterValue> <dev:type> <maml:name>String</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>None</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="none"> <maml:name>SearchScope</maml:name> <maml:description> <maml:para>Specifies the scope of an Active Directory search. This can be set to</maml:para> <maml:para>+ `Base` - Only searches the object at the `-SearchBase` path specified</maml:para> <maml:para>+ `OneLevel` - Searches the immediate children of `-SearchBase`</maml:para> <maml:para>+ `Subtree` (default) - Searches the children of `-SearchBase` and subsquent children of them</maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">SearchScope</command:parameterValue> <dev:type> <maml:name>SearchScope</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>Subtree</dev:defaultValue> </command:parameter> <command:parameter required="true" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="none"> <maml:name>Session</maml:name> <maml:description> <maml:para>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.</maml:para> <maml:para>This option is mutually exclusive with `-Server`.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">OpenADSession</command:parameterValue> <dev:type> <maml:name>OpenADSession</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>None</dev:defaultValue> </command:parameter> </command:syntaxItem> </command:syntax> <command:parameters> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="none"> <maml:name>AuthType</maml:name> <maml:description> <maml:para>The authentication type to use when creating the `OpenAD` session. This is used when the cmdlet creates a new connection to the `-Server` specified`.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">AuthenticationMethod</command:parameterValue> <dev:type> <maml:name>AuthenticationMethod</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>Default</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="none"> <maml:name>Credential</maml:name> <maml:description> <maml:para>The explicit credentials to use when creating the `OpenAD` session. This is used when the cmdlet creates a new connection to the `-Server` specified.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">PSCredential</command:parameterValue> <dev:type> <maml:name>PSCredential</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>None</dev:defaultValue> </command:parameter> <command:parameter required="true" variableLength="true" globbing="false" pipelineInput="True (ByPropertyName, ByValue)" position="named" aliases="none"> <maml:name>Identity</maml:name> <maml:description> <maml:para>Specifies the Active Directory object to search for using one fo the following formats:</maml:para> <maml:para>+ `DistinguishedName`</maml:para> <maml:para>+ `ObjectGUID`</maml:para> <maml:para>The cmdlet writes an error if no, or multiple, objects are found based on the identity specified. The `-LDAPFilter` parameter can be used instead to query for multiple objects.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">ADObjectIdentity</command:parameterValue> <dev:type> <maml:name>ADObjectIdentity</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>None</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="none"> <maml:name>IncludeDeletedObjects</maml:name> <maml:description> <maml:para>Include objects that have been deleted and are sitting in the Active Directory recycling bin. Setting this option will include the following LDAP control codes on the query:</maml:para> <maml:para>+ Show Deleted Objects `1.2.840.113556.1.4.417`</maml:para> <maml:para>+ Show Deactivated Links `1.2.840.113556.1.4.2065`</maml:para> </maml:description> <command:parameterValue required="false" variableLength="false">SwitchParameter</command:parameterValue> <dev:type> <maml:name>SwitchParameter</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>False</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="True (ByPropertyName)" position="named" aliases="none"> <maml:name>LDAPFilter</maml:name> <maml:description> <maml:para>Used instead of `-Identity` to specify an LDAP query used to filter objects.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">String</command:parameterValue> <dev:type> <maml:name>String</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>None</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="Properties"> <maml:name>Property</maml:name> <maml:description> <maml:para>The attributes to retrieve for each 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:</maml:para> <maml:para>+ `distinguishedName`</maml:para> <maml:para>+ `name`</maml:para> <maml:para>+ `objectClass`</maml:para> <maml:para>+ `objectGUID`</maml:para> <maml:para>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.</maml:para> <maml:para>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 `top` object class. If no connection has been created by the client then there is no tab completion available.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">String[]</command:parameterValue> <dev:type> <maml:name>String[]</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>None</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="none"> <maml:name>SearchBase</maml:name> <maml:description> <maml:para>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.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">String</command:parameterValue> <dev:type> <maml:name>String</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>None</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="none"> <maml:name>SearchScope</maml:name> <maml:description> <maml:para>Specifies the scope of an Active Directory search. This can be set to</maml:para> <maml:para>+ `Base` - Only searches the object at the `-SearchBase` path specified</maml:para> <maml:para>+ `OneLevel` - Searches the immediate children of `-SearchBase`</maml:para> <maml:para>+ `Subtree` (default) - Searches the children of `-SearchBase` and subsquent children of them</maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">SearchScope</command:parameterValue> <dev:type> <maml:name>SearchScope</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>Subtree</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="none"> <maml:name>Server</maml:name> <maml:description> <maml:para>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.</maml:para> <maml:para>This option is mutually exclusive with `-Session`.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">String</command:parameterValue> <dev:type> <maml:name>String</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>None</dev:defaultValue> </command:parameter> <command:parameter required="true" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="none"> <maml:name>Session</maml:name> <maml:description> <maml:para>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.</maml:para> <maml:para>This option is mutually exclusive with `-Server`.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">OpenADSession</command:parameterValue> <dev:type> <maml:name>OpenADSession</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>None</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="none"> <maml:name>SessionOption</maml:name> <maml:description> <maml:para>Advanced session options used when creating a new session with `-Server`. These options can be generated with `New-OpenADSessionOption`.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">OpenADSessionOptions</command:parameterValue> <dev:type> <maml:name>OpenADSessionOptions</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>None</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="none"> <maml:name>StartTLS</maml:name> <maml:description> <maml:para>Use `StartTLS` when creating a new session with `-Server`.</maml:para> </maml:description> <command:parameterValue required="false" variableLength="false">SwitchParameter</command:parameterValue> <dev:type> <maml:name>SwitchParameter</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>False</dev:defaultValue> </command:parameter> </command:parameters> <command:inputTypes> <command:inputType> <dev:type> <maml:name>PSOpenAD.ADObjectIdentity</maml:name> </dev:type> <maml:description> <maml:para>The identity to get can be passed in as an input object. This can be in the form of the Distinguished Name or Object GUID.</maml:para> </maml:description> </command:inputType> </command:inputTypes> <command:returnValues> <command:returnValue> <dev:type> <maml:name>PSOpenAD.OpenADObject</maml:name> </dev:type> <maml:description> <maml:para>The `OpenADObject` representing the object(s) found. This object will always have the following properties set:</maml:para> <maml:para>+ `DistinguishedName`</maml:para> <maml:para>+ `Name`</maml:para> <maml:para>+ `ObjectClass`</maml:para> <maml:para>+ `ObjectGuid`</maml:para> <maml:para>+ `DomainController`: This is set to the domain controller that processed the request</maml:para> <maml:para>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`.</maml:para> </maml:description> </command:returnValue> </command:returnValues> <maml:alertSet> <maml:alert> <maml:para>Unlike `Get-ADObject`, 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-ADObject`.</maml:para> </maml:alert> </maml:alertSet> <command:examples> <command:example> <maml:title>Example 1: Get the sites for a domain using LDAP filter syntax</maml:title> <dev:code>PS C:\> $getParams @{ .. LDAPFilter = "(objectClass=site)" .. SearchBase = 'CN=Configuration,DC=Fabrikam,DC=Com' .. Properties = "canonicalName" .. } PS C:\> Get-OpenADObject @getParams | Select-Object Name, canonicalName</dev:code> <dev:remarks> <maml:para>This command displays a list of sites for Fabrikam using the LDAP filter syntax.</maml:para> </dev:remarks> </command:example> <command:example> <maml:title>Example 2: Get information for a specified object of an LDAP instance</maml:title> <dev:code>PS C:\> Get-OpenADObject -Identity "DC=AppNC" -Server "FABRIKAM-SRV1"</dev:code> <dev:remarks> <maml:para>This command gets the information of the domainDNS object from an explicit Active Directory.</maml:para> </dev:remarks> </command:example> <command:example> <maml:title>---------------- Example 3: Get deleted objects ----------------</maml:title> <dev:code>PS C:\> Get-OpenADObject -IncludeDeletedObjects</dev:code> <dev:remarks> <maml:para>This command gets all AD objects that have been deleted and are currently sitting in the recycling bin. Please note this will not return any deleted objects if the recycling bin is disabled or the object has been removed from the bin itself.</maml:para> </dev:remarks> </command:example> </command:examples> <command:relatedLinks> <maml:navigationLink> <maml:linkText>Online Version:</maml:linkText> <maml:uri>https://www.github.com/jborean93/PSOpenAD/blob/main/docs/en-US/Get-OpenADObject.md</maml:uri> </maml:navigationLink> <maml:navigationLink> <maml:linkText>Active Directory: LDAP Syntax Filters</maml:linkText> <maml:uri>https://social.technet.microsoft.com/wiki/contents/articles/5392.active-directory-ldap-syntax-filters.aspx</maml:uri> </maml:navigationLink> <maml:navigationLink> <maml:linkText>LDAP Filters</maml:linkText> <maml:uri>https://ldap.com/ldap-filters/</maml:uri> </maml:navigationLink> </command:relatedLinks> </command:command> <command:command xmlns:maml="http://schemas.microsoft.com/maml/2004/10" xmlns:command="http://schemas.microsoft.com/maml/dev/command/2004/10" xmlns:dev="http://schemas.microsoft.com/maml/dev/2004/10" xmlns:MSHelp="http://msdn.microsoft.com/mshelp"> <command:details> <command:name>Get-OpenADServiceAccount</command:name> <command:verb>Get</command:verb> <command:noun>OpenADServiceAccount</command:noun> <maml:description> <maml:para>Gets one or more Active Directory managed service accounts or group managed service accounts.</maml:para> </maml:description> </command:details> <maml:description> <maml:para>The `Get-OpenADServiceAccount` cmdlet gets a service account or perforams a search to retrieve multiple service accounts. Specifying no `-Identity` or `-LDAPFilter` parameter will result in a query of just `(objectCategory=msDS-GroupManagedServiceAccount)`. Otherwise that will be be used as an AND condition of the query specified by the caller, e.g. `(&(objectCategory=msDS-GroupManagedServiceAccount)(...))`.</maml:para> <maml:para>The `-Identity` parameter specifies the Active Directory service account to retrieve. You can identify a service account by its distinguished name, GUID, security identifier, user principal name, or SAM account name.</maml:para> <maml:para>The `-LDAPFilter` parameter can be used to retrieve multiple service account objects using the filter required. The LDAP filter value is in the form of an LDAP filter string.</maml:para> <maml:para>The cmdlet communicates with the LDAP server in one of three ways:</maml:para> <maml:para>+ Using the implicit AD connection based on the current environment</maml:para> <maml:para>+ Using the `-Session` object specified</maml:para> <maml:para>+ Using a new or cached connection to the `-Server` specified</maml:para> <maml:para>For more information on Open AD sessions, see about_OpenADSessions (./about_OpenADSessions.md).</maml:para> <maml:para>The output for each service account retrieves a default set of service account 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.</maml:para> </maml:description> <command:syntax> <command:syntaxItem> <maml:name>Get-OpenADServiceAccount</maml:name> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="none"> <maml:name>AuthType</maml:name> <maml:description> <maml:para>The authentication type to use when creating the `OpenAD` session. This is used when the cmdlet creates a new connection to the `-Server` specified`.</maml:para> </maml:description> <command:parameterValueGroup> <command:parameterValue required="false" command:variableLength="false">Default</command:parameterValue> <command:parameterValue required="false" command:variableLength="false">Anonymous</command:parameterValue> <command:parameterValue required="false" command:variableLength="false">Simple</command:parameterValue> <command:parameterValue required="false" command:variableLength="false">Negotiate</command:parameterValue> <command:parameterValue required="false" command:variableLength="false">Kerberos</command:parameterValue> </command:parameterValueGroup> <command:parameterValue required="true" variableLength="false">AuthenticationMethod</command:parameterValue> <dev:type> <maml:name>AuthenticationMethod</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>Default</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="none"> <maml:name>Credential</maml:name> <maml:description> <maml:para>The explicit credentials to use when creating the `OpenAD` session. This is used when the cmdlet creates a new connection to the `-Server` specified.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">PSCredential</command:parameterValue> <dev:type> <maml:name>PSCredential</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>None</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="True (ByPropertyName)" position="named" aliases="none"> <maml:name>LDAPFilter</maml:name> <maml:description> <maml:para>Used instead of `-Identity` to specify an LDAP query used to filter service account objects. The filter specified here will be used with an `AND` condition to `(objectCategory=msDS-GroupManagedServiceAccount)`.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">String</command:parameterValue> <dev:type> <maml:name>String</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>None</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="Properties"> <maml:name>Property</maml:name> <maml:description> <maml:para>The attributes to retrieve for each service account 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:</maml:para> <maml:para>+ `distinguishedName`</maml:para> <maml:para>+ `name`</maml:para> <maml:para>+ `objectClass`</maml:para> <maml:para>+ `objectGUID`</maml:para> <maml:para>+ `sAMAccountName`</maml:para> <maml:para>+ `objectSid`</maml:para> <maml:para>+ `userPrincipalName`</maml:para> <maml:para>+ `servicePrincipalName`</maml:para> <maml:para>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.</maml:para> <maml:para>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 `msDS-GroupManagedServiceAccount` object class. If no connection has been created by the client then there is no tab completion available.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">String[]</command:parameterValue> <dev:type> <maml:name>String[]</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>None</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="none"> <maml:name>SearchBase</maml:name> <maml:description> <maml:para>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.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">String</command:parameterValue> <dev:type> <maml:name>String</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>None</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="none"> <maml:name>SearchScope</maml:name> <maml:description> <maml:para>Specifies the scope of an Active Directory search. This can be set to</maml:para> <maml:para>+ `Base` - Only searches the object at the `-SearchBase` path specified</maml:para> <maml:para>+ `OneLevel` - Searches the immediate children of `-SearchBase`</maml:para> <maml:para>+ `Subtree` (default) - Searches the children of `-SearchBase` and subsquent children of them</maml:para> </maml:description> <command:parameterValueGroup> <command:parameterValue required="false" command:variableLength="false">Base</command:parameterValue> <command:parameterValue required="false" command:variableLength="false">OneLevel</command:parameterValue> <command:parameterValue required="false" command:variableLength="false">Subtree</command:parameterValue> </command:parameterValueGroup> <command:parameterValue required="true" variableLength="false">SearchScope</command:parameterValue> <dev:type> <maml:name>SearchScope</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>Subtree</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="none"> <maml:name>Server</maml:name> <maml:description> <maml:para>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.</maml:para> <maml:para>This option is mutually exclusive with `-Session`.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">String</command:parameterValue> <dev:type> <maml:name>String</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>None</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="none"> <maml:name>SessionOption</maml:name> <maml:description> <maml:para>Advanced session options used when creating a new session with `-Server`. These options can be generated with `New-OpenADSessionOption`.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">OpenADSessionOptions</command:parameterValue> <dev:type> <maml:name>OpenADSessionOptions</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>None</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="none"> <maml:name>StartTLS</maml:name> <maml:description> <maml:para>Use `StartTLS` when creating a new session with `-Server`.</maml:para> </maml:description> <dev:type> <maml:name>SwitchParameter</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>False</dev:defaultValue> </command:parameter> </command:syntaxItem> <command:syntaxItem> <maml:name>Get-OpenADServiceAccount</maml:name> <command:parameter required="true" variableLength="true" globbing="false" pipelineInput="True (ByPropertyName, ByValue)" position="0" aliases="none"> <maml:name>Identity</maml:name> <maml:description> <maml:para>Specifies the Active Directory service account object to search for using one fo the following formats:</maml:para> <maml:para>+ `DistinguishedName`</maml:para> <maml:para>+ `ObjectGUID`</maml:para> <maml:para>+ `ObjectSID`</maml:para> <maml:para>+ `UserPrincipalName`</maml:para> <maml:para>+ `SamAccountName`</maml:para> <maml:para>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=msDS-GroupManagedServiceAccount)` to restrict only service account objects from being searched. The `-LDAPFilter` parameter can be used instead to query for multiple objects.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">ADPrincipalIdentityWithDollar</command:parameterValue> <dev:type> <maml:name>ADPrincipalIdentityWithDollar</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>None</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="none"> <maml:name>AuthType</maml:name> <maml:description> <maml:para>The authentication type to use when creating the `OpenAD` session. This is used when the cmdlet creates a new connection to the `-Server` specified`.</maml:para> </maml:description> <command:parameterValueGroup> <command:parameterValue required="false" command:variableLength="false">Default</command:parameterValue> <command:parameterValue required="false" command:variableLength="false">Anonymous</command:parameterValue> <command:parameterValue required="false" command:variableLength="false">Simple</command:parameterValue> <command:parameterValue required="false" command:variableLength="false">Negotiate</command:parameterValue> <command:parameterValue required="false" command:variableLength="false">Kerberos</command:parameterValue> </command:parameterValueGroup> <command:parameterValue required="true" variableLength="false">AuthenticationMethod</command:parameterValue> <dev:type> <maml:name>AuthenticationMethod</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>Default</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="none"> <maml:name>Credential</maml:name> <maml:description> <maml:para>The explicit credentials to use when creating the `OpenAD` session. This is used when the cmdlet creates a new connection to the `-Server` specified.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">PSCredential</command:parameterValue> <dev:type> <maml:name>PSCredential</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>None</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="Properties"> <maml:name>Property</maml:name> <maml:description> <maml:para>The attributes to retrieve for each service account 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:</maml:para> <maml:para>+ `distinguishedName`</maml:para> <maml:para>+ `name`</maml:para> <maml:para>+ `objectClass`</maml:para> <maml:para>+ `objectGUID`</maml:para> <maml:para>+ `sAMAccountName`</maml:para> <maml:para>+ `objectSid`</maml:para> <maml:para>+ `userPrincipalName`</maml:para> <maml:para>+ `servicePrincipalName`</maml:para> <maml:para>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.</maml:para> <maml:para>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 `msDS-GroupManagedServiceAccount` object class. If no connection has been created by the client then there is no tab completion available.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">String[]</command:parameterValue> <dev:type> <maml:name>String[]</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>None</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="none"> <maml:name>Server</maml:name> <maml:description> <maml:para>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.</maml:para> <maml:para>This option is mutually exclusive with `-Session`.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">String</command:parameterValue> <dev:type> <maml:name>String</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>None</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="none"> <maml:name>SessionOption</maml:name> <maml:description> <maml:para>Advanced session options used when creating a new session with `-Server`. These options can be generated with `New-OpenADSessionOption`.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">OpenADSessionOptions</command:parameterValue> <dev:type> <maml:name>OpenADSessionOptions</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>None</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="none"> <maml:name>StartTLS</maml:name> <maml:description> <maml:para>Use `StartTLS` when creating a new session with `-Server`.</maml:para> </maml:description> <dev:type> <maml:name>SwitchParameter</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>False</dev:defaultValue> </command:parameter> </command:syntaxItem> <command:syntaxItem> <maml:name>Get-OpenADServiceAccount</maml:name> <command:parameter required="true" variableLength="true" globbing="false" pipelineInput="True (ByPropertyName, ByValue)" position="0" aliases="none"> <maml:name>Identity</maml:name> <maml:description> <maml:para>Specifies the Active Directory service account object to search for using one fo the following formats:</maml:para> <maml:para>+ `DistinguishedName`</maml:para> <maml:para>+ `ObjectGUID`</maml:para> <maml:para>+ `ObjectSID`</maml:para> <maml:para>+ `UserPrincipalName`</maml:para> <maml:para>+ `SamAccountName`</maml:para> <maml:para>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=msDS-GroupManagedServiceAccount)` to restrict only service account objects from being searched. The `-LDAPFilter` parameter can be used instead to query for multiple objects.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">ADPrincipalIdentityWithDollar</command:parameterValue> <dev:type> <maml:name>ADPrincipalIdentityWithDollar</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>None</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="Properties"> <maml:name>Property</maml:name> <maml:description> <maml:para>The attributes to retrieve for each service account 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:</maml:para> <maml:para>+ `distinguishedName`</maml:para> <maml:para>+ `name`</maml:para> <maml:para>+ `objectClass`</maml:para> <maml:para>+ `objectGUID`</maml:para> <maml:para>+ `sAMAccountName`</maml:para> <maml:para>+ `objectSid`</maml:para> <maml:para>+ `userPrincipalName`</maml:para> <maml:para>+ `servicePrincipalName`</maml:para> <maml:para>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.</maml:para> <maml:para>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 `msDS-GroupManagedServiceAccount` object class. If no connection has been created by the client then there is no tab completion available.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">String[]</command:parameterValue> <dev:type> <maml:name>String[]</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>None</dev:defaultValue> </command:parameter> <command:parameter required="true" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="none"> <maml:name>Session</maml:name> <maml:description> <maml:para>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.</maml:para> <maml:para>This option is mutually exclusive with `-Server`.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">OpenADSession</command:parameterValue> <dev:type> <maml:name>OpenADSession</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>None</dev:defaultValue> </command:parameter> </command:syntaxItem> <command:syntaxItem> <maml:name>Get-OpenADServiceAccount</maml:name> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="True (ByPropertyName)" position="named" aliases="none"> <maml:name>LDAPFilter</maml:name> <maml:description> <maml:para>Used instead of `-Identity` to specify an LDAP query used to filter service account objects. The filter specified here will be used with an `AND` condition to `(objectCategory=msDS-GroupManagedServiceAccount)`.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">String</command:parameterValue> <dev:type> <maml:name>String</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>None</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="Properties"> <maml:name>Property</maml:name> <maml:description> <maml:para>The attributes to retrieve for each service account 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:</maml:para> <maml:para>+ `distinguishedName`</maml:para> <maml:para>+ `name`</maml:para> <maml:para>+ `objectClass`</maml:para> <maml:para>+ `objectGUID`</maml:para> <maml:para>+ `sAMAccountName`</maml:para> <maml:para>+ `objectSid`</maml:para> <maml:para>+ `userPrincipalName`</maml:para> <maml:para>+ `servicePrincipalName`</maml:para> <maml:para>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.</maml:para> <maml:para>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 `msDS-GroupManagedServiceAccount` object class. If no connection has been created by the client then there is no tab completion available.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">String[]</command:parameterValue> <dev:type> <maml:name>String[]</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>None</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="none"> <maml:name>SearchBase</maml:name> <maml:description> <maml:para>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.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">String</command:parameterValue> <dev:type> <maml:name>String</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>None</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="none"> <maml:name>SearchScope</maml:name> <maml:description> <maml:para>Specifies the scope of an Active Directory search. This can be set to</maml:para> <maml:para>+ `Base` - Only searches the object at the `-SearchBase` path specified</maml:para> <maml:para>+ `OneLevel` - Searches the immediate children of `-SearchBase`</maml:para> <maml:para>+ `Subtree` (default) - Searches the children of `-SearchBase` and subsquent children of them</maml:para> </maml:description> <command:parameterValueGroup> <command:parameterValue required="false" command:variableLength="false">Base</command:parameterValue> <command:parameterValue required="false" command:variableLength="false">OneLevel</command:parameterValue> <command:parameterValue required="false" command:variableLength="false">Subtree</command:parameterValue> </command:parameterValueGroup> <command:parameterValue required="true" variableLength="false">SearchScope</command:parameterValue> <dev:type> <maml:name>SearchScope</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>Subtree</dev:defaultValue> </command:parameter> <command:parameter required="true" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="none"> <maml:name>Session</maml:name> <maml:description> <maml:para>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.</maml:para> <maml:para>This option is mutually exclusive with `-Server`.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">OpenADSession</command:parameterValue> <dev:type> <maml:name>OpenADSession</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>None</dev:defaultValue> </command:parameter> </command:syntaxItem> </command:syntax> <command:parameters> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="none"> <maml:name>AuthType</maml:name> <maml:description> <maml:para>The authentication type to use when creating the `OpenAD` session. This is used when the cmdlet creates a new connection to the `-Server` specified`.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">AuthenticationMethod</command:parameterValue> <dev:type> <maml:name>AuthenticationMethod</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>Default</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="none"> <maml:name>Credential</maml:name> <maml:description> <maml:para>The explicit credentials to use when creating the `OpenAD` session. This is used when the cmdlet creates a new connection to the `-Server` specified.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">PSCredential</command:parameterValue> <dev:type> <maml:name>PSCredential</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>None</dev:defaultValue> </command:parameter> <command:parameter required="true" variableLength="true" globbing="false" pipelineInput="True (ByPropertyName, ByValue)" position="0" aliases="none"> <maml:name>Identity</maml:name> <maml:description> <maml:para>Specifies the Active Directory service account object to search for using one fo the following formats:</maml:para> <maml:para>+ `DistinguishedName`</maml:para> <maml:para>+ `ObjectGUID`</maml:para> <maml:para>+ `ObjectSID`</maml:para> <maml:para>+ `UserPrincipalName`</maml:para> <maml:para>+ `SamAccountName`</maml:para> <maml:para>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=msDS-GroupManagedServiceAccount)` to restrict only service account objects from being searched. The `-LDAPFilter` parameter can be used instead to query for multiple objects.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">ADPrincipalIdentityWithDollar</command:parameterValue> <dev:type> <maml:name>ADPrincipalIdentityWithDollar</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>None</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="True (ByPropertyName)" position="named" aliases="none"> <maml:name>LDAPFilter</maml:name> <maml:description> <maml:para>Used instead of `-Identity` to specify an LDAP query used to filter service account objects. The filter specified here will be used with an `AND` condition to `(objectCategory=msDS-GroupManagedServiceAccount)`.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">String</command:parameterValue> <dev:type> <maml:name>String</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>None</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="Properties"> <maml:name>Property</maml:name> <maml:description> <maml:para>The attributes to retrieve for each service account 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:</maml:para> <maml:para>+ `distinguishedName`</maml:para> <maml:para>+ `name`</maml:para> <maml:para>+ `objectClass`</maml:para> <maml:para>+ `objectGUID`</maml:para> <maml:para>+ `sAMAccountName`</maml:para> <maml:para>+ `objectSid`</maml:para> <maml:para>+ `userPrincipalName`</maml:para> <maml:para>+ `servicePrincipalName`</maml:para> <maml:para>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.</maml:para> <maml:para>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 `msDS-GroupManagedServiceAccount` object class. If no connection has been created by the client then there is no tab completion available.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">String[]</command:parameterValue> <dev:type> <maml:name>String[]</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>None</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="none"> <maml:name>SearchBase</maml:name> <maml:description> <maml:para>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.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">String</command:parameterValue> <dev:type> <maml:name>String</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>None</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="none"> <maml:name>SearchScope</maml:name> <maml:description> <maml:para>Specifies the scope of an Active Directory search. This can be set to</maml:para> <maml:para>+ `Base` - Only searches the object at the `-SearchBase` path specified</maml:para> <maml:para>+ `OneLevel` - Searches the immediate children of `-SearchBase`</maml:para> <maml:para>+ `Subtree` (default) - Searches the children of `-SearchBase` and subsquent children of them</maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">SearchScope</command:parameterValue> <dev:type> <maml:name>SearchScope</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>Subtree</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="none"> <maml:name>Server</maml:name> <maml:description> <maml:para>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.</maml:para> <maml:para>This option is mutually exclusive with `-Session`.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">String</command:parameterValue> <dev:type> <maml:name>String</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>None</dev:defaultValue> </command:parameter> <command:parameter required="true" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="none"> <maml:name>Session</maml:name> <maml:description> <maml:para>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.</maml:para> <maml:para>This option is mutually exclusive with `-Server`.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">OpenADSession</command:parameterValue> <dev:type> <maml:name>OpenADSession</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>None</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="none"> <maml:name>SessionOption</maml:name> <maml:description> <maml:para>Advanced session options used when creating a new session with `-Server`. These options can be generated with `New-OpenADSessionOption`.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">OpenADSessionOptions</command:parameterValue> <dev:type> <maml:name>OpenADSessionOptions</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>None</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="none"> <maml:name>StartTLS</maml:name> <maml:description> <maml:para>Use `StartTLS` when creating a new session with `-Server`.</maml:para> </maml:description> <command:parameterValue required="false" variableLength="false">SwitchParameter</command:parameterValue> <dev:type> <maml:name>SwitchParameter</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>False</dev:defaultValue> </command:parameter> </command:parameters> <command:inputTypes> <command:inputType> <dev:type> <maml:name>PSOpenAD.ADPrincipalIdentity</maml:name> </dev:type> <maml:description> <maml:para></maml:para> </maml:description> </command:inputType> <command:inputType> <dev:type> <maml:name>System.String</maml:name> </dev:type> <maml:description> <maml:para>The identity in it's various forms can be piped into the cmdlet.</maml:para> </maml:description> </command:inputType> </command:inputTypes> <command:returnValues> <command:returnValue> <dev:type> <maml:name>PSOpenAD.OpenADServiceAccount</maml:name> </dev:type> <maml:description> <maml:para>The `OpenADServiceAccount` representing the object(s) found. This object will always have the following properties set:</maml:para> <maml:para>+ `DistinguishedName`</maml:para> <maml:para>+ `Name`</maml:para> <maml:para>+ `ObjectClass`</maml:para> <maml:para>+ `ObjectGuid`</maml:para> <maml:para>+ `SamAccountName`</maml:para> <maml:para>+ `SID`</maml:para> <maml:para>+ `Enabled`</maml:para> <maml:para>+ `UserPrincipalName`</maml:para> <maml:para>+ `ServicePrincipalNames`</maml:para> <maml:para>+ `DomainController`: This is set to the domain controller that processed the request</maml:para> <maml:para>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`.</maml:para> </maml:description> </command:returnValue> </command:returnValues> <maml:alertSet> <maml:alert> <maml:para>Unlike `Get-OpenADServiceAccount`, if a service account 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-OpenADServiceAccount`.</maml:para> </maml:alert> </maml:alertSet> <command:examples> <command:example> <maml:title>Example 1: Get all service accounts in the target LDAP connection</maml:title> <dev:code>PS C:\> Get-OpenADServiceAccount</dev:code> <dev:remarks> <maml:para>This command retrieves all AD service account objects (`(objectCategory=msDS-GroupManagedServiceAccount)`) in the implicit AD connection.</maml:para> </dev:remarks> </command:example> <command:example> <maml:title>Example 2: Get specific service account from a specific LDAP instance using the distinguished name</maml:title> <dev:code>PS C:\> Get-OpenADServiceAccount -Identity "CN=mygMSA,CN=Managed Service Accounts,DC=domain,DC=test" -Server dc.domain.test</dev:code> <dev:remarks> <maml:para>This command retrieves the AD service account object `Workstation` under `OU=City,DC=domain,DC=test` from the specific LDAP server `dc.domain.test`.</maml:para> </dev:remarks> </command:example> <command:example> <maml:title>Example 3: Get all service accounts with a name starting with APP</maml:title> <dev:code>PS C:\> Get-OpenADServiceAccount -LDAPFilter "(name=APP*)"</dev:code> <dev:remarks> <maml:para>This commands gets all the service accounts that have the `name` LDAP attribute that starts with `APP`.</maml:para> </dev:remarks> </command:example> <command:example> <maml:title>---- Example 4: Get extra properties for a service account ----</maml:title> <dev:code>PS C:\> $filter = "(&(sAMAccountName=*APP*)(logonCount>=1))" PS C:\> Get-OpenADServiceAccount -LDAPFilter $filter -Property whenCreated, userAccountControl</dev:code> <dev:remarks> <maml:para>This command gets all service accounts that match the filter and also gets the LDAP attributes `whenCreated` and `userAccountControl` in addition to the default properties.</maml:para> </dev:remarks> </command:example> <command:example> <maml:title>----- Example 5: Get all properties for a service account -----</maml:title> <dev:code>PS C:\> Get-OpenADServiceAccount -Property *</dev:code> <dev:remarks> <maml:para>This command get all the service account objects in addition to all the properties that have a value set.</maml:para> </dev:remarks> </command:example> </command:examples> <command:relatedLinks> <maml:navigationLink> <maml:linkText>Online Version:</maml:linkText> <maml:uri>https://www.github.com/jborean93/PSOpenAD/blob/main/docs/en-US/Get-OpenADServiceAccount.md</maml:uri> </maml:navigationLink> <maml:navigationLink> <maml:linkText>Active Directory: LDAP Syntax Filters</maml:linkText> <maml:uri>https://social.technet.microsoft.com/wiki/contents/articles/5392.active-directory-ldap-syntax-filters.aspx</maml:uri> </maml:navigationLink> <maml:navigationLink> <maml:linkText>LDAP Filters</maml:linkText> <maml:uri>https://ldap.com/ldap-filters/</maml:uri> </maml:navigationLink> </command:relatedLinks> </command:command> <command:command xmlns:maml="http://schemas.microsoft.com/maml/2004/10" xmlns:command="http://schemas.microsoft.com/maml/dev/command/2004/10" xmlns:dev="http://schemas.microsoft.com/maml/dev/2004/10" xmlns:MSHelp="http://msdn.microsoft.com/mshelp"> <command:details> <command:name>Get-OpenADSession</command:name> <command:verb>Get</command:verb> <command:noun>OpenADSession</command:noun> <maml:description> <maml:para>Lists all the current OpenADSessions created by the client.</maml:para> </maml:description> </command:details> <maml:description> <maml:para>Outputs each Open AD session that has been opened by the client. These sessions contains connection details, such as the connection URI, authentication method used, encryption details. A session can then be explicitly closed with `Remove-OpenADSession` or used in any of the PSOpenAD cmdlets that accepts a `-Session` object.</maml:para> <maml:para>Each session in the pool were either created by an explicit call to `New-OpenADSession` or by any implicit sessions created when connecting to a new LDAP server.</maml:para> <maml:para>For more information on Open AD sessions, see about_OpenADSessions (./about_OpenADSessions.md).</maml:para> </maml:description> <command:syntax> <command:syntaxItem> <maml:name>Get-OpenADSession</maml:name> </command:syntaxItem> </command:syntax> <command:parameters /> <command:inputTypes> <command:inputType> <dev:type> <maml:name>None</maml:name> </dev:type> <maml:description> <maml:para></maml:para> </maml:description> </command:inputType> </command:inputTypes> <command:returnValues> <command:returnValue> <dev:type> <maml:name>PSOpenAD.OpenADSession</maml:name> </dev:type> <maml:description> <maml:para>The connected AD session that can be used as an explicit connection on the various `OpenAD` cmdlets. This object contains the following properties:</maml:para> <maml:para>+ `Id`: The unique identifier for this session in the process</maml:para> <maml:para>+ `Uri`: The full URI used to connect to the host</maml:para> <maml:para>+ `Authentication`: The authentication method used</maml:para> <maml:para>+ `IsSigned`: Whether the data on this connection will be signed</maml:para> <maml:para>+ `IsEncrypted`: Whether the data on this connection will be encrypted</maml:para> <maml:para>+ `OperationTimeout`: The timeout, in milliseconds, that set the maximum time to wait for a response for each LDAP operation</maml:para> <maml:para>+ `DefaultNamingContext`: The default naming context of the connected LDAP host used as the search base for future queries</maml:para> <maml:para>+ `IsClosed`: Whether the session is closed or not.</maml:para> </maml:description> </command:returnValue> </command:returnValues> <maml:alertSet> <maml:alert> <maml:para>Once a session has been removed with `Remove-OpenADSession` it will no longer appear in this output.</maml:para> </maml:alert> </maml:alertSet> <command:examples> <command:example> <maml:title>-------------- Example 1: Get all OpenAD sessions --------------</maml:title> <dev:code>PS C:\> Get-OpenADSession</dev:code> <dev:remarks> <maml:para>Gets all the OpenAD session objects created by the client.</maml:para> </dev:remarks> </command:example> </command:examples> <command:relatedLinks> <maml:navigationLink> <maml:linkText>Online Version:</maml:linkText> <maml:uri>https://www.github.com/jborean93/PSOpenAD/blob/main/docs/en-US/Get-OpenADSession.md</maml:uri> </maml:navigationLink> </command:relatedLinks> </command:command> <command:command xmlns:maml="http://schemas.microsoft.com/maml/2004/10" xmlns:command="http://schemas.microsoft.com/maml/dev/command/2004/10" xmlns:dev="http://schemas.microsoft.com/maml/dev/2004/10" xmlns:MSHelp="http://msdn.microsoft.com/mshelp"> <command:details> <command:name>Get-OpenADUser</command:name> <command:verb>Get</command:verb> <command:noun>OpenADUser</command:noun> <maml:description> <maml:para>Gets one or more Active Directory users.</maml:para> </maml:description> </command:details> <maml:description> <maml:para>The `Get-OpenADUser` cmdlet gets a user or perforams a search to retrieve multiple users. Specifying no `-Identity` or `-LDAPFilter` parameter will result in a query of just `(&(objectClass=user)(objectCategory=person))`. Otherwise that will be be used as an AND condition of the query specified by the caller, e.g. `(&(&(objectClass=user)(objectCategory=person))(...))`.</maml:para> <maml:para>The `-Identity` parameter specifies the Active Directory user to retrieve. You can identify a user by its distinguished name, GUID, security identifier, user principal name, or SAM account name.</maml:para> <maml:para>The `-LDAPFilter` parameter can be used to retrieve multiple user objects using the filter required. The LDAP filter value is in the form of an LDAP filter string.</maml:para> <maml:para>The cmdlet communicates with the LDAP server in one of three ways:</maml:para> <maml:para>+ Using the implicit AD connection based on the current environment</maml:para> <maml:para>+ Using the `-Session` object specified</maml:para> <maml:para>+ Using a new or cached connection to the `-Server` specified</maml:para> <maml:para>For more information on Open AD sessions, see about_OpenADSessions (./about_OpenADSessions.md).</maml:para> <maml:para>The output for each user retrieves a default set of user 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.</maml:para> </maml:description> <command:syntax> <command:syntaxItem> <maml:name>Get-OpenADUser</maml:name> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="none"> <maml:name>AuthType</maml:name> <maml:description> <maml:para>The authentication type to use when creating the `OpenAD` session. This is used when the cmdlet creates a new connection to the `-Server` specified`.</maml:para> </maml:description> <command:parameterValueGroup> <command:parameterValue required="false" command:variableLength="false">Default</command:parameterValue> <command:parameterValue required="false" command:variableLength="false">Anonymous</command:parameterValue> <command:parameterValue required="false" command:variableLength="false">Simple</command:parameterValue> <command:parameterValue required="false" command:variableLength="false">Negotiate</command:parameterValue> <command:parameterValue required="false" command:variableLength="false">Kerberos</command:parameterValue> </command:parameterValueGroup> <command:parameterValue required="true" variableLength="false">AuthenticationMethod</command:parameterValue> <dev:type> <maml:name>AuthenticationMethod</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>Default</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="none"> <maml:name>Credential</maml:name> <maml:description> <maml:para>The explicit credentials to use when creating the `OpenAD` session. This is used when the cmdlet creates a new connection to the `-Server` specified.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">PSCredential</command:parameterValue> <dev:type> <maml:name>PSCredential</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>None</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="True (ByPropertyName)" position="named" aliases="none"> <maml:name>LDAPFilter</maml:name> <maml:description> <maml:para>Used instead of `-Identity` to specify an LDAP query used to filter user objects. The filter specified here will be used with an `AND` condition to `(&(objectClass=user)(objectCategory=person))`.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">String</command:parameterValue> <dev:type> <maml:name>String</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>None</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="Properties"> <maml:name>Property</maml:name> <maml:description> <maml:para>The attributes to retrieve for each user 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:</maml:para> <maml:para>+ `distinguishedName`</maml:para> <maml:para>+ `name`</maml:para> <maml:para>+ `objectClass`</maml:para> <maml:para>+ `objectGUID`</maml:para> <maml:para>+ `sAMAccountName`</maml:para> <maml:para>+ `objectSid`</maml:para> <maml:para>+ `userPrincipalName`</maml:para> <maml:para>+ `givenName`</maml:para> <maml:para>+ `sn`</maml:para> <maml:para>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.</maml:para> <maml:para>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 `person` object class. If no connection has been created by the client then there is no tab completion available.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">String[]</command:parameterValue> <dev:type> <maml:name>String[]</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>None</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="none"> <maml:name>SearchBase</maml:name> <maml:description> <maml:para>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.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">String</command:parameterValue> <dev:type> <maml:name>String</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>None</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="none"> <maml:name>SearchScope</maml:name> <maml:description> <maml:para>Specifies the scope of an Active Directory search. This can be set to</maml:para> <maml:para>+ `Base` - Only searches the object at the `-SearchBase` path specified</maml:para> <maml:para>+ `OneLevel` - Searches the immediate children of `-SearchBase`</maml:para> <maml:para>+ `Subtree` (default) - Searches the children of `-SearchBase` and subsquent children of them</maml:para> </maml:description> <command:parameterValueGroup> <command:parameterValue required="false" command:variableLength="false">Base</command:parameterValue> <command:parameterValue required="false" command:variableLength="false">OneLevel</command:parameterValue> <command:parameterValue required="false" command:variableLength="false">Subtree</command:parameterValue> </command:parameterValueGroup> <command:parameterValue required="true" variableLength="false">SearchScope</command:parameterValue> <dev:type> <maml:name>SearchScope</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>Subtree</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="none"> <maml:name>Server</maml:name> <maml:description> <maml:para>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.</maml:para> <maml:para>This option is mutually exclusive with `-Session`.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">String</command:parameterValue> <dev:type> <maml:name>String</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>None</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="none"> <maml:name>SessionOption</maml:name> <maml:description> <maml:para>Advanced session options used when creating a new session with `-Server`. These options can be generated with `New-OpenADSessionOption`.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">OpenADSessionOptions</command:parameterValue> <dev:type> <maml:name>OpenADSessionOptions</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>None</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="none"> <maml:name>StartTLS</maml:name> <maml:description> <maml:para>Use `StartTLS` when creating a new session with `-Server`.</maml:para> </maml:description> <dev:type> <maml:name>SwitchParameter</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>False</dev:defaultValue> </command:parameter> </command:syntaxItem> <command:syntaxItem> <maml:name>Get-OpenADUser</maml:name> <command:parameter required="true" variableLength="true" globbing="false" pipelineInput="True (ByPropertyName, ByValue)" position="0" aliases="none"> <maml:name>Identity</maml:name> <maml:description> <maml:para>Specifies the Active Directory user object to search for using one fo the following formats:</maml:para> <maml:para>+ `DistinguishedName`</maml:para> <maml:para>+ `ObjectGUID`</maml:para> <maml:para>+ `ObjectSID`</maml:para> <maml:para>+ `UserPrincipalName`</maml:para> <maml:para>+ `SamAccountName`</maml:para> <maml:para>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 `(&(objectClass=user)(objectCategory=person))` to restrict only user objects from being searched. The `-LDAPFilter` parameter can be used instead to query for multiple objects.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">ADPrincipalIdentity</command:parameterValue> <dev:type> <maml:name>ADPrincipalIdentity</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>None</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="none"> <maml:name>AuthType</maml:name> <maml:description> <maml:para>The authentication type to use when creating the `OpenAD` session. This is used when the cmdlet creates a new connection to the `-Server` specified`.</maml:para> </maml:description> <command:parameterValueGroup> <command:parameterValue required="false" command:variableLength="false">Default</command:parameterValue> <command:parameterValue required="false" command:variableLength="false">Anonymous</command:parameterValue> <command:parameterValue required="false" command:variableLength="false">Simple</command:parameterValue> <command:parameterValue required="false" command:variableLength="false">Negotiate</command:parameterValue> <command:parameterValue required="false" command:variableLength="false">Kerberos</command:parameterValue> </command:parameterValueGroup> <command:parameterValue required="true" variableLength="false">AuthenticationMethod</command:parameterValue> <dev:type> <maml:name>AuthenticationMethod</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>Default</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="none"> <maml:name>Credential</maml:name> <maml:description> <maml:para>The explicit credentials to use when creating the `OpenAD` session. This is used when the cmdlet creates a new connection to the `-Server` specified.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">PSCredential</command:parameterValue> <dev:type> <maml:name>PSCredential</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>None</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="Properties"> <maml:name>Property</maml:name> <maml:description> <maml:para>The attributes to retrieve for each user 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:</maml:para> <maml:para>+ `distinguishedName`</maml:para> <maml:para>+ `name`</maml:para> <maml:para>+ `objectClass`</maml:para> <maml:para>+ `objectGUID`</maml:para> <maml:para>+ `sAMAccountName`</maml:para> <maml:para>+ `objectSid`</maml:para> <maml:para>+ `userPrincipalName`</maml:para> <maml:para>+ `givenName`</maml:para> <maml:para>+ `sn`</maml:para> <maml:para>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.</maml:para> <maml:para>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 `person` object class. If no connection has been created by the client then there is no tab completion available.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">String[]</command:parameterValue> <dev:type> <maml:name>String[]</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>None</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="none"> <maml:name>Server</maml:name> <maml:description> <maml:para>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.</maml:para> <maml:para>This option is mutually exclusive with `-Session`.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">String</command:parameterValue> <dev:type> <maml:name>String</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>None</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="none"> <maml:name>SessionOption</maml:name> <maml:description> <maml:para>Advanced session options used when creating a new session with `-Server`. These options can be generated with `New-OpenADSessionOption`.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">OpenADSessionOptions</command:parameterValue> <dev:type> <maml:name>OpenADSessionOptions</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>None</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="none"> <maml:name>StartTLS</maml:name> <maml:description> <maml:para>Use `StartTLS` when creating a new session with `-Server`.</maml:para> </maml:description> <dev:type> <maml:name>SwitchParameter</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>False</dev:defaultValue> </command:parameter> </command:syntaxItem> <command:syntaxItem> <maml:name>Get-OpenADUser</maml:name> <command:parameter required="true" variableLength="true" globbing="false" pipelineInput="True (ByPropertyName, ByValue)" position="0" aliases="none"> <maml:name>Identity</maml:name> <maml:description> <maml:para>Specifies the Active Directory user object to search for using one fo the following formats:</maml:para> <maml:para>+ `DistinguishedName`</maml:para> <maml:para>+ `ObjectGUID`</maml:para> <maml:para>+ `ObjectSID`</maml:para> <maml:para>+ `UserPrincipalName`</maml:para> <maml:para>+ `SamAccountName`</maml:para> <maml:para>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 `(&(objectClass=user)(objectCategory=person))` to restrict only user objects from being searched. The `-LDAPFilter` parameter can be used instead to query for multiple objects.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">ADPrincipalIdentity</command:parameterValue> <dev:type> <maml:name>ADPrincipalIdentity</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>None</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="Properties"> <maml:name>Property</maml:name> <maml:description> <maml:para>The attributes to retrieve for each user 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:</maml:para> <maml:para>+ `distinguishedName`</maml:para> <maml:para>+ `name`</maml:para> <maml:para>+ `objectClass`</maml:para> <maml:para>+ `objectGUID`</maml:para> <maml:para>+ `sAMAccountName`</maml:para> <maml:para>+ `objectSid`</maml:para> <maml:para>+ `userPrincipalName`</maml:para> <maml:para>+ `givenName`</maml:para> <maml:para>+ `sn`</maml:para> <maml:para>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.</maml:para> <maml:para>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 `person` object class. If no connection has been created by the client then there is no tab completion available.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">String[]</command:parameterValue> <dev:type> <maml:name>String[]</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>None</dev:defaultValue> </command:parameter> <command:parameter required="true" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="none"> <maml:name>Session</maml:name> <maml:description> <maml:para>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.</maml:para> <maml:para>This option is mutually exclusive with `-Server`.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">OpenADSession</command:parameterValue> <dev:type> <maml:name>OpenADSession</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>None</dev:defaultValue> </command:parameter> </command:syntaxItem> <command:syntaxItem> <maml:name>Get-OpenADUser</maml:name> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="True (ByPropertyName)" position="named" aliases="none"> <maml:name>LDAPFilter</maml:name> <maml:description> <maml:para>Used instead of `-Identity` to specify an LDAP query used to filter user objects. The filter specified here will be used with an `AND` condition to `(&(objectClass=user)(objectCategory=person))`.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">String</command:parameterValue> <dev:type> <maml:name>String</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>None</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="Properties"> <maml:name>Property</maml:name> <maml:description> <maml:para>The attributes to retrieve for each user 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:</maml:para> <maml:para>+ `distinguishedName`</maml:para> <maml:para>+ `name`</maml:para> <maml:para>+ `objectClass`</maml:para> <maml:para>+ `objectGUID`</maml:para> <maml:para>+ `sAMAccountName`</maml:para> <maml:para>+ `objectSid`</maml:para> <maml:para>+ `userPrincipalName`</maml:para> <maml:para>+ `givenName`</maml:para> <maml:para>+ `sn`</maml:para> <maml:para>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.</maml:para> <maml:para>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 `person` object class. If no connection has been created by the client then there is no tab completion available.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">String[]</command:parameterValue> <dev:type> <maml:name>String[]</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>None</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="none"> <maml:name>SearchBase</maml:name> <maml:description> <maml:para>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.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">String</command:parameterValue> <dev:type> <maml:name>String</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>None</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="none"> <maml:name>SearchScope</maml:name> <maml:description> <maml:para>Specifies the scope of an Active Directory search. This can be set to</maml:para> <maml:para>+ `Base` - Only searches the object at the `-SearchBase` path specified</maml:para> <maml:para>+ `OneLevel` - Searches the immediate children of `-SearchBase`</maml:para> <maml:para>+ `Subtree` (default) - Searches the children of `-SearchBase` and subsquent children of them</maml:para> </maml:description> <command:parameterValueGroup> <command:parameterValue required="false" command:variableLength="false">Base</command:parameterValue> <command:parameterValue required="false" command:variableLength="false">OneLevel</command:parameterValue> <command:parameterValue required="false" command:variableLength="false">Subtree</command:parameterValue> </command:parameterValueGroup> <command:parameterValue required="true" variableLength="false">SearchScope</command:parameterValue> <dev:type> <maml:name>SearchScope</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>Subtree</dev:defaultValue> </command:parameter> <command:parameter required="true" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="none"> <maml:name>Session</maml:name> <maml:description> <maml:para>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.</maml:para> <maml:para>This option is mutually exclusive with `-Server`.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">OpenADSession</command:parameterValue> <dev:type> <maml:name>OpenADSession</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>None</dev:defaultValue> </command:parameter> </command:syntaxItem> </command:syntax> <command:parameters> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="none"> <maml:name>AuthType</maml:name> <maml:description> <maml:para>The authentication type to use when creating the `OpenAD` session. This is used when the cmdlet creates a new connection to the `-Server` specified`.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">AuthenticationMethod</command:parameterValue> <dev:type> <maml:name>AuthenticationMethod</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>Default</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="none"> <maml:name>Credential</maml:name> <maml:description> <maml:para>The explicit credentials to use when creating the `OpenAD` session. This is used when the cmdlet creates a new connection to the `-Server` specified.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">PSCredential</command:parameterValue> <dev:type> <maml:name>PSCredential</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>None</dev:defaultValue> </command:parameter> <command:parameter required="true" variableLength="true" globbing="false" pipelineInput="True (ByPropertyName, ByValue)" position="0" aliases="none"> <maml:name>Identity</maml:name> <maml:description> <maml:para>Specifies the Active Directory user object to search for using one fo the following formats:</maml:para> <maml:para>+ `DistinguishedName`</maml:para> <maml:para>+ `ObjectGUID`</maml:para> <maml:para>+ `ObjectSID`</maml:para> <maml:para>+ `UserPrincipalName`</maml:para> <maml:para>+ `SamAccountName`</maml:para> <maml:para>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 `(&(objectClass=user)(objectCategory=person))` to restrict only user objects from being searched. The `-LDAPFilter` parameter can be used instead to query for multiple objects.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">ADPrincipalIdentity</command:parameterValue> <dev:type> <maml:name>ADPrincipalIdentity</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>None</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="True (ByPropertyName)" position="named" aliases="none"> <maml:name>LDAPFilter</maml:name> <maml:description> <maml:para>Used instead of `-Identity` to specify an LDAP query used to filter user objects. The filter specified here will be used with an `AND` condition to `(&(objectClass=user)(objectCategory=person))`.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">String</command:parameterValue> <dev:type> <maml:name>String</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>None</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="Properties"> <maml:name>Property</maml:name> <maml:description> <maml:para>The attributes to retrieve for each user 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:</maml:para> <maml:para>+ `distinguishedName`</maml:para> <maml:para>+ `name`</maml:para> <maml:para>+ `objectClass`</maml:para> <maml:para>+ `objectGUID`</maml:para> <maml:para>+ `sAMAccountName`</maml:para> <maml:para>+ `objectSid`</maml:para> <maml:para>+ `userPrincipalName`</maml:para> <maml:para>+ `givenName`</maml:para> <maml:para>+ `sn`</maml:para> <maml:para>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.</maml:para> <maml:para>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 `person` object class. If no connection has been created by the client then there is no tab completion available.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">String[]</command:parameterValue> <dev:type> <maml:name>String[]</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>None</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="none"> <maml:name>SearchBase</maml:name> <maml:description> <maml:para>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.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">String</command:parameterValue> <dev:type> <maml:name>String</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>None</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="none"> <maml:name>SearchScope</maml:name> <maml:description> <maml:para>Specifies the scope of an Active Directory search. This can be set to</maml:para> <maml:para>+ `Base` - Only searches the object at the `-SearchBase` path specified</maml:para> <maml:para>+ `OneLevel` - Searches the immediate children of `-SearchBase`</maml:para> <maml:para>+ `Subtree` (default) - Searches the children of `-SearchBase` and subsquent children of them</maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">SearchScope</command:parameterValue> <dev:type> <maml:name>SearchScope</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>Subtree</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="none"> <maml:name>Server</maml:name> <maml:description> <maml:para>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.</maml:para> <maml:para>This option is mutually exclusive with `-Session`.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">String</command:parameterValue> <dev:type> <maml:name>String</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>None</dev:defaultValue> </command:parameter> <command:parameter required="true" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="none"> <maml:name>Session</maml:name> <maml:description> <maml:para>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.</maml:para> <maml:para>This option is mutually exclusive with `-Server`.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">OpenADSession</command:parameterValue> <dev:type> <maml:name>OpenADSession</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>None</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="none"> <maml:name>SessionOption</maml:name> <maml:description> <maml:para>Advanced session options used when creating a new session with `-Server`. These options can be generated with `New-OpenADSessionOption`.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">OpenADSessionOptions</command:parameterValue> <dev:type> <maml:name>OpenADSessionOptions</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>None</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="none"> <maml:name>StartTLS</maml:name> <maml:description> <maml:para>Use `StartTLS` when creating a new session with `-Server`.</maml:para> </maml:description> <command:parameterValue required="false" variableLength="false">SwitchParameter</command:parameterValue> <dev:type> <maml:name>SwitchParameter</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>False</dev:defaultValue> </command:parameter> </command:parameters> <command:inputTypes> <command:inputType> <dev:type> <maml:name>PSOpenAD.ADPrincipalIdentity</maml:name> </dev:type> <maml:description> <maml:para></maml:para> </maml:description> </command:inputType> <command:inputType> <dev:type> <maml:name>System.String</maml:name> </dev:type> <maml:description> <maml:para>The identity in it's various forms can be piped into the cmdlet.</maml:para> </maml:description> </command:inputType> </command:inputTypes> <command:returnValues> <command:returnValue> <dev:type> <maml:name>PSOpenAD.OpenADUser</maml:name> </dev:type> <maml:description> <maml:para>The `OpenADUser` representing the object(s) found. This object will always have the following properties set:</maml:para> <maml:para>+ `DistinguishedName`</maml:para> <maml:para>+ `Name`</maml:para> <maml:para>+ `ObjectClass`</maml:para> <maml:para>+ `ObjectGuid`</maml:para> <maml:para>+ `SamAccountName`</maml:para> <maml:para>+ `SID`</maml:para> <maml:para>+ `Enabled`</maml:para> <maml:para>+ `UserPrincipalName`</maml:para> <maml:para>+ `Givenname`</maml:para> <maml:para>+ `Surname`</maml:para> <maml:para>+ `DomainController`: This is set to the domain controller that processed the request</maml:para> <maml:para>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`.</maml:para> </maml:description> </command:returnValue> </command:returnValues> <maml:alertSet> <maml:alert> <maml:para>Unlike `Get-ADUser`, if a user 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-ADUser`.</maml:para> </maml:alert> </maml:alertSet> <command:examples> <command:example> <maml:title>---- Example 1: Get all users in the target LDAP connection ----</maml:title> <dev:code>PS C:\> Get-OpenADUser</dev:code> <dev:remarks> <maml:para>This command retrieves all AD user objects (`(&(objectClass=user)(objectCategory=person))`) in the implicit AD connection.</maml:para> </dev:remarks> </command:example> <command:example> <maml:title>Example 2: Get specific user from a specific LDAP instance using the distinguished name</maml:title> <dev:code>PS C:\> Get-OpenADUser -Identity "CN=Administrator,CN=Users,DC=domain,DC=test" -Server dc.domain.test</dev:code> <dev:remarks> <maml:para>This command retrieves the AD user object `Administrator` under `CN=Users,DC=domain,DC=test` from the specific LDAP server `dc.domain.test`.</maml:para> </dev:remarks> </command:example> <command:example> <maml:title>---- Example 3: Get all user with a name starting with APP ----</maml:title> <dev:code>PS C:\> Get-OpenADUser -LDAPFilter "(name=APP*)"</dev:code> <dev:remarks> <maml:para>This commands gets all the users that have the `name` LDAP attribute that starts with `APP`.</maml:para> </dev:remarks> </command:example> <command:example> <maml:title>---------- Example 4: Get extra properties for a user ----------</maml:title> <dev:code>PS C:\> $filter = "(&(sAMAccountName=*USER*)(logonCount>=1))" PS C:\> Get-OpenADUser -LDAPFilter $filter -Property displayName, logonCount</dev:code> <dev:remarks> <maml:para>This command gets all users that match the filter and also gets the LDAP attributes `displayName` and `logonCount` in addition to the default properties.</maml:para> </dev:remarks> </command:example> <command:example> <maml:title>----------- Example 5: Get all properties for a user -----------</maml:title> <dev:code>PS C:\> Get-OpenADUser -Property *</dev:code> <dev:remarks> <maml:para>This command get all the user objects in addition to all the properties that have a value set.</maml:para> </dev:remarks> </command:example> </command:examples> <command:relatedLinks> <maml:navigationLink> <maml:linkText>Online Version:</maml:linkText> <maml:uri>https://www.github.com/jborean93/PSOpenAD/blob/main/docs/en-US/Get-OpenADUser.md</maml:uri> </maml:navigationLink> <maml:navigationLink> <maml:linkText>Active Directory: LDAP Syntax Filters</maml:linkText> <maml:uri>https://social.technet.microsoft.com/wiki/contents/articles/5392.active-directory-ldap-syntax-filters.aspx</maml:uri> </maml:navigationLink> <maml:navigationLink> <maml:linkText>LDAP Filters</maml:linkText> <maml:uri>https://ldap.com/ldap-filters/</maml:uri> </maml:navigationLink> </command:relatedLinks> </command:command> <command:command xmlns:maml="http://schemas.microsoft.com/maml/2004/10" xmlns:command="http://schemas.microsoft.com/maml/dev/command/2004/10" xmlns:dev="http://schemas.microsoft.com/maml/dev/2004/10" xmlns:MSHelp="http://msdn.microsoft.com/mshelp"> <command:details> <command:name>Get-OpenADWhoami</command:name> <command:verb>Get</command:verb> <command:noun>OpenADWhoami</command:noun> <maml:description> <maml:para>Performs an LDAP Whoami extended operation on the target server.</maml:para> </maml:description> </command:details> <maml:description> <maml:para>Performs the LDAP Whoami extended operation and outputs the username the server has authenticated the user as. This is useful for debugging purposes and just to test out a connection. Because this is an extended operation not all servers implement support for this. Active Directory based LDAP connections should work but this is not a guarantee for any other LDAP hosts.</maml:para> <maml:para>The cmdlet communicates with the LDAP server in one of three ways:</maml:para> <maml:para>+ Using the implicit AD connection based on the current environment</maml:para> <maml:para>+ Using the `-Session` object specified</maml:para> <maml:para>+ Using a new or cached connection to the `-Server` specified</maml:para> <maml:para>For more information on Open AD sessions, see about_OpenADSessions (./about_OpenADSessions.md).</maml:para> </maml:description> <command:syntax> <command:syntaxItem> <maml:name>Get-OpenADWhoami</maml:name> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="none"> <maml:name>AuthType</maml:name> <maml:description> <maml:para>The authentication type to use when creating the `OpenAD` session. This is used when the cmdlet creates a new connection to the `-Server` specified`.</maml:para> </maml:description> <command:parameterValueGroup> <command:parameterValue required="false" command:variableLength="false">Default</command:parameterValue> <command:parameterValue required="false" command:variableLength="false">Anonymous</command:parameterValue> <command:parameterValue required="false" command:variableLength="false">Simple</command:parameterValue> <command:parameterValue required="false" command:variableLength="false">Negotiate</command:parameterValue> <command:parameterValue required="false" command:variableLength="false">Kerberos</command:parameterValue> </command:parameterValueGroup> <command:parameterValue required="true" variableLength="false">AuthenticationMethod</command:parameterValue> <dev:type> <maml:name>AuthenticationMethod</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>Default</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="none"> <maml:name>Credential</maml:name> <maml:description> <maml:para>The explicit credentials to use when creating the `OpenAD` session. This is used when the cmdlet creates a new connection to the `-Server` specified.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">PSCredential</command:parameterValue> <dev:type> <maml:name>PSCredential</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>None</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="none"> <maml:name>Server</maml:name> <maml:description> <maml:para>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.</maml:para> <maml:para>This option is mutually exclusive with `-Session`.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">String</command:parameterValue> <dev:type> <maml:name>String</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>None</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="none"> <maml:name>SessionOption</maml:name> <maml:description> <maml:para>Advanced session options used when creating a new session with `-Server`. These options can be generated with `New-OpenADSessionOption`.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">OpenADSessionOptions</command:parameterValue> <dev:type> <maml:name>OpenADSessionOptions</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>None</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="none"> <maml:name>StartTLS</maml:name> <maml:description> <maml:para>Use `StartTLS` when creating a new session with `-Server`.</maml:para> </maml:description> <dev:type> <maml:name>SwitchParameter</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>False</dev:defaultValue> </command:parameter> </command:syntaxItem> <command:syntaxItem> <maml:name>Get-OpenADWhoami</maml:name> <command:parameter required="true" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="none"> <maml:name>Session</maml:name> <maml:description> <maml:para>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.</maml:para> <maml:para>This option is mutually exclusive with `-Server`.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">OpenADSession</command:parameterValue> <dev:type> <maml:name>OpenADSession</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>None</dev:defaultValue> </command:parameter> </command:syntaxItem> </command:syntax> <command:parameters> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="none"> <maml:name>AuthType</maml:name> <maml:description> <maml:para>The authentication type to use when creating the `OpenAD` session. This is used when the cmdlet creates a new connection to the `-Server` specified`.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">AuthenticationMethod</command:parameterValue> <dev:type> <maml:name>AuthenticationMethod</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>Default</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="none"> <maml:name>Credential</maml:name> <maml:description> <maml:para>The explicit credentials to use when creating the `OpenAD` session. This is used when the cmdlet creates a new connection to the `-Server` specified.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">PSCredential</command:parameterValue> <dev:type> <maml:name>PSCredential</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>None</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="none"> <maml:name>Server</maml:name> <maml:description> <maml:para>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.</maml:para> <maml:para>This option is mutually exclusive with `-Session`.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">String</command:parameterValue> <dev:type> <maml:name>String</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>None</dev:defaultValue> </command:parameter> <command:parameter required="true" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="none"> <maml:name>Session</maml:name> <maml:description> <maml:para>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.</maml:para> <maml:para>This option is mutually exclusive with `-Server`.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">OpenADSession</command:parameterValue> <dev:type> <maml:name>OpenADSession</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>None</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="none"> <maml:name>SessionOption</maml:name> <maml:description> <maml:para>Advanced session options used when creating a new session with `-Server`. These options can be generated with `New-OpenADSessionOption`.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">OpenADSessionOptions</command:parameterValue> <dev:type> <maml:name>OpenADSessionOptions</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>None</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="none"> <maml:name>StartTLS</maml:name> <maml:description> <maml:para>Use `StartTLS` when creating a new session with `-Server`.</maml:para> </maml:description> <command:parameterValue required="false" variableLength="false">SwitchParameter</command:parameterValue> <dev:type> <maml:name>SwitchParameter</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>False</dev:defaultValue> </command:parameter> </command:parameters> <command:inputTypes> <command:inputType> <dev:type> <maml:name>None</maml:name> </dev:type> <maml:description> <maml:para></maml:para> </maml:description> </command:inputType> </command:inputTypes> <command:returnValues> <command:returnValue> <dev:type> <maml:name>PSOpenAD.Commands.WhoamiResult</maml:name> </dev:type> <maml:description> <maml:para>The `WhoamiResult` object representing the result returned by the LDAP Whoami extended operation plus extra properties to provide extract context on the session. This object will always have the following properties set:</maml:para> <maml:para>+ `UserName`: The username, typically in the netlogon form `DOMAIN\username`, of the authenticated session.</maml:para> <maml:para>+ `Uri`: The LDAP URI used for the connection.</maml:para> <maml:para>+ `DomainController`: The DNS hostname of the domain controller the session is connected to.</maml:para> <maml:para>+ `Authentication`: The authentication method used to authenticate with the session.</maml:para> <maml:para>+ `RawUserName`: The raw string returned from the LDAP whoami extended operation.</maml:para> <maml:para>The `RawUserName` is not part of the default property sets and will display unless explicitly requested with `Select-Object *` or accessed manually `$result.RawUserName`.</maml:para> </maml:description> </command:returnValue> </command:returnValues> <maml:alertSet> <maml:alert> <maml:para></maml:para> </maml:alert> </maml:alertSet> <command:examples> <command:example> <maml:title>-------------- Example 1: Get connection username --------------</maml:title> <dev:code>PS C:\> $session = New-OpenADSession -ComputerName dc01.domain.test PS C:\> Get-OpenADWhoami -Session $session</dev:code> <dev:remarks> <maml:para>Creates a session and returns the Whoami result for that authenticated session.</maml:para> </dev:remarks> </command:example> <command:example> <maml:title>---- Example 2: Create cached session and get the username ----</maml:title> <dev:code>PS C:\> Get-OpenADWhoami -Server dc.contoso.com -StartTLS</dev:code> <dev:remarks> <maml:para>Creates a new connection with `StartTLS` to `dc.contoso.com`, caches the connection for future use. Once connected the LDAP Whoami operation is performed and the username is output to the caller.</maml:para> </dev:remarks> </command:example> </command:examples> <command:relatedLinks> <maml:navigationLink> <maml:linkText>Online Version:</maml:linkText> <maml:uri>https://www.github.com/jborean93/PSOpenAD/blob/main/docs/en-US/Get-OpenADWhoami.md</maml:uri> </maml:navigationLink> <maml:navigationLink> <maml:linkText>Who Am I Extended Operation</maml:linkText> <maml:uri>https://ldapwiki.com/wiki/Who%20Am%20I%20Extended%20Operation</maml:uri> </maml:navigationLink> </command:relatedLinks> </command:command> <command:command xmlns:maml="http://schemas.microsoft.com/maml/2004/10" xmlns:command="http://schemas.microsoft.com/maml/dev/command/2004/10" xmlns:dev="http://schemas.microsoft.com/maml/dev/2004/10" xmlns:MSHelp="http://msdn.microsoft.com/mshelp"> <command:details> <command:name>New-OpenADSession</command:name> <command:verb>New</command:verb> <command:noun>OpenADSession</command:noun> <maml:description> <maml:para>Creates an authenticated connection to an AD/LDAP host.</maml:para> </maml:description> </command:details> <maml:description> <maml:para>Connects and authenticates the client to an LDAP/AD host. The session created can then be used by other cmdlets to get/set data from the LDAP connection. When creating an `OpenAD` session, PowerShell will:</maml:para> <maml:para>+ Open a connection to the endpoint configured</maml:para> <maml:para>+ Perform the `StartTLS` extended operation if `-StartTLS` is specified.</maml:para> <maml:para>+ Bind/authenticate the client with the method specified</maml:para> <maml:para>+ Get the default naming context from the Root DSE used for subsequent queries on that connection</maml:para> <maml:para>+ Get the schema attribute and class object information used to parse the raw data returned by the server</maml:para> <maml:para>When the session is no longer needed, dispose of the connection using `Remove-OpenADSession`.</maml:para> <maml:para>For more information on Open AD sessions, see about_OpenADSessions (./about_OpenADSessions.md).</maml:para> </maml:description> <command:syntax> <command:syntaxItem> <maml:name>New-OpenADSession</maml:name> <command:parameter required="true" variableLength="true" globbing="false" pipelineInput="True (ByPropertyName, ByValue)" position="0" aliases="Server"> <maml:name>ComputerName</maml:name> <maml:description> <maml:para>The LDAP/AD host to connect to. This should be just the hostname, use `-ConnectionUri` to connect with a full LDAP URI.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">String</command:parameterValue> <dev:type> <maml:name>String</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>None</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="none"> <maml:name>AuthType</maml:name> <maml:description> <maml:para>The authentication type to use when authenticating the user. The available options are:</maml:para> <maml:para>+ `Default` - The default auth type used when one isn't explicitly defined</maml:para> <maml:para>+ `Anonymous` - No credentials are used, the user is treated as an anonymous user on the server</maml:para> <maml:para>+ `Simple` - Like HTTP Basic auth, the credentials are sent in plaintext to the server</maml:para> <maml:para>+ `Kerberos` - Uses the SASL `GSSAPI` mech which is configured for Kerberos authentication</maml:para> <maml:para>+ `Negotiate` - Uses the SASL `GSS-SPNEGO` mech which is configured for SPNEGO/Negotiate authentication</maml:para> <maml:para>The `Default` auth type will attempt to use `Negotiate` if it's available on the client. If it is not then it will fallback to `Simple` if both a credential is provided and TLS is used on the connection. Finally it falls back to `Anonymous` auth if all else fails.</maml:para> <maml:para>The `Anonymous` and `Simple` auth types are always available as the functionality is builtin to the LDAP client. When using `Simple` you should always use LDAPS or specify `-StartTLS` to encrypt the data. Failure to do so will expose both the username and password in plaintext on the network.</maml:para> <maml:para>The `Negotiate` authentication type will attempt to use `Kerberos` but potentially fallback to `NTLM` if it's available (Windows only). On non-Windows platforms `Negotiate` is essentially `Kerberos` but requires less requests to the server to complete the authentication phase.</maml:para> <maml:para>The `Kerberos` and `Negotiate` options both rely on a few factors before they are ready to use:</maml:para> <maml:para>+ Windows and macOS will always include support for both but may not be able to use `Kerberos` is the client cannot communicate with a domain</maml:para> <maml:para>+ Linux requires a GSSAPI library to be installed and configured for both `Negotiate` and `Kerberos` to work</maml:para> <maml:para>Use `Get-OpenADAuthSupport` to get more information around authentication.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">AuthenticationMethod</command:parameterValue> <dev:type> <maml:name>AuthenticationMethod</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>None</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="none"> <maml:name>Credential</maml:name> <maml:description> <maml:para>The username and password to authenticate with. This is only required when using `-AuthType Simple` other mechanisms can still use explicit credentials but can also rely on system wide caches, like `kinit`.</maml:para> <maml:para>If using `Negotiate` or `Kerberos` on non-Windows with an explicit credential the username should be in the `UPN` form `username@DOMAIN.COM`. The neglogon form `DOMAIN\username` will typically only work for Windows. A credential with a blank password (`[SecureString]::new()`) will attempt to lookup the username specified in the credential cache of the host and use that if present or fail if not present.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">PSCredential</command:parameterValue> <dev:type> <maml:name>PSCredential</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>None</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="none"> <maml:name>Port</maml:name> <maml:description> <maml:para>The LDAP port to connect to. This defaults to `389` for LDAP and `636` for LDAPS.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">Int32</command:parameterValue> <dev:type> <maml:name>Int32</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>None</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="none"> <maml:name>SessionOption</maml:name> <maml:description> <maml:para>Advanced sessions options to use when creating the connection. These session options can be generated by `New-OpenADSessionOption`.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">OpenADSessionOptions</command:parameterValue> <dev:type> <maml:name>OpenADSessionOptions</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>None</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="none"> <maml:name>StartTLS</maml:name> <maml:description> <maml:para>Use `StartTLS` over a standard LDAP connection. This is used to encrypt data sent over an LDAP connection before any subsequent traffic, like authentication details. Either `StartTLS` or an LDAPS connection should be used when `-AuthType Simple` to ensure the data exchanged is encrypted and the server's identity is verified.</maml:para> </maml:description> <dev:type> <maml:name>SwitchParameter</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>False</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="none"> <maml:name>UseTLS</maml:name> <maml:description> <maml:para>Connect over LDAPS rather than standard LDAP. Either `StartTLS` or an LDAPS connection should be used when `-AuthType Simple` to ensure the data exchanged is encrypted and the server's identity is verified.</maml:para> </maml:description> <dev:type> <maml:name>SwitchParameter</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>False</dev:defaultValue> </command:parameter> </command:syntaxItem> <command:syntaxItem> <maml:name>New-OpenADSession</maml:name> <command:parameter required="true" variableLength="true" globbing="false" pipelineInput="True (ByPropertyName)" position="0" aliases="none"> <maml:name>Uri</maml:name> <maml:description> <maml:para>Connect using the full LDAP URI. This is mutually exclusive with the `-ComputerName`, `-Port`, and `-UseTLS` options.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">Uri</command:parameterValue> <dev:type> <maml:name>Uri</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>None</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="none"> <maml:name>AuthType</maml:name> <maml:description> <maml:para>The authentication type to use when authenticating the user. The available options are:</maml:para> <maml:para>+ `Default` - The default auth type used when one isn't explicitly defined</maml:para> <maml:para>+ `Anonymous` - No credentials are used, the user is treated as an anonymous user on the server</maml:para> <maml:para>+ `Simple` - Like HTTP Basic auth, the credentials are sent in plaintext to the server</maml:para> <maml:para>+ `Kerberos` - Uses the SASL `GSSAPI` mech which is configured for Kerberos authentication</maml:para> <maml:para>+ `Negotiate` - Uses the SASL `GSS-SPNEGO` mech which is configured for SPNEGO/Negotiate authentication</maml:para> <maml:para>The `Default` auth type will attempt to use `Negotiate` if it's available on the client. If it is not then it will fallback to `Simple` if both a credential is provided and TLS is used on the connection. Finally it falls back to `Anonymous` auth if all else fails.</maml:para> <maml:para>The `Anonymous` and `Simple` auth types are always available as the functionality is builtin to the LDAP client. When using `Simple` you should always use LDAPS or specify `-StartTLS` to encrypt the data. Failure to do so will expose both the username and password in plaintext on the network.</maml:para> <maml:para>The `Negotiate` authentication type will attempt to use `Kerberos` but potentially fallback to `NTLM` if it's available (Windows only). On non-Windows platforms `Negotiate` is essentially `Kerberos` but requires less requests to the server to complete the authentication phase.</maml:para> <maml:para>The `Kerberos` and `Negotiate` options both rely on a few factors before they are ready to use:</maml:para> <maml:para>+ Windows and macOS will always include support for both but may not be able to use `Kerberos` is the client cannot communicate with a domain</maml:para> <maml:para>+ Linux requires a GSSAPI library to be installed and configured for both `Negotiate` and `Kerberos` to work</maml:para> <maml:para>Use `Get-OpenADAuthSupport` to get more information around authentication.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">AuthenticationMethod</command:parameterValue> <dev:type> <maml:name>AuthenticationMethod</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>None</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="none"> <maml:name>Credential</maml:name> <maml:description> <maml:para>The username and password to authenticate with. This is only required when using `-AuthType Simple` other mechanisms can still use explicit credentials but can also rely on system wide caches, like `kinit`.</maml:para> <maml:para>If using `Negotiate` or `Kerberos` on non-Windows with an explicit credential the username should be in the `UPN` form `username@DOMAIN.COM`. The neglogon form `DOMAIN\username` will typically only work for Windows. A credential with a blank password (`[SecureString]::new()`) will attempt to lookup the username specified in the credential cache of the host and use that if present or fail if not present.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">PSCredential</command:parameterValue> <dev:type> <maml:name>PSCredential</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>None</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="none"> <maml:name>SessionOption</maml:name> <maml:description> <maml:para>Advanced sessions options to use when creating the connection. These session options can be generated by `New-OpenADSessionOption`.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">OpenADSessionOptions</command:parameterValue> <dev:type> <maml:name>OpenADSessionOptions</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>None</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="none"> <maml:name>StartTLS</maml:name> <maml:description> <maml:para>Use `StartTLS` over a standard LDAP connection. This is used to encrypt data sent over an LDAP connection before any subsequent traffic, like authentication details. Either `StartTLS` or an LDAPS connection should be used when `-AuthType Simple` to ensure the data exchanged is encrypted and the server's identity is verified.</maml:para> </maml:description> <dev:type> <maml:name>SwitchParameter</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>False</dev:defaultValue> </command:parameter> </command:syntaxItem> </command:syntax> <command:parameters> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="none"> <maml:name>AuthType</maml:name> <maml:description> <maml:para>The authentication type to use when authenticating the user. The available options are:</maml:para> <maml:para>+ `Default` - The default auth type used when one isn't explicitly defined</maml:para> <maml:para>+ `Anonymous` - No credentials are used, the user is treated as an anonymous user on the server</maml:para> <maml:para>+ `Simple` - Like HTTP Basic auth, the credentials are sent in plaintext to the server</maml:para> <maml:para>+ `Kerberos` - Uses the SASL `GSSAPI` mech which is configured for Kerberos authentication</maml:para> <maml:para>+ `Negotiate` - Uses the SASL `GSS-SPNEGO` mech which is configured for SPNEGO/Negotiate authentication</maml:para> <maml:para>The `Default` auth type will attempt to use `Negotiate` if it's available on the client. If it is not then it will fallback to `Simple` if both a credential is provided and TLS is used on the connection. Finally it falls back to `Anonymous` auth if all else fails.</maml:para> <maml:para>The `Anonymous` and `Simple` auth types are always available as the functionality is builtin to the LDAP client. When using `Simple` you should always use LDAPS or specify `-StartTLS` to encrypt the data. Failure to do so will expose both the username and password in plaintext on the network.</maml:para> <maml:para>The `Negotiate` authentication type will attempt to use `Kerberos` but potentially fallback to `NTLM` if it's available (Windows only). On non-Windows platforms `Negotiate` is essentially `Kerberos` but requires less requests to the server to complete the authentication phase.</maml:para> <maml:para>The `Kerberos` and `Negotiate` options both rely on a few factors before they are ready to use:</maml:para> <maml:para>+ Windows and macOS will always include support for both but may not be able to use `Kerberos` is the client cannot communicate with a domain</maml:para> <maml:para>+ Linux requires a GSSAPI library to be installed and configured for both `Negotiate` and `Kerberos` to work</maml:para> <maml:para>Use `Get-OpenADAuthSupport` to get more information around authentication.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">AuthenticationMethod</command:parameterValue> <dev:type> <maml:name>AuthenticationMethod</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>None</dev:defaultValue> </command:parameter> <command:parameter required="true" variableLength="true" globbing="false" pipelineInput="True (ByPropertyName, ByValue)" position="0" aliases="Server"> <maml:name>ComputerName</maml:name> <maml:description> <maml:para>The LDAP/AD host to connect to. This should be just the hostname, use `-ConnectionUri` to connect with a full LDAP URI.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">String</command:parameterValue> <dev:type> <maml:name>String</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>None</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="none"> <maml:name>Credential</maml:name> <maml:description> <maml:para>The username and password to authenticate with. This is only required when using `-AuthType Simple` other mechanisms can still use explicit credentials but can also rely on system wide caches, like `kinit`.</maml:para> <maml:para>If using `Negotiate` or `Kerberos` on non-Windows with an explicit credential the username should be in the `UPN` form `username@DOMAIN.COM`. The neglogon form `DOMAIN\username` will typically only work for Windows. A credential with a blank password (`[SecureString]::new()`) will attempt to lookup the username specified in the credential cache of the host and use that if present or fail if not present.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">PSCredential</command:parameterValue> <dev:type> <maml:name>PSCredential</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>None</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="none"> <maml:name>Port</maml:name> <maml:description> <maml:para>The LDAP port to connect to. This defaults to `389` for LDAP and `636` for LDAPS.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">Int32</command:parameterValue> <dev:type> <maml:name>Int32</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>None</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="none"> <maml:name>SessionOption</maml:name> <maml:description> <maml:para>Advanced sessions options to use when creating the connection. These session options can be generated by `New-OpenADSessionOption`.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">OpenADSessionOptions</command:parameterValue> <dev:type> <maml:name>OpenADSessionOptions</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>None</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="none"> <maml:name>StartTLS</maml:name> <maml:description> <maml:para>Use `StartTLS` over a standard LDAP connection. This is used to encrypt data sent over an LDAP connection before any subsequent traffic, like authentication details. Either `StartTLS` or an LDAPS connection should be used when `-AuthType Simple` to ensure the data exchanged is encrypted and the server's identity is verified.</maml:para> </maml:description> <command:parameterValue required="false" variableLength="false">SwitchParameter</command:parameterValue> <dev:type> <maml:name>SwitchParameter</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>False</dev:defaultValue> </command:parameter> <command:parameter required="true" variableLength="true" globbing="false" pipelineInput="True (ByPropertyName)" position="0" aliases="none"> <maml:name>Uri</maml:name> <maml:description> <maml:para>Connect using the full LDAP URI. This is mutually exclusive with the `-ComputerName`, `-Port`, and `-UseTLS` options.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">Uri</command:parameterValue> <dev:type> <maml:name>Uri</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>None</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="none"> <maml:name>UseTLS</maml:name> <maml:description> <maml:para>Connect over LDAPS rather than standard LDAP. Either `StartTLS` or an LDAPS connection should be used when `-AuthType Simple` to ensure the data exchanged is encrypted and the server's identity is verified.</maml:para> </maml:description> <command:parameterValue required="false" variableLength="false">SwitchParameter</command:parameterValue> <dev:type> <maml:name>SwitchParameter</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>False</dev:defaultValue> </command:parameter> </command:parameters> <command:inputTypes> <command:inputType> <dev:type> <maml:name>System.Uri</maml:name> </dev:type> <maml:description> <maml:para>The full LDAP URI to connect to.</maml:para> </maml:description> </command:inputType> <command:inputType> <dev:type> <maml:name>System.String</maml:name> </dev:type> <maml:description> <maml:para>The LDAP/AD server name to connect to.</maml:para> </maml:description> </command:inputType> </command:inputTypes> <command:returnValues> <command:returnValue> <dev:type> <maml:name>PSOpenAD.OpenADSession</maml:name> </dev:type> <maml:description> <maml:para>The connected AD session that can be used as an explicit connection on the various `OpenAD` cmdlets. This object contains the following properties:</maml:para> <maml:para>+ `Id`: The unique identifier for this session in the process</maml:para> <maml:para>+ `Uri`: The full URI used to connect to the host</maml:para> <maml:para>+ `Authentication`: The authentication method used</maml:para> <maml:para>+ `DomainController`: The DNS hostname of the domain controller that the session is connected to</maml:para> <maml:para>+ `IsSigned`: Whether the data on this connection will be signed</maml:para> <maml:para>+ `IsEncrypted`: Whether the data on this connection will be encrypted</maml:para> <maml:para>+ `OperationTimeout`: The timeout, in milliseconds, that set the maximum time to wait for a response for each LDAP operation</maml:para> <maml:para>+ `DefaultNamingContext`: The default naming context of the connected LDAP host used as the search base for future queries</maml:para> <maml:para>+ `IsClosed`: Whether the session is closed or not.</maml:para> </maml:description> </command:returnValue> </command:returnValues> <maml:alertSet> <maml:alert> <maml:para>Once the connection has been successfully made the connection is placed in a cache and reused for any subsequent requests to the same URI. This will be removed from the cache when it is closed with `Remove-OpenADSession`.</maml:para> </maml:alert> </maml:alertSet> <command:examples> <command:example> <maml:title>-------- Example 1: Create a session using the defaults --------</maml:title> <dev:code>PS C:\> $session = New-OpenADSession -ComputerName dc01.domain.test</dev:code> <dev:remarks> <maml:para>Creates an `OpenAD` session to the domain controller at `dc01.domain.test`.</maml:para> </dev:remarks> </command:example> <command:example> <maml:title>---- Example 2: Create a session with explicit credentials ----</maml:title> <dev:code>PS C:\> $cred = Get-Credential PS C:\> $session = New-OpenADSession -ComputerName dc01 -Credential $cred</dev:code> <dev:remarks> <maml:para>Creates an `OpenAD` session to the domain controller at `dc01` using the credentials specified.</maml:para> </dev:remarks> </command:example> <command:example> <maml:title>- Example 3: Create a connection with SIMPLE auth and StartTLS -</maml:title> <dev:code>PS C:\> $cred = Get-Credential PS C:\> $session = New-OpenADSession -ComputerName dc -AuthType Simple -StartTLS -Credential $cred</dev:code> <dev:remarks> <maml:para>Creates an `OpenAD` session and upgrades the connection using `StartTLS`. Once the TLS handshake occurs the user is authenticated using the credentials specified. Because `StartTLS` is used, the SIMPLE auth exchange is encrypted and the credentials are not exposed on the network.</maml:para> </dev:remarks> </command:example> <command:example> <maml:title>------------ Example 4: Create an LDAPS connection ------------</maml:title> <dev:code>PS C:\> $session = New-OpenADSession -ComputerName dc -UseTLS</dev:code> <dev:remarks> <maml:para>Creates an `OpenAD` session using LDAPS.</maml:para> </dev:remarks> </command:example> <command:example> <maml:title>----- Example 5: Create a connection as an anonymous user -----</maml:title> <dev:code>PS C:\> $session = New-OpenADSession -ComputerName dc -AuthType Anonymous</dev:code> <dev:remarks> <maml:para>Creates an `OpenAD` session as an anonymous user. An anonymous user is typically limited in what it can do on the remote host.</maml:para> </dev:remarks> </command:example> </command:examples> <command:relatedLinks> <maml:navigationLink> <maml:linkText>Online Version:</maml:linkText> <maml:uri>https://www.github.com/jborean93/PSOpenAD/blob/main/docs/en-US/New-OpenADSession.md</maml:uri> </maml:navigationLink> </command:relatedLinks> </command:command> <command:command xmlns:maml="http://schemas.microsoft.com/maml/2004/10" xmlns:command="http://schemas.microsoft.com/maml/dev/command/2004/10" xmlns:dev="http://schemas.microsoft.com/maml/dev/2004/10" xmlns:MSHelp="http://msdn.microsoft.com/mshelp"> <command:details> <command:name>New-OpenADSessionOption</command:name> <command:verb>New</command:verb> <command:noun>OpenADSessionOption</command:noun> <maml:description> <maml:para>Creates an object that contains advanced options for an `OpenAD` session.</maml:para> </maml:description> </command:details> <maml:description> <maml:para>The cmdlet creates an object that contains advanced options for creating an LDAP connection. You can use this object as the value of `-SessionOption` parameter on cmdlets that create an `OpenAD` session. If no parameters are specified then the default `OpenAD` session options are used.</maml:para> </maml:description> <command:syntax> <command:syntaxItem> <maml:name>New-OpenADSessionOption</maml:name> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="none"> <maml:name>ClientCertificate</maml:name> <maml:description> <maml:para>The X.509 certificate to be used for the TLS client authentication. This is used for the `Certificate` authentication mechanism with the LDAP server using `StartTLS` or over `LDAPS`. The certificate must have access to the private key for it to be used with authentication. See the X509Certificate constructors (https://docs.microsoft.com/en-us/dotnet/api/system.security.cryptography.x509certificates.x509certificate.-ctor?view=net-6.0)to see how to create this object from a file.</maml:para> <maml:para>The certificate specified needs to be mapped to an account that is used for authorization checks. This mapping can be done either implicitly through a user cert requested by Active Directory Certificate Services (ADCS) or through an explicit mapping on the user object.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">X509Certificate</command:parameterValue> <dev:type> <maml:name>X509Certificate</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>None</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="none"> <maml:name>ConnectTimeout</maml:name> <maml:description> <maml:para>The timeout in milliseconds that the client will wait to connect to the target host.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">Int32</command:parameterValue> <dev:type> <maml:name>Int32</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>None</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="none"> <maml:name>NoChannelBinding</maml:name> <maml:description> <maml:para>Stops the LDAP client from adding channel binding data to the authentication bind operation. This is mostly used for debugging or disabling this operation on older LDAP hosts that may fail to authenticate a client with this data. It is recommended to not use this option unless you know what you are doing.</maml:para> </maml:description> <dev:type> <maml:name>SwitchParameter</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>False</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="none"> <maml:name>NoEncryption</maml:name> <maml:description> <maml:para>Disables SASL encryption used when exchanging data between the client and LDAP server over a non-TLS connection. Encryption is used by the `Negotiate` and `Kerberos` mechanisms when communicating over LDAP without `StartTLS`. Set this option to disable the encryption done by the client, beware this means any data exchanged over the network will be in plaintext. For either `Anonymous` or `Simple` this option has no affect as they do not have any encryption capabilities. For `Kerberos` this option will disable encryption but the data will still be signed for integrity checks. For `Negotiate` on Windows this will be the same as `Kerberos` but for `NTLM` this will do nothing as `NTLM` does not offer signature only wrappings. For `Negotiate` on non-Windows` this will do nothing as it cannot be disabled without also disabling signatures.</maml:para> </maml:description> <dev:type> <maml:name>SwitchParameter</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>False</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="none"> <maml:name>NoSigning</maml:name> <maml:description> <maml:para>Disables SASL signatures used when exchanging data between the client and LDAP server. These signatures ensure the data is not tampered with when it travelled across the network. This option must be set with `-NoEncryption` as encrypiton needs to be disabled for signatures to be disabled on an LDAP connection without `StartTLS`. This cannot be set when using `-StartTLS` or an `LDAPS` connection.</maml:para> <maml:para>For either `Anonymous` or `Simple` this option has no affect as they do not have any signing capabilities. For other auth methods this will disable any signatures and with encryption also disabled the messages are exchanged in plaintext.</maml:para> </maml:description> <dev:type> <maml:name>SwitchParameter</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>False</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="none"> <maml:name>OperationTimeout</maml:name> <maml:description> <maml:para>The time, in milliseconds to wait until an individual request like a search request to take before timing out.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">Int32</command:parameterValue> <dev:type> <maml:name>Int32</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>None</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="none"> <maml:name>SkipCertificateCheck</maml:name> <maml:description> <maml:para>Disables the TLS certificate checks done when connecting to an LDAPS endpoint or using `StartTLS`. This is useful when the server is using a self signed certificate for it's TLS context but should be avoided when being used in a production environment.</maml:para> </maml:description> <dev:type> <maml:name>SwitchParameter</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>False</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="none"> <maml:name>TracePath</maml:name> <maml:description> <maml:para>The path to a local file where incoming and outgoing LDAP messages will be written to. Each line in this path starts with either `RECV: ` or `SEND: ` and the value being the base64 encoded string of the LDAP message. Opening a new session with a trace path will create the new file path and will overwrite the existing path if it already exists. The directory the file is located in must already exist or else the session creation will fail. The contents of the LDAP messages can contain sensitive values so use this only for debugging purposes.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">String</command:parameterValue> <dev:type> <maml:name>String</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>None</dev:defaultValue> </command:parameter> </command:syntaxItem> </command:syntax> <command:parameters> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="none"> <maml:name>ClientCertificate</maml:name> <maml:description> <maml:para>The X.509 certificate to be used for the TLS client authentication. This is used for the `Certificate` authentication mechanism with the LDAP server using `StartTLS` or over `LDAPS`. The certificate must have access to the private key for it to be used with authentication. See the X509Certificate constructors (https://docs.microsoft.com/en-us/dotnet/api/system.security.cryptography.x509certificates.x509certificate.-ctor?view=net-6.0)to see how to create this object from a file.</maml:para> <maml:para>The certificate specified needs to be mapped to an account that is used for authorization checks. This mapping can be done either implicitly through a user cert requested by Active Directory Certificate Services (ADCS) or through an explicit mapping on the user object.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">X509Certificate</command:parameterValue> <dev:type> <maml:name>X509Certificate</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>None</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="none"> <maml:name>ConnectTimeout</maml:name> <maml:description> <maml:para>The timeout in milliseconds that the client will wait to connect to the target host.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">Int32</command:parameterValue> <dev:type> <maml:name>Int32</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>None</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="none"> <maml:name>NoChannelBinding</maml:name> <maml:description> <maml:para>Stops the LDAP client from adding channel binding data to the authentication bind operation. This is mostly used for debugging or disabling this operation on older LDAP hosts that may fail to authenticate a client with this data. It is recommended to not use this option unless you know what you are doing.</maml:para> </maml:description> <command:parameterValue required="false" variableLength="false">SwitchParameter</command:parameterValue> <dev:type> <maml:name>SwitchParameter</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>False</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="none"> <maml:name>NoEncryption</maml:name> <maml:description> <maml:para>Disables SASL encryption used when exchanging data between the client and LDAP server over a non-TLS connection. Encryption is used by the `Negotiate` and `Kerberos` mechanisms when communicating over LDAP without `StartTLS`. Set this option to disable the encryption done by the client, beware this means any data exchanged over the network will be in plaintext. For either `Anonymous` or `Simple` this option has no affect as they do not have any encryption capabilities. For `Kerberos` this option will disable encryption but the data will still be signed for integrity checks. For `Negotiate` on Windows this will be the same as `Kerberos` but for `NTLM` this will do nothing as `NTLM` does not offer signature only wrappings. For `Negotiate` on non-Windows` this will do nothing as it cannot be disabled without also disabling signatures.</maml:para> </maml:description> <command:parameterValue required="false" variableLength="false">SwitchParameter</command:parameterValue> <dev:type> <maml:name>SwitchParameter</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>False</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="none"> <maml:name>NoSigning</maml:name> <maml:description> <maml:para>Disables SASL signatures used when exchanging data between the client and LDAP server. These signatures ensure the data is not tampered with when it travelled across the network. This option must be set with `-NoEncryption` as encrypiton needs to be disabled for signatures to be disabled on an LDAP connection without `StartTLS`. This cannot be set when using `-StartTLS` or an `LDAPS` connection.</maml:para> <maml:para>For either `Anonymous` or `Simple` this option has no affect as they do not have any signing capabilities. For other auth methods this will disable any signatures and with encryption also disabled the messages are exchanged in plaintext.</maml:para> </maml:description> <command:parameterValue required="false" variableLength="false">SwitchParameter</command:parameterValue> <dev:type> <maml:name>SwitchParameter</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>False</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="none"> <maml:name>OperationTimeout</maml:name> <maml:description> <maml:para>The time, in milliseconds to wait until an individual request like a search request to take before timing out.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">Int32</command:parameterValue> <dev:type> <maml:name>Int32</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>None</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="none"> <maml:name>SkipCertificateCheck</maml:name> <maml:description> <maml:para>Disables the TLS certificate checks done when connecting to an LDAPS endpoint or using `StartTLS`. This is useful when the server is using a self signed certificate for it's TLS context but should be avoided when being used in a production environment.</maml:para> </maml:description> <command:parameterValue required="false" variableLength="false">SwitchParameter</command:parameterValue> <dev:type> <maml:name>SwitchParameter</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>False</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="none"> <maml:name>TracePath</maml:name> <maml:description> <maml:para>The path to a local file where incoming and outgoing LDAP messages will be written to. Each line in this path starts with either `RECV: ` or `SEND: ` and the value being the base64 encoded string of the LDAP message. Opening a new session with a trace path will create the new file path and will overwrite the existing path if it already exists. The directory the file is located in must already exist or else the session creation will fail. The contents of the LDAP messages can contain sensitive values so use this only for debugging purposes.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">String</command:parameterValue> <dev:type> <maml:name>String</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>None</dev:defaultValue> </command:parameter> </command:parameters> <command:inputTypes> <command:inputType> <dev:type> <maml:name>None</maml:name> </dev:type> <maml:description> <maml:para></maml:para> </maml:description> </command:inputType> </command:inputTypes> <command:returnValues> <command:returnValue> <dev:type> <maml:name>PSOpenAD.OpenADSessionOptions</maml:name> </dev:type> <maml:description> <maml:para>The `OpenADSessionOptions` instance that stores the session options desired. This can be edited further to change any setting as desired.</maml:para> </maml:description> </command:returnValue> </command:returnValues> <maml:alertSet> <maml:alert> <maml:para>Settings are only used when the session is being created. If the cmdlet is reusing an existing session then these options are ignored and the sessions used when the connection was created will continue to be used.</maml:para> </maml:alert> </maml:alertSet> <command:examples> <command:example> <maml:title>---------- Example 1: Create default session options ----------</maml:title> <dev:code>PS C:\> New-OpenADSessionOption</dev:code> <dev:remarks> <maml:para>Creates the default session options for an `OpenADSession`. These options can be manually edited and then used with a `-SessionOption` parameter.</maml:para> </dev:remarks> </command:example> <command:example> <maml:title>--------- Example 2: Disable certificate verification ---------</maml:title> <dev:code>PS C:\> $so = New-OpenADSessionOption -SkipCertificateCheck PS C:\> Get-OpenADUser -Server dc -StartTLS -SessionOption $so -Identity my-username</dev:code> <dev:remarks> <maml:para>Creates session options that disable any certificate verification checks that are done when using `StartTLS` or connecting over an LDAP endpoint. This should not be used in a production like environment and is designed for use with test environments where self signed certificates may be in place.</maml:para> </dev:remarks> </command:example> <command:example> <maml:title>---------- Example 3: Disable encryption and signing ----------</maml:title> <dev:code>PS C:\> $so = New-OpenADSessionOption -NoEncryption -NoSigning PS C:\> Get-OpenADUser -Server dc -SessionOption $so -Identity my-username</dev:code> <dev:remarks> <maml:para>Disables and encryption or signatures placed on the data exchanged with the LDAP server. Encryption and signing is used by auth mechanisms, like `Negotiate` and `Kerberos` to encrypt or sign the data exchanged on the network.</maml:para> </dev:remarks> </command:example> <command:example> <maml:title>----------- Example 4: Enable message trace logging -----------</maml:title> <dev:code>PS C:\> $so = New-OpenADSessionOption -TracePath temp:/PSOpenAD-Trace.log PS C:\> $s = New-OpenADSession -ComputerName dc -SessionOption $so PS C:\> Get-OpenADUser -Session $s -Identity my-username PS C:\> $s | Remove-OpenADSession</dev:code> <dev:remarks> <maml:para>Creates an OpenAD session with trace message logging set to log the incoming and outgoing LDAP messages to `temp:/PSOpenAD-Trace.log`. The path can be any location accessible by the `FileSystem` provider in PowerShell. The logs will continue to append until the OpenAD session is closed.</maml:para> </dev:remarks> </command:example> <command:example> <maml:title>----- Example 5: Connect using Certificate authentication -----</maml:title> <dev:code>PS C:\> $cert = [System.Security.Cryptography.X509Certificates.X509Certificate]::new('Cert Path.pfx', $certPass) PS C:\> $so = New-OpenADSessionOption -ClientCertificate $cert PS C:\> $s = New-OpenADSession -ComputerName dc -SessionOption $so -UseTLS</dev:code> <dev:remarks> <maml:para>Creates an OpenAD session to an `LDAPS` endpoint and authenticates using the client certificate provided. This certificate needs to be mapped to a user on the server for the authentication to occur.</maml:para> </dev:remarks> </command:example> </command:examples> <command:relatedLinks> <maml:navigationLink> <maml:linkText>Online Version:</maml:linkText> <maml:uri>https://www.github.com/jborean93/PSOpenAD/blob/main/docs/en-US/New-OpenADSessionOption.md</maml:uri> </maml:navigationLink> </command:relatedLinks> </command:command> <command:command xmlns:maml="http://schemas.microsoft.com/maml/2004/10" xmlns:command="http://schemas.microsoft.com/maml/dev/command/2004/10" xmlns:dev="http://schemas.microsoft.com/maml/dev/2004/10" xmlns:MSHelp="http://msdn.microsoft.com/mshelp"> <command:details> <command:name>Remove-OpenADSession</command:name> <command:verb>Remove</command:verb> <command:noun>OpenADSession</command:noun> <maml:description> <maml:para>Disconnects an LDAP/AD session.</maml:para> </maml:description> </command:details> <maml:description> <maml:para>Disconnects an LDAP/AD session and marks the session object as closed.</maml:para> <maml:para>Once closed the sesion is removed from the process wide connection pool.</maml:para> </maml:description> <command:syntax> <command:syntaxItem> <maml:name>Remove-OpenADSession</maml:name> <command:parameter required="true" variableLength="true" globbing="false" pipelineInput="True (ByPropertyName, ByValue)" position="0" aliases="none"> <maml:name>Session</maml:name> <maml:description> <maml:para>The session to disconnect.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">OpenADSession[]</command:parameterValue> <dev:type> <maml:name>OpenADSession[]</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>None</dev:defaultValue> </command:parameter> </command:syntaxItem> </command:syntax> <command:parameters> <command:parameter required="true" variableLength="true" globbing="false" pipelineInput="True (ByPropertyName, ByValue)" position="0" aliases="none"> <maml:name>Session</maml:name> <maml:description> <maml:para>The session to disconnect.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">OpenADSession[]</command:parameterValue> <dev:type> <maml:name>OpenADSession[]</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>None</dev:defaultValue> </command:parameter> </command:parameters> <command:inputTypes> <command:inputType> <dev:type> <maml:name>PSOpenAD.OpenADSession[]</maml:name> </dev:type> <maml:description> <maml:para>The session(s) to disconnect.</maml:para> </maml:description> </command:inputType> </command:inputTypes> <command:returnValues> <command:returnValue> <dev:type> <maml:name>None</maml:name> </dev:type> <maml:description> <maml:para></maml:para> </maml:description> </command:returnValue> </command:returnValues> <maml:alertSet> <maml:alert> <maml:para>Once the session has been closed it will be removed from the pool and cannot be used for any future operations.</maml:para> </maml:alert> </maml:alertSet> <command:examples> <command:example> <maml:title>-------------------------- Example 1 --------------------------</maml:title> <dev:code>PS C:\> $s = New-OpenADSession -ComputerName domain-controller -Authentication Negotiate PS C:\> $s | Remove-OpenADSession</dev:code> <dev:remarks> <maml:para>Creates a session and then disconnects it.</maml:para> </dev:remarks> </command:example> </command:examples> <command:relatedLinks> <maml:navigationLink> <maml:linkText>Online Version:</maml:linkText> <maml:uri>https://www.github.com/jborean93/PSOpenAD/blob/main/docs/en-US/Remove-OpenADSession.md</maml:uri> </maml:navigationLink> </command:relatedLinks> </command:command> </helpItems> |