Megosztás a következőn keresztül:

Hitelesítő adatokkal kapcsolatos támogatás hozzáadása a PowerShell-függvényekhez

  • Cikk

Feljegyzés

A cikk eredeti verziója @joshduffney által írt blogon jelent meg. Ez a cikk a webhelyre való felvételhez lett szerkesztve. A PowerShell csapata köszönjük Joshnak, hogy megosztotta velünk ezt a tartalmat. Kérjük, nézze meg a blogját a duffney.io.

Ez a cikk bemutatja, hogyan adhat hozzá hitelesítő paramétereket a PowerShell-függvényekhez, és hogy miért érdemes. A hitelesítőadat-paraméter lehetővé teszi a függvény vagy parancsmag más felhasználóként való futtatását. A leggyakoribb használat a függvény vagy parancsmag emelt szintű felhasználói fiókként való futtatása.

A parancsmag New-ADUser például rendelkezik hitelesítő paraméterrel, amelyet tartományadminisztrátori hitelesítő adatokkal adhat meg egy tartományfiók létrehozásához. Feltéve, hogy a PowerShell-munkamenetet futtató normál fiókja még nem rendelkezik ilyen hozzáféréssel.

Hitelesítőadat-objektum létrehozása

A PSCredential objektum olyan biztonsági hitelesítő adatok készletét jelöli, mint a felhasználónév és a jelszó. Az objektum paraméterként továbbítható egy olyan függvénynek, amely a hitelesítőadat-objektum felhasználói fiókjaként fut. A hitelesítő adatokat többféleképpen is létrehozhatja. Hitelesítő objektum létrehozásának első módja a PowerShell-parancsmag Get-Credentialhasználata. Ha paraméterek nélkül fut, a rendszer felhasználónevet és jelszót kér. Vagy meghívhatja a parancsmagot néhány választható paraméterrel.

Ha előre meg szeretné adni a tartománynevet és a felhasználónevet, használhatja a Hitelesítő adatok vagy a UserName paramétereket. A UserName paraméter használatakor meg kell adnia egy üzenetértéket is. Az alábbi kód bemutatja a parancsmag használatát. A hitelesítő objektumot egy változóban is tárolhatja, így többször is használhatja a hitelesítő adatokat. Az alábbi példában a hitelesítő objektum a változóban $Credlesz tárolva.

$Cred = Get-Credential
$Cred = Get-Credential -Credential domain\user
$Cred = Get-Credential -UserName domain\user -Message 'Enter Password'

Néha nem használhatja az előző példában bemutatott hitelesítő objektumok létrehozásának interaktív módszerét. A legtöbb automatizálási eszköz nem interaktív módszert igényel. Ha felhasználói beavatkozás nélkül szeretne hitelesítő adatokat létrehozni, hozzon létre egy jelszót tartalmazó biztonságos sztringet. Ezután adja át a biztonságos sztringet és a felhasználónevet a System.Management.Automation.PSCredential() metódusnak.

A következő paranccsal hozzon létre egy jelszót tartalmazó biztonságos sztringet:

ConvertTo-SecureString "MyPlainTextPassword" -AsPlainText -Force

Az AsPlainText és a Force paraméterek egyaránt szükségesek. Ezen paraméterek nélkül egy üzenet figyelmezteti, hogy nem szabad egyszerű szöveget átadni egy biztonságos sztringbe. A PowerShell azért adja vissza ezt a figyelmeztetést, mert az egyszerű szöveges jelszó különböző naplókban lesz rögzítve. Miután létrehozott egy biztonságos sztringet, át kell adnia azt a PSCredential() hitelesítőadat-objektum létrehozásához szükséges metódusnak. Az alábbi példában a változó $password a hitelesítőadat-objektumot tartalmazó biztonságos sztringet $Cred tartalmazza.

$password = ConvertTo-SecureString "MyPlainTextPassword" -AsPlainText -Force
$Cred = New-Object System.Management.Automation.PSCredential ("username", $password)

Most, hogy már tudja, hogyan hozhat létre hitelesítő objektumokat, hitelesítő paramétereket adhat hozzá a PowerShell-függvényekhez.

