Hinzufügen von Unterstützung für Anmeldeinformationen zu PowerShell-Funktionen

Hinweis

Die originale Version dieses Artikels erschien auf dem Blog, der von @joshduffney geschrieben wurde. Dieser Artikel wurde zur Aufnahme auf dieser Website bearbeitet. Das PowerShell-Team dankt Josh für das Teilen dieser Inhalte mit uns. Bitte schauen Sie sich seinen Blog bei duffney.io an.

In diesem Artikel wird erläutert, wie Sie PowerShell-Funktionen Anmeldeinformationsparameter hinzufügen und warum Sie möchten. Mit einem Anmeldeinformationsparameter können Sie die Funktion oder das Cmdlet als anderen Benutzer ausführen. Die häufigste Verwendung besteht darin, die Funktion oder das Cmdlet als Benutzerkonto mit erhöhten Rechten auszuführen.

Das Cmdlet New-ADUser verfügt beispielsweise über einen Parameter für Anmeldeinformationen, mit dem Sie Domänenadministratoranmeldeinformationen zum Erstellen eines Kontos in einer Domäne bereitstellen können. Wenn Ihr normales Konto, das die PowerShell-Sitzung ausführt, noch nicht über diesen Zugriff verfügt.

Erstellen eines Anmeldeinformationsobjekts

Das PSCredential -Objekt stellt eine Reihe von Sicherheitsanmeldeinformationen wie einen Benutzernamen und ein Kennwort dar. Das Objekt kann als Parameter an eine Funktion übergeben werden, die als Benutzerkonto in diesem Anmeldeinformationsobjekt ausgeführt wird. Es gibt einige Möglichkeiten, wie Sie ein Anmeldeinformationsobjekt erstellen können. Die erste Möglichkeit zum Erstellen eines Anmeldeinformationsobjekts besteht darin, das PowerShell-Cmdlet Get-Credentialzu verwenden. Wenn Sie ohne Parameter ausgeführt werden, werden Sie aufgefordert, einen Benutzernamen und ein Kennwort einzugeben. Sie können das Cmdlet auch mit einigen optionalen Parametern aufrufen.

Wenn Sie den Domänennamen und den Benutzernamen vorab angeben möchten, können Sie entweder die Parameter "Anmeldeinformationen " oder " Benutzername " verwenden. Wenn Sie den Parameter "UserName " verwenden, müssen Sie auch einen Nachrichtenwert angeben. Der folgende Code veranschaulicht die Verwendung des Cmdlets. Sie können das Anmeldeinformationsobjekt auch in einer Variablen speichern, sodass Sie die Anmeldeinformationen mehrmals verwenden können. Im folgenden Beispiel wird das Anmeldeinformationsobjekt in der Variablen $Credgespeichert.

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

Manchmal können Sie die interaktive Methode zum Erstellen von Anmeldeinformationsobjekten, die im vorherigen Beispiel gezeigt werden, nicht verwenden. Die meisten Automatisierungstools erfordern eine nicht interaktive Methode. Um eine Anmeldeinformation ohne Benutzerinteraktion zu erstellen, erstellen Sie eine sichere Zeichenfolge, die das Kennwort enthält. Übergeben Sie dann die sichere Zeichenfolge und den Benutzernamen an die System.Management.Automation.PSCredential() Methode.

Verwenden Sie den folgenden Befehl, um eine sichere Zeichenfolge mit dem Kennwort zu erstellen:

ConvertTo-SecureString "MyPlainTextPassword" -AsPlainText -Force

Sowohl die Parameter "AsPlainText " als auch " Force " sind erforderlich. Ohne diese Parameter erhalten Sie eine Meldungswarnung, dass Sie nur Text nicht an eine sichere Zeichenfolge übergeben sollten. PowerShell gibt diese Warnung zurück, da das Nur-Text-Kennwort in verschiedenen Protokollen aufgezeichnet wird. Nachdem Sie eine sichere Zeichenfolge erstellt haben, müssen Sie sie an die PSCredential() Methode übergeben, um das Anmeldeinformationsobjekt zu erstellen. Im folgenden Beispiel enthält die Variable $password die sichere Zeichenfolge $Cred das Anmeldeinformationsobjekt.

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

Nachdem Sie nun wissen, wie Sie Anmeldeinformationsobjekte erstellen, können Sie Ihren PowerShell-Funktionen Anmeldeinformationsparameter hinzufügen.

Hinzufügen eines Anmeldeinformationsparameters

