El Blog de Gualtrysoft

Windows 2000/2003/2008, Active Directory, VBScript, Hyper-V, PowerShell y todo aquello interesante a la hora de usar, configurar y administrar Windows Server. También tenemos longanizas…

PowerShell: Cmdlet Para Realizar Búsquedas en Active Directory y Obtener los Resultados Como Objetos DirectoryEntry

Posted by urpiano en Domingo 21 \21\UTC octubre \21\UTC 2012

Cuando se utiliza un objeto DirectorySearcher para realizar búsquedas por medio de filtros LDAP, los resultados obtenidos son objetos SearchResult, más incómodos de consultar que los objetos DirectoryEntry. Este Cmdlet en un encapsulamiento del objeto DirectorySearcher que permite usar el mismo filtro LDAP que se usaría con el DirectorySearcher y obtener los mismos resultados, pero como objetos DirectoryEntry.

El Cmdlet permite establecer el contenedor raíz de la búsqueda, si será o no recursiva, el controlador de dominio con el que se contactará y el usuario y contraseña utilizados para acceder a Active Directory.

El Cmdlet incluye ayuda, pego a continuación la ayuda con modificador -Detailed (esta ayuda se basa en la prestación de ayuda basada en comentarios de PowerShell 2.0 ¿Qué todavía tienes la versión 1.0 y no la 2.0? ¿A qué esperas para instalarla si es mucho mejor?):

NOMBRE
    Get-LDAPSearch
    
SINOPSIS
    Esta función ejecuta una consulta LDAP y devuelve los objetos
    DirectoryEntry encontrados.
    
    
SINTAXIS
    Get-LDAPSearch [[-StartContainer] ] [[-DomainController] ] [[-UserName] ] [[-Password] 
    ] [[-Filter] ] [[-SearchScope] ] []
    
    
DESCRIPCIÓN
    Esta función ejecuta una consulta LDAP y devuelve los objetos 
    encontrados no como DirectorySearchResult si no como DirectoryEntry. Permite
    especificar el contenedor en el que buscar, el controlador de dominio al que se
    conectará, el usuario y la contraseña con la que se conectará y si se búscará
    únicamente en el contenedor o la búsqueda será recursiva (todo el árbol de
    contenedores cuya raíz sea la especificada como contenedor).
    