Hitelesítőadat-paraméter hozzáadása

A többi paraméterhez hasonlóan a függvény blokkjához param is hozzá kell adnia. Javasoljuk, hogy nevezze el a paramétert $Credential , mert a meglévő PowerShell-parancsmagok ezt használják. A paraméter típusának a következőnek kell lennie [System.Management.Automation.PSCredential]: .

Az alábbi példa egy úgynevezett Get-Somethingfüggvény paraméterblokkját mutatja be. Két paramétere van: $Name és $Credential.

function Get-Something {
    param(
        $Name,
        [System.Management.Automation.PSCredential]$Credential
    )

Az ebben a példában szereplő kód elegendő egy működő hitelesítőadat-paraméter használatához, azonban van néhány dolog, amelyet hozzáadhat, hogy robusztusabb legyen.

  • Adja hozzá az [ValidateNotNull()] érvényesítési attribútumot annak ellenőrzéséhez, hogy az érték átadva van-e a Hitelesítő adatoknak. Ha a paraméter értéke null, ez az attribútum megakadályozza, hogy a függvény érvénytelen hitelesítő adatokkal hajtsa végre.

  • Hozzáadás [System.Management.Automation.Credential()]. Ez lehetővé teszi, hogy sztringként adja meg a felhasználónevet, és interaktív kéréssel rendelkezzen a jelszóra.

  • Állítsa be a paraméter alapértelmezett értékét a $Credential következőre [System.Management.Automation.PSCredential]::Empty: . Előfordulhat, hogy a függvény átadja ezt az $Credential objektumot a meglévő PowerShell-parancsmagoknak. Ha null értéket ad a függvényben hívott parancsmagnak, az hibát okoz. Ha üres hitelesítőadat-objektumot ad meg, azzal elkerülheti ezt a hibát.

Tipp.

Egyes hitelesítő adatokat elfogadó parancsmagok nem támogatják [System.Management.Automation.PSCredential]::Empty a kívánt módon. Kerülő megoldásért tekintse meg az Örökölt parancsmagok kezelése szakaszt.

Hitelesítő adatok paramétereinek használata

Az alábbi példa a hitelesítő adatok paramétereinek használatát mutatja be. Ez a példa egy , a Pester Könyvből kifelé lévő függvényt Set-RemoteRegistryValuemutat be. Ez a függvény az előző szakaszban leírt technikák használatával határozza meg a hitelesítőadat-paramétert. A függvény a $Credential függvény által létrehozott változó használatával hívja Invoke-Command meg a hívásokat. Így módosíthatja a futó Invoke-Commandfelhasználót. Mivel az alapértelmezett érték $Credential egy üres hitelesítő adat, a függvény hitelesítő adatok megadása nélkül is futtatható.

function Set-RemoteRegistryValue {
    param(
        $ComputerName,
        $Path,
        $Name,
        $Value,
        [ValidateNotNull()]
        [System.Management.Automation.PSCredential]
        [System.Management.Automation.Credential()]
        $Credential = [System.Management.Automation.PSCredential]::Empty
    )
        $null = Invoke-Command -ComputerName $ComputerName -ScriptBlock {
            Set-ItemProperty -Path $using:Path -Name $using:Name -Value $using:Value
        } -Credential $Credential
}

Az alábbi szakaszok különböző módszereket mutatnak be a hitelesítő adatok megadására Set-RemoteRegistryValue.

Hitelesítő adatok kérése

A zárójelekben () való használat Get-Credential futáskor az első futtatást eredményeziGet-credential. A rendszer felhasználónevet és jelszót kér. A felhasználónév és a tartomány előzetes feltöltéséhez használhatja a Hitelesítő adatok vagy a UserNameGet-credential paramétereket. Az alábbi példa egy splatting nevű technikával adja át a paramétereket a Set-RemoteRegistryValue függvénynek. A splattingről további információt a about_Splatting cikkben talál.

$remoteKeyParams = @{
    ComputerName = $env:COMPUTERNAME
    Path = 'HKLM:\SOFTWARE\Microsoft\WebManagement\Server'
    Name = 'EnableRemoteManagement'
    Value = '1'
}

Set-RemoteRegistryValue @remoteKeyParams -Credential (Get-Credential)

Hitelesítő adatok lekérése futásidőben

Használata (Get-Credential) nehézkesnek tűnik. Általában, ha a Hitelesítő paramétert csak felhasználónévvel használja, a parancsmag automatikusan kéri a jelszót. Az [System.Management.Automation.Credential()] attribútum engedélyezi ezt a viselkedést.

$remoteKeyParams = @{
    ComputerName = $env:COMPUTERNAME
    Path = 'HKLM:\SOFTWARE\Microsoft\WebManagement\Server'
    Name = 'EnableRemoteManagement'
    Value = '1'
}

Set-RemoteRegistryValue @remoteKeyParams -Credential duffney

Hitelesítő adatok kérése

Feljegyzés

A megjelenő beállításjegyzék-érték beállításához ezek a példák feltételezik, hogy telepítve vannak a Windows webkiszolgálói funkciói. Futtassa Install-WindowsFeature Web-Server , és Install-WindowsFeature web-mgmt-tools ha szükséges.

Hitelesítő adatok megadása változóban

A hitelesítő változót előre is feltöltheti, és átadhatja a függvény hitelesítő paraméterénekSet-RemoteRegistryValue. Ezt a módszert a folyamatos integrációs/ folyamatos üzembe helyezési (CI/CD) eszközökkel, például a Jenkins, a TeamCity és az Octopus Deploy használatával használhatja. Ha például Jenkinst használ, tekintse meg Hodge blogbejegyzését , amely a Jenkins és a PowerShell automatizálása Windows rendszeren – 2. rész.

Ez a példa a .NET metódussal hozza létre a hitelesítő objektumot, és egy biztonságos sztringet a jelszó átadásához.

$password = ConvertTo-SecureString "P@ssw0rd" -AsPlainText -Force
$Cred = New-Object System.Management.Automation.PSCredential ("duffney", $password)

$remoteKeyParams = @{
    ComputerName = $env:COMPUTERNAME
    Path = 'HKLM:\SOFTWARE\Microsoft\WebManagement\Server'
    Name = 'EnableRemoteManagement'
    Value = '1'
}

Set-RemoteRegistryValue @remoteKeyParams -Credential $Cred

Ebben a példában a biztonságos sztring tiszta szöveges jelszóval jön létre. Az összes korábban említett CI/CD rendelkezik egy biztonságos módszerrel a jelszó futásidőben történő megadására. Ezen eszközök használatakor cserélje le az egyszerű szöveges jelszót a használt CI/CD-eszközben definiált változóra.

Futtatás hitelesítő adatok nélkül

Mivel $Credential az alapértelmezett érték egy üres hitelesítőadat-objektum, hitelesítő adatok nélkül is futtathatja a parancsot, ahogyan az ebben a példában látható:

$remoteKeyParams = @{
    ComputerName = $env:COMPUTERNAME
    Path = 'HKLM:\SOFTWARE\Microsoft\WebManagement\Server'
    Name = 'EnableRemoteManagement'
    Value = '1'
}

Set-RemoteRegistryValue @remoteKeyParams

Régi parancsmagok kezelése

Nem minden parancsmag támogatja a hitelesítő objektumokat, vagy nem engedélyezi az üres hitelesítő adatokat. Ehelyett a parancsmag sztringként szeretné megadni a felhasználónevet és a jelszót. Ezt a korlátozást többféleképpen is megkerülheti.

Az if-else használata üres hitelesítő adatok kezeléséhez

Ebben a forgatókönyvben a futtatni kívánt parancsmag nem fogad el üres hitelesítő objektumot. Ez a példa csak akkor adja hozzá a hitelesítőadat-paramétertInvoke-Command, ha az nem üres. Ellenkező esetben a Invoke-Command hitelesítő adat paraméter nélkül futtatja .

function Set-RemoteRegistryValue {
    param(
        $ComputerName,
        $Path,
        $Name,
        $Value,
        [ValidateNotNull()]
        [System.Management.Automation.PSCredential]
        [System.Management.Automation.Credential()]
        $Credential = [System.Management.Automation.PSCredential]::Empty
    )

    if($Credential -ne [System.Management.Automation.PSCredential]::Empty) {
        Invoke-Command -ComputerName:$ComputerName -Credential:$Credential  {
            Set-ItemProperty -Path $using:Path -Name $using:Name -Value $using:Value
        }
    } else {
        Invoke-Command -ComputerName:$ComputerName {
            Set-ItemProperty -Path $using:Path -Name $using:Name -Value $using:Value
        }
    }
}

Üres hitelesítő adatok kezelése splatting használatával

Ez a példa paraméterplatform használatával hívja meg az örökölt parancsmagot. A $Credential rendszer feltételesen hozzáadja az objektumot a kivonatoló táblához a platformhoz, és nem szükséges megismételni a Invoke-Command szkriptblokkot. Ha többet szeretne megtudni a függvényeken belüli splattingról, tekintse meg a Splatting Parameters Inside Advanced Functions blogbejegyzést.

function Set-RemoteRegistryValue {
    param(
        $ComputerName,
        $Path,
        $Name,
        $Value,
        [ValidateNotNull()]
        [System.Management.Automation.PSCredential]
        [System.Management.Automation.Credential()]
        $Credential = [System.Management.Automation.PSCredential]::Empty
    )

        $Splat = @{
            ComputerName = $ComputerName
        }

        if ($Credential -ne [System.Management.Automation.PSCredential]::Empty) {
            $Splat['Credential'] = $Credential
        }

        $null = Invoke-Command -ScriptBlock {
            Set-ItemProperty -Path $using:Path -Name $using:Name -Value $using:Value
        } @splat
}

Sztringjelszavak használata

A Invoke-Sqlcmd parancsmag egy példa egy olyan parancsmagra, amely egy sztringet fogad el jelszóként. Invoke-Sqlcmd lehetővé teszi egyszerű SQL-beszúrási, frissítési és törlési utasítások futtatását. Invoke-Sqlcmd a biztonságosabb hitelesítőadat-objektum helyett egyértelmű szöveges felhasználónévre és jelszóra van szükség. Ez a példa bemutatja, hogyan nyerheti ki a felhasználónevet és a jelszót egy hitelesítő objektumból.

A Get-AllSQLDatabases példában szereplő függvény meghívja a Invoke-Sqlcmd parancsmagot egy SQL-kiszolgáló lekérdezésére az összes adatbázisához. A függvény egy hitelesítő paramétert határoz meg ugyanazzal az attribútummal, amelyet az előző példákban használt. Mivel a felhasználónév és a jelszó megtalálható a $Credential változóban, ezeket az értékeket kinyerheti a használatával Invoke-Sqlcmd.

A felhasználónév a változó UserName tulajdonságából $Credential érhető el. A jelszó beszerzéséhez az GetNetworkCredential() objektum metódusát kell használnia $Credential . Az értékek olyan változókba lesznek kinyerve, amelyek hozzáadódnak egy kivonattáblához, amelybe a splatting paramétereket használják Invoke-Sqlcmd.

function Get-AllSQLDatabases {
    param(
        $SQLServer,
        [ValidateNotNull()]
        [System.Management.Automation.PSCredential]
        [System.Management.Automation.Credential()]
        $Credential = [System.Management.Automation.PSCredential]::Empty
    )

        $UserName = $Credential.UserName
        $Password = $Credential.GetNetworkCredential().Password

        $splat = @{
            UserName = $UserName
            Password = $Password
            ServerInstance = 'SQLServer'
            Query = "Select * from Sys.Databases"
        }

        Invoke-Sqlcmd @splat
}

$credSplat = @{
    TypeName = 'System.Management.Automation.PSCredential'
    ArgumentList = 'duffney',('P@ssw0rd' | ConvertTo-SecureString -AsPlainText -Force)
}
$Credential = New-Object @credSplat

Get-AllSQLDatabases -SQLServer SQL01 -Credential $Credential

A tanulás hitelesítő adatainak folyamatos kezelése

A hitelesítő adatok biztonságos létrehozása és tárolása nehéz lehet. Az alábbi erőforrások segíthetnek a PowerShell-hitelesítő adatok karbantartásában.