> For the complete documentation index, see [llms.txt](https://docs.devolutions.net/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.devolutions.net/powershell-universal/de/sicherheit/forms-authentication.md).

# Formularbasierte Authentifizierung

{% hint style="warning" %}
Das Skript für die Formularauthentifizierung wird nur aufgerufen, wenn sich Benutzer über die Anmeldeseite anmelden. Wenn Sie eine andere Authentifizierungsmethode verwenden, wird dieses Skript nicht aufgerufen. Rollenrichtlinien-Skripte werden für alle Authentifizierungstypen aufgerufen.
{% endhint %}

Standardmäßig ist das Skript für die Formularauthentifizierung so konfiguriert, dass es den Benutzer Admin und ein beliebiges Passwort akzeptiert. Sie können diese Authentifizierungsrichtlinie so konfigurieren, dass sie mit jedem System interagiert, das Sie möchten. Das Skript erhält ein `PSCredential`-Objekt, das den Benutzernamen und das Passwort enthält, die der Benutzer auf der Anmeldeseite eingegeben hat.

{% hint style="info" %}
Authentifizierungseinstellungen werden ebenfalls mit `authentication.ps1` gespeichert
{% endhint %}

Um die Formularauthentifizierung zu aktualisieren, können Sie auf Einstellungen Sicherheit klicken und dann auf die Schaltfläche Code bearbeiten für die Formularauthentifizierung klicken.

Sie können das PowerShell-Skript in den Einstellungen aktualisieren, um zu konfigurieren, wie der Benutzer authentifiziert wird. Sie müssen ein `New-PSUAuthenticationResult` aus dem Skript zurückgeben, um anzugeben, ob der Benutzer erfolgreich authentifiziert wurde.

```powershell
param(
    [PSCredential]$Credential
)

#
#   You can call whatever cmdlets you like to conduct authentication here.
#   Just make sure to return the $Result with the Success property set to $true
#

if ($Credential.UserName -eq 'Admin') 
{
    New-PSUAuthenticationResult -Success -UserName 'Admin'
}
else 
{
    New-PSUAuthenticationResult -ErrorMessage 'Bad username or password'
}
```

## Festlegen eines Passworts

Sie können das Passwort der Anmeldeinformationen mit der Methode `GetNetworkCredential()` von `PSCredential` überprüfen.

```powershell
param(
    [PSCredential]$Credential
)

#
#   You can call whatever cmdlets you like to conduct authentication here.
#   Just make sure to return the $Result with the Success property set to $true
#

if ($Credential.UserName -eq 'Admin' -and $Credential.GetNetworkCredential().Password -eq 'MySuperSecretPassword') 
{
    New-PSUAuthenticationResult -Success -UserName 'Admin'
}
else 
{
    New-PSUAuthenticationResult -ErrorMessage 'Bad username or password'
}
```

## Festlegen von Claims

Während der Formularauthentifizierung können Sie Claims festlegen, die innerhalb von Rollenrichtlinien verfügbar sind. Dies kann bei der Interaktion mit Remote-Systemen einen Leistungsvorteil bieten, da Sie eine einzelne Claim-Abfrage durchführen und die Claims dann lokal auswerten können, anstatt zusätzliche Aufrufe an das Remote-System durchführen zu müssen.

Dieses Beispiel verwendet Active Directory, um die Gruppenmitgliedschaft abzufragen und diese als Claims zuzuweisen, die innerhalb der Rollen-Skripte verfügbar sind.

```powershell
param(
    [PSCredential]$Credential
)

#
#   You can call whatever cmdlets you like to conduct authentication here.
#   Just make sure to return the $Result with the Success property set to $true
#

$Result = [Security.AuthenticationResult]::new()
if ($Credential.UserName -eq 'Admin') 
{
    #Maintain the out of box admin user
    New-PSUAuthenticationResult -UserName 'Admin' -Success
}
else
{
    # Get current domain using logged-on user's credentials - this validates their credential
    $CurrentDomain = "LDAP://DC=mydemodomain,DC=com"  # Insert Your Domain Here
    $domain = New-Object System.DirectoryServices.DirectoryEntry($CurrentDomain,($Credential.UserName),$Credential.GetNetworkCredential().password)

    if ($domain.name -eq $null)
    {
        "Authentication failed for $($Credential.UserName)!" | Out-File "C:\test\adlogin.txt"
        write-host "Authentication failed - please verify your username and password."
        New-PSUAuthenticationResult -UserName $Credential.UserName
    }
    else
    {
        write-host "Successfully authenticated with domain $($domain.name)"
        "Authentication success for $($Credential.UserName)!" | Out-File "C:\test\adlogin.txt"

        New-PSUAuthenticationResult -UserName $Credential.UserName -Success -Claims { 
            Get-ADPrincipalGroupMembership $Credential.UserName | Select-Object -ExpandProperty name | ForEach-Object {
                New-PSUAuthorizationClaim -Type Role -Value $_
            }
        }
    }
}
```

Innerhalb Ihrer `roles.ps1`-Datei können Sie diese Claims verwenden, um die Gruppenmitgliedschaft zu validieren.

Dieses Beispiel prüft, ob der Benutzer Teil der Gruppe SOC\_Admins ist.

```powershell
param($User)

$Roles = $User.Claims | Where-Object Type -eq Role | Select-Object -ExpandProperty Value
$Roles -contains 'SOC_Admins'
```

## Variablen

Dies sind die innerhalb der Sicherheitsskripte definierten Variablen.

| Name             | Beschreibung                                             | Typ       |
| ---------------- | -------------------------------------------------------- | --------- |
| $Cookies         | In der HTTP-Anfrage des Clients bereitgestellte Cookies. | hashtable |
| $Headers         | In der HTTP-Anfrage des Clients bereitgestellte Header.  | hashtable |
| $LocalIpAddress  | Die lokale IP-Adresse der Anfrage.                       | string    |
| $LocalPort       | Der lokale Port der Anfrage.                             | string    |
| $RemoteIpAddress | Die Remote-IP-Adresse der Anfrage.                       | string    |
| $RemotePort      | Der Remote-Port der Anfrage.                             | string    |

## Basic-Authentifizierung

Beim Aufrufen von API-Endpunkten oder der PowerShell Management API können Sie die Basic-Authentifizierung verwenden, um einen Benutzernamen und ein Passwort zu übergeben. Dadurch werden die Skripte für Formularauthentifizierung und -autorisierung aufgerufen, um die Anmeldung zu validieren. Benutzername und Passwort sollten im Format `username:password` als Base64 codiert und im Authorization-Header mit dem Präfix `Basic` gesendet werden.

```powershell
$credentials = [Convert]::ToBase64String([Text.Encoding]::ASCII.GetBytes("admin:admin"))
Invoke-RestMethod $Env:UniversalUrl/api/v1/accessible -Headers @{
    Authorization = "Basic $credentials"
} 
```

Sie können auch den integrierten Parameter -Credential von Invoke-RestMethod verwenden, um die Basic-Anmeldeinformationen nicht selbst codieren zu müssen. Das nachstehende `$AdminCredential` muss ein `PSCredential` sein.

```powershell
Invoke-RestMethod $Env:UniversalUrl/api/v1/accessible -Credential $AdminCredential -Authentication Basic
```

## Windows-Anmeldung

Wenn Sie die native Anmeldung für die Formularauthentifizierungsmethode aktivieren, versucht PowerShell Universal, sich mit den angegebenen Anmeldeinformationen am aktuellen Computer oder an der aktuellen Domäne anzumelden. Nach der Anmeldung werden die Gruppen des Benutzers erfasst und dann dem Autorisierungssystem bereitgestellt.

Sie können eine nicht standardmäßige Domäne konfigurieren, indem Sie die Domäne für die native Anmeldung angeben. Wenn Sie diese Domäne nicht angeben, wird die Standarddomäne des Computers oder die vom Benutzer angegebene Domäne verwendet.

## Live-Protokoll

Sie können die Live-Protokollansicht auf der Authentifizierungsseite verwenden, um Informationen über die Skriptausführung anzuzeigen. Die Live-Protokollansicht zeigt PowerShell-Streams an.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://docs.devolutions.net/powershell-universal/de/sicherheit/forms-authentication.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.