Genau wie jeder andere Parameter beginnen Sie, indem Sie ihn im param Block Ihrer Funktion hinzufügen. Es wird empfohlen, den Parameter $Credential zu benennen, da die vorhandenen PowerShell-Cmdlets verwendet werden. Der Typ des Parameters sollte sein [System.Management.Automation.PSCredential].

Das folgende Beispiel zeigt den Parameterblock für eine Funktion, die aufgerufen wird Get-Something. Es hat zwei Parameter: $Name und $Credential.

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

Der Code in diesem Beispiel reicht aus, um über einen funktionierenden Anmeldeinformationsparameter zu verfügen. Es gibt jedoch einige Dinge, die Sie hinzufügen können, um sie robuster zu machen.

  • Fügen Sie das [ValidateNotNull()] Überprüfungsattribut hinzu, um zu überprüfen, ob der Wert an Anmeldeinformationen übergeben wird. Wenn der Parameterwert null ist, verhindert dieses Attribut, dass die Funktion mit ungültigen Anmeldeinformationen ausgeführt wird.

  • Fügen Sie [System.Management.Automation.Credential()]hinzu. Auf diese Weise können Sie einen Benutzernamen als Zeichenfolge übergeben und eine interaktive Eingabeaufforderung für das Kennwort erhalten.

  • Legen Sie einen Standardwert für den $Credential Parameter auf [System.Management.Automation.PSCredential]::Empty. Ihre Funktion, die Sie möglicherweise an $Credential vorhandene PowerShell-Cmdlets übergeben. Das Bereitstellen eines NULL-Werts für das cmdlet, das in Ihrer Funktion aufgerufen wird, verursacht einen Fehler. Wenn Sie ein leeres Anmeldeinformationsobjekt angeben, wird dieser Fehler vermieden.

Tipp

Einige Cmdlets, die einen Anmeldeinformationsparameter akzeptieren, unterstützen [System.Management.Automation.PSCredential]::Empty nicht wie sie sollten. Eine Problemumgehung finden Sie im Abschnitt "Umgang mit Legacy-Cmdlets ".

Verwenden von Anmeldeinformationsparametern

Im folgenden Beispiel wird die Verwendung von Anmeldeinformationsparametern veranschaulicht. Dieses Beispiel zeigt eine Funktion namens Set-RemoteRegistryValue. Diese Funktion definiert den Anmeldeinformationsparameter mithilfe der im vorherigen Abschnitt beschriebenen Techniken. Die Funktion ruft die $Credential von der Funktion erstellte Variable aufInvoke-Command. Auf diese Weise können Sie den Benutzer ändern, der ausgeführt wird Invoke-Command. Da der Standardwert $Credential eine leere Anmeldeinformation ist, kann die Funktion ohne Angabe von Anmeldeinformationen ausgeführt werden.

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
}

In den folgenden Abschnitten werden verschiedene Methoden zum Bereitstellen von Anmeldeinformationen für Set-RemoteRegistryValue.

Aufforderung zur Eingabe von Anmeldeinformationen

Die Verwendung Get-Credential in Klammern () zur Laufzeit bewirkt, dass die Get-Credential Ausführung zuerst erfolgt. Sie werden aufgefordert, einen Benutzernamen und ein Kennwort einzugeben. Sie können die Parameter "Anmeldeinformationen" oder "Get-CredentialBenutzername" verwenden, um den Benutzernamen und die Domäne vorab aufzufüllen. Im folgenden Beispiel wird eine Technik namens Splatting verwendet, um Parameter an die Set-RemoteRegistryValue Funktion zu übergeben. Weitere Informationen zum Splatting finden Sie im artikel about_Splatting .

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

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

Abrufen von Anmeldeinformationen zur Laufzeit

Die Verwendung (Get-Credential) scheint umständlich. Wenn Sie normalerweise den Parameter "Credential " nur mit einem Benutzernamen verwenden, fordert das Cmdlet automatisch das Kennwort ein. Das [System.Management.Automation.Credential()] Attribut aktiviert dieses Verhalten.

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

Set-RemoteRegistryValue @remoteKeyParams -Credential duffney

Aufforderung zur Eingabe von Anmeldeinformationen

Hinweis

Um den angezeigten Registrierungswert festzulegen, gehen diese Beispiele davon aus, dass die Webserverfeatures von Windows installiert sind. Führen Sie die Ausführung Install-WindowsFeature Web-Server aus, und Install-WindowsFeature web-mgmt-tools falls erforderlich.

Bereitstellen von Anmeldeinformationen in einer Variablen

Sie können auch eine Anmeldeinformationsvariable vorab auffüllen und an den Credential-Parameter der Set-RemoteRegistryValue Funktion übergeben. Verwenden Sie diese Methode mit kontinuierlichen Integrations- und Fortlaufenden Bereitstellungstools (CI/CD), z. B. Jenkins, TeamCity und Octopus Deploy. Ein Beispiel für die Verwendung von Jenkins finden Sie im Blogbeitrag Automating von Hodge mit Jenkins und PowerShell auf Windows - Teil 2.

In diesem Beispiel wird die .NET-Methode verwendet, um das Anmeldeinformationsobjekt und eine sichere Zeichenfolge zum Übergeben des Kennworts zu erstellen.

$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

In diesem Beispiel wird die sichere Zeichenfolge mit einem Klartextkennwort erstellt. Alle zuvor erwähnten CI/CD verfügen über eine sichere Methode zur Bereitstellung dieses Kennworts zur Laufzeit. Ersetzen Sie bei Verwendung dieser Tools das Nur-Text-Kennwort durch die variable, die im verwendeten CI/CD-Tool definiert ist.

Ohne Anmeldeinformationen ausführen

Da $Credential standardmäßig ein leeres Anmeldeinformationsobjekt verwendet wird, können Sie den Befehl ohne Anmeldeinformationen ausführen, wie in diesem Beispiel gezeigt:

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

Set-RemoteRegistryValue @remoteKeyParams

Umgang mit Legacy-Cmdlets

Nicht alle Cmdlets unterstützen Anmeldeinformationsobjekte oder zulassen leere Anmeldeinformationen. Stattdessen möchte das Cmdlet Benutzernamen- und Kennwortparameter als Zeichenfolgen. Es gibt einige Möglichkeiten, diese Einschränkung zu umgehen.

Verwenden von if-else zum Behandeln leerer Anmeldeinformationen

In diesem Szenario akzeptiert das auszuführende Cmdlet kein leeres Anmeldeinformationsobjekt. In diesem Beispiel wird der Parameter "Credential " nur hinzugefügt Invoke-Command , wenn er nicht leer ist. Andernfalls wird der Invoke-Command Parameter "Credential" ohne den Parameter "Credential " ausgeführt.

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
        }
    }
}

Verwenden von Splatting zum Behandeln leerer Anmeldeinformationen

In diesem Beispiel wird die Parametersplatting verwendet, um das Legacy-Cmdlet aufzurufen. Das $Credential Objekt wird der Hashtabelle zur Splatting bedingt hinzugefügt und verhindert, dass der Invoke-Command Skriptblock wiederholt werden muss. Weitere Informationen zum Splatting innerhalb von Funktionen finden Sie im Blogbeitrag " Splatting Parameters Inside Advanced Functions ".

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
}

Arbeiten mit Zeichenfolgen-Kennwörtern

Das Invoke-Sqlcmd Cmdlet ist ein Beispiel für ein Cmdlet, das eine Zeichenfolge als Kennwort akzeptiert. Invoke-Sqlcmd ermöglicht ihnen das Ausführen einfacher SQL-Einfüge-, Aktualisierungs- und Löschanweisungen. Invoke-Sqlcmd erfordert einen Klartextbenutzernamen und ein Kennwort anstelle eines sichereren Anmeldeinformationsobjekts. In diesem Beispiel wird gezeigt, wie Sie den Benutzernamen und das Kennwort aus einem Anmeldeinformationsobjekt extrahieren.

Die Get-AllSQLDatabases Funktion in diesem Beispiel ruft das Invoke-Sqlcmd Cmdlet auf, um einen SQL-Server für alle zugehörigen Datenbanken abzufragen. Die Funktion definiert einen Credential-Parameter mit demselben Attribut, das in den vorherigen Beispielen verwendet wird. Da der Benutzername und das Kennwort in der $Credential Variablen vorhanden sind, können Sie diese Werte für die Verwendung mit Invoke-Sqlcmdextrahieren.

Der Benutzername ist über die UserName-Eigenschaft der $Credential Variablen verfügbar. Um das Kennwort abzurufen, müssen Sie die GetNetworkCredential() Methode des $Credential Objekts verwenden. Die Werte werden in Variablen extrahiert, die einer Hashtabelle hinzugefügt werden, die zum Splatting von Parametern Invoke-Sqlcmdverwendet wird.

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

Weiterlernen der Anmeldeinformationsverwaltung

Das Sichere Erstellen und Speichern von Anmeldeinformationsobjekten kann schwierig sein. Die folgenden Ressourcen können Ihnen helfen, PowerShell-Anmeldeinformationen zu verwalten.

  • Zuletzt aktualisiert um