PARÁMETROS
    -StartContainer 
        Nombre distinguido del contenedor raíz de la búsqueda. Si se omite, la
        función averiguará el nombre distinguido del dominio al que pertenece el equipo
        desde el que se lanza la función y será éste el contenedor raíz de la búsqueda.
        Este parámetro admite, además, el alias C.
        
    -DomainController 
        Nombre FQDN del controlador de dominio que se usará para conectar al
        dominio. Si se omite y no es omitido el parámetro Domain, la ruta LDAP que se
        monte para conectar al dominio no establecerá controlador al que conectar, lo
        que hará que se conecte al catálogo global que el equipo considere el más
        cercano; si también es omitido el parámetro Domain, el sevidor especificado será
        el que ostente el rol de PDE Emulator en el dominio al que pertenezca el equipo
        desde el que se lanza la función. Este parámetro admite, además, el alias DC.
        
    -UserName 
        Usuario con el que se producirá la validación al conectar al dominio;
        en caso de no establecerse, la conexión se realizará validando con el usuario
        que lanza la función. Este parámetro admite, además, el alias U.
        
    -Password 
        Contraseña del usuario con el que se producirá la validación al conectar
        al dominio; en caso de no pasarse el parámetro UserName, la conexión se
        realizará validando con el usuario que lanza la función y si Password fuese
        pasado se ignorará este parámetro. Este parámetro admite, además, el alias P.
        
    -Filter 
        Esta es la consulta LDAP que se realizará. Sigue la nomenclatura de una
        consulta LDAP:
        (http://msdn.microsoft.com/en-us/library/windows/desktop/aa746475(v=vs.85).aspx)
        Este parámetro admite, además, el alias F.
        
    -SearchScope 
        Este parámetro permite especificar el ámbito de búsqueda. Admite dos
        valores:
        - SubTree  : la búsqueda se realiza en todo el árbol cuya raíz tiene como
                 nombre distinguido el especificado por el parámetro
                 StartContainer.
        - OneLevel : La búsqueda se realizará sólo en el contenedor cuyo nombre
                 distinguido es el especificado en el parámetro StartContainer.
        
        Si se omite este parámetro, el valor que se utilizará será SubTree. Este
        parámetro admite, además, el alias S.
        
    
        Este cmdlet admite los parámetros comunes Verbose, Debug,
        ErrorAction, ErrorVariable, WarningAction, WarningVariable,
        OutBuffer y OutVariable. Para obtener más información, escriba:
        "get-help about_commonparameters".
    
    -------------------------- EJEMPLO 1 --------------------------
    
    PS C:\>Get-LDAPSearch -Filter "(objectClass=computer)"
    
    La función devuelve los objetos DirectoryEntry correspondientes a las cuentas de
    los equipos del dominio desde el que se lanza el script.
    
    
    
    
    -------------------------- EJEMPLO 2 --------------------------
    
    PS C:\>$Filtro = "(&(objectClass=user)(objectCategory=person)"
    
    PS C:\> Get-LDAPSearch -F $Filtro
    
    La función devuelve los objetos DirectoryEntry correspondientes a las cuentas de
    los usuarios y contactos del dominio desde el que se lanza el script.
    
    
    
    
    -------------------------- EJEMPLO 3 --------------------------
    
    PS C:\>$Raiz = ""OU=Agentes,DC=tia,DC=org"
    
    PS C:\> $DC = "bacterio-dc.tia.org"
    PS C:\> $Filtro = "(&(objectClass=user)(objectCategory=person)"
    PS C:\> Get-LDAPSearch -F $Filtro -C $Raiz -DomainController $DC
    
    La función devuelve los objetos DirectoryEntry correspondientes a las cuentas de
    los usuarios y contactos que estén en el subárbol cuya raíz es la OU Agentes del
    dominio tia.org, conectando al controlador de dominio bacterio-dc.tia.org.
    
    
    
    
    -------------------------- EJEMPLO 4 --------------------------
    
    PS C:\>$Raiz = ""OU=Agentes,DC=tia,DC=org"
    
    PS C:\> $DC = "bacterio-dc.tia.org"
    PS C:\> $Filtro = "(&(objectClass=user)(objectCategory=person)"
    PS C:\> Get-LDAPSearch -F $Filtro -C $Raiz -DomainController $DC -S "OneLevel"
    
    La función devuelve los objetos DirectoryEntry correspondientes a las cuentas de
    los usuarios y contactos que estén en la OU Agentes del dominio tia.org,
    conectando al controlador de dominio bacterio-dc.tia.org.
    
    
    
    
    -------------------------- EJEMPLO 5 --------------------------
    
    PS C:\>$Dominio = "DC=tia,DC=org"
    
    PS C:\> $DC = "bacterio-dc.tia.org"
    PS C:\> $Usuario = "bacterio"
    PS C:\> $Clave = "OfeliaFOCA"
    PS C:\> $Filtro = "(&(objectClass=user)(objectCategory=person)"
    PS C:\> Get-LDAPSearch -F $Filtro -C $Dominio -DC $DC -U $Usuario -P $Clave
    
    La función devuelve los objetos DirectoryEntry correspondientes a las cuentas de
    los usuarios y contactos del dominio tia.org conectando al controlador de
    dominio bacterio-dc.tia.org usando para validarse la cuenta "bacterio" con la
    contraseña "OfeliaFOCA".
    
    
    
    
NOTAS
    Para ver los ejemplos, escriba: "get-help Get-LDAPSearch -examples".
    Para obtener más información, escriba: "get-help Get-LDAPSearch -detailed".
    Para obtener información técnica, escriba: "get-help Get-LDAPSearch -full".

Este es el código del Cmdlet:

Function Get-LDAPSearch([Alias("C")][String] $StartContainer,
                        [Alias("DC")][String]$DomainController,
                        [Alias("U")][String] $UserName,
                        [Alias("P")][String] $Password,
                        [Alias("F")][String] $Filter,
                        [Alias("S")]
                        [ValidateSet("Subtree","OneLevel")]
                        [String]             $SearchScope = "Subtree")
{
    # Revisamos si se ha recibido dominio, en caso negativo lo obtendremos
    If([System.String]::IsNullOrEmpty($StartContainer))
    {
        # Obtenemos el dominio gracias al método GetCurrentDomain del objeto
        # Domain
        $Dominio = `
           [System.DirectoryServices.ActiveDirectory.Domain]::GetCurrentDomain()
        # Montamos la ruta LDAP del dominio conectando al PDC Emulator
        $Ruta = "LDAP://$($Dominio.PdcRoleOwner)"
        $Ruta = "$Ruta/DC=$($Dominio.Name -replace "\.",",DC=")"
    }
    # Se ha recibido domino pero no servidor
    ElseIf([System.String]::IsNullOrEmpty($DomainController))
    {
        # Montamos la ruta LDAP que usa el catálogo global más cercano
        $Ruta = "LDAP://$StartContainer"
    }
    # Se ha recibido tanto nombre de dominio como servidor; montamos la ruta
    # LDAP con esos datos
    Else
    {
        $Ruta = "LDAP://$DomainController/$StartContainer"
    }
    # Debemos ver si se han recibido credenciales de usuario; en caso contrario
    # obtendremos el objeto DirectoryEntry sin pasar credenciales
    If([System.String]::IsNullOrEmpty($UserName) -eq $true)
    {
        $Dominio = New-Object System.DirectoryServices.DirectoryEntry $Ruta
    }
    # Obtenemos el objeto DirectoryEntry del dominio, pasando las credenciales
    # y estableciendo el sevidor LDAP en el que se consulta, ya que se han
    # pasado credenciales de usuario
    Else
    {
        $Dominio = New-Object System.DirectoryServices.DirectoryEntry `
                                 $Ruta,$UserName,$Password
    }
    # Creamos un objeto DirectorySearcher, contectado al dominio, con el que
    # realizaremos las búsquedas
    $Buscador = [System.DirectoryServices.DirectorySearcher]$Dominio

    # Establecemos el filtro en el objeto DirectorySearcher
    $Buscador.Filter = $Filter

    # Establecemos el ámbito de búsqueda
    $Buscador.SearchScope = $SearchScope

    # Establecemos paginación para que así no se limiten los resultados
    # obtenidos
    $Buscador.PageSize = 100

    # La función devuelve los objetos DirectoryEntry correspondientes a los
    # objetos devueltos por el objeto buscador
    $Buscador.FindAll() | ForEach{$_.GetDirectoryEntry()}

<#
    .SYNOPSIS
        Esta función ejecuta una consulta LDAP y devuelve los objetos
DirectoryEntry encontrados.

    .DESCRIPTION
        Esta función ejecuta una consulta LDAP y devuelve los objetos 
encontrados no como DirectorySearchResult si no como DirectoryEntry. Permite
especificar el contenedor en el que buscar, el controlador de dominio al que se
conectará, el usuario y la contraseña con la que se conectará y si se búscará
únicamente en el contenedor o la búsqueda será recursiva (todo el árbol de
contenedores cuya raíz sea la especificada como contenedor).

    .PARAMETER  Filter
        Esta es la consulta LDAP que se realizará. Sigue la nomenclatura de una
consulta LDAP:
(http://msdn.microsoft.com/en-us/library/windows/desktop/aa746475(v=vs.85).aspx)
Este parámetro admite, además, el alias F.

    .PARAMETER  StartContainer
        Nombre distinguido del contenedor raíz de la búsqueda. Si se omite, la
función averiguará el nombre distinguido del dominio al que pertenece el equipo
desde el que se lanza la función y será éste el contenedor raíz de la búsqueda.
Este parámetro admite, además, el alias C.

    .PARAMETER  DomainController
        Nombre FQDN del controlador de dominio que se usará para conectar al
dominio. Si se omite y no es omitido el parámetro Domain, la ruta LDAP que se
monte para conectar al dominio no establecerá controlador al que conectar, lo
que hará que se conecte al catálogo global que el equipo considere el más
cercano; si también es omitido el parámetro Domain, el sevidor especificado será
el que ostente el rol de PDE Emulator en el dominio al que pertenezca el equipo
desde el que se lanza la función. Este parámetro admite, además, el alias DC.

    .PARAMETER  UserName
        Usuario con el que se producirá la validación al conectar al dominio;
en caso de no establecerse, la conexión se realizará validando con el usuario
que lanza la función. Este parámetro admite, además, el alias U.

    .PARAMETER  Password
        Contraseña del usuario con el que se producirá la validación al conectar
al dominio; en caso de no pasarse el parámetro UserName, la conexión se
realizará validando con el usuario que lanza la función y si Password fuese
pasado se ignorará este parámetro. Este parámetro admite, además, el alias P.

    .PARAMETER  SearchScope
        Este parámetro permite especificar el ámbito de búsqueda. Admite dos
valores:
    - SubTree  : la búsqueda se realiza en todo el árbol cuya raíz tiene como
                 nombre distinguido el especificado por el parámetro
                 StartContainer.
    - OneLevel : La búsqueda se realizará sólo en el contenedor cuyo nombre
                 distinguido es el especificado en el parámetro StartContainer.
     
    Si se omite este parámetro, el valor que se utilizará será SubTree. Este
parámetro admite, además, el alias S.

    .EXAMPLE
        PS C:\> Get-LDAPSearch -Filter "(objectClass=computer)"
La función devuelve los objetos DirectoryEntry correspondientes a las cuentas de
los equipos del dominio desde el que se lanza el script.

    .EXAMPLE
        PS C:\> $Filtro = "(&(objectClass=user)(objectCategory=person)"
        PS C:\> Get-LDAPSearch -F $Filtro
        
La función devuelve los objetos DirectoryEntry correspondientes a las cuentas de
los usuarios y contactos del dominio desde el que se lanza el script.

    .EXAMPLE
        PS C:\> $Raiz = ""OU=Agentes,DC=tia,DC=org"
        PS C:\> $DC = "bacterio-dc.tia.org"
        PS C:\> $Filtro = "(&(objectClass=user)(objectCategory=person)"
        PS C:\> Get-LDAPSearch -F $Filtro -C $Raiz -DomainController $DC
        
La función devuelve los objetos DirectoryEntry correspondientes a las cuentas de
los usuarios y contactos que estén en el subárbol cuya raíz es la OU Agentes del
dominio tia.org, conectando al controlador de dominio bacterio-dc.tia.org.

    .EXAMPLE
        PS C:\> $Raiz = ""OU=Agentes,DC=tia,DC=org"
        PS C:\> $DC = "bacterio-dc.tia.org"
        PS C:\> $Filtro = "(&(objectClass=user)(objectCategory=person)"
        PS C:\> Get-LDAPSearch -F $Filtro -C $Raiz -DomainController $DC -S "OneLevel"
        
La función devuelve los objetos DirectoryEntry correspondientes a las cuentas de
los usuarios y contactos que estén en la OU Agentes del dominio tia.org,
conectando al controlador de dominio bacterio-dc.tia.org.

    .EXAMPLE
        PS C:\> $Dominio = "DC=tia,DC=org"
        PS C:\> $DC = "bacterio-dc.tia.org"
        PS C:\> $Usuario = "bacterio"
        PS C:\> $Clave = "OfeliaFOCA"
        PS C:\> $Filtro = "(&(objectClass=user)(objectCategory=person)"
        PS C:\> Get-LDAPSearch -F $Filtro -C $Dominio -DC $DC -U $Usuario -P $Clave
        
La función devuelve los objetos DirectoryEntry correspondientes a las cuentas de
los usuarios y contactos del dominio tia.org conectando al controlador de
dominio bacterio-dc.tia.org usando para validarse la cuenta "bacterio" con la
contraseña "OfeliaFOCA".

    .INPUTS
        System.String,System.String,System.String,System.String,System.String

    .OUTPUTS
        System.DirectoryServices.DirectoryEntry[]

    .NOTES
        Fernando Reyes López © 2012

    .LINK
        http://freyes.svetlian.com

    .LINK
        https://urpiano.wordpress.com

#>
}

2 comentarios to “PowerShell: Cmdlet Para Realizar Búsquedas en Active Directory y Obtener los Resultados Como Objetos DirectoryEntry”

  1. […] PowerShell: Cmdlet Para Realizar Búsquedas en Active Directory y Obtener los Resultados Como Objeto… […]

  2. I read this post completely abut the difference oof most up-to-date and preceding technologies, it’s
    amazing article.

Responder

Introduce tus datos o haz clic en un icono para iniciar sesión:

Logo de WordPress.com

Estás comentando usando tu cuenta de WordPress.com. Cerrar sesión / Cambiar )

Imagen de Twitter

Estás comentando usando tu cuenta de Twitter. Cerrar sesión / Cambiar )

Foto de Facebook

Estás comentando usando tu cuenta de Facebook. Cerrar sesión / Cambiar )

Google+ photo

Estás comentando usando tu cuenta de Google+. Cerrar sesión / Cambiar )

Conectando a %s

 
A %d blogueros les gusta esto: