Inhaltsverzeichnis

Letzte Aktualisierung am 10.10.2026, 23:10:30 Uhr

NoSpamProxy Server 16.2 verwendet standardmäßig die Basic-Authentifizierung für die Anmeldung. Dieser Artikel beschreibt, wie sich OpenID Connect als Authentifizierungsverfahren einrichten lässt und wie die Integration mit Microsoft Active Directory Federation Services (AD FS) erfolgt.

Die Konfiguration wird Schritt für Schritt erläutert. Von der Vorbereitung der Active Directory (AD) Gruppen über die Einrichtung der AD FS Anwendung bis zur abschließenden Überprüfung der Anmeldung.

Voraussetzungen

Bevor mit der Konfiguration begonnen wird, sollten die erforderlichen Komponenten und Berechtigungen geprüft werden.

NoSpamProxy Server 16.2 ist installiert und funktionsfähig.
Microsoft AD FS steht als Identity Provider (IdP) zur Verfügung.
Der Zugriff auf die AD FS Management Konsole ist vorhanden.
Die erforderlichen Berechtigungen zur Verwaltung von AD und der NoSpamProxy Konfiguration liegen vor.
Die benötigten DNS-Namen und HTTPS-Endpunkte sind erreichbar.

Active Directory Gruppen vorbereiten

Für die spätere Zuordnung der Benutzer zu den Berechtigungsrollen werden die benötigten Sicherheitsgruppen im AD angelegt.

Ziel OU festlegen und validieren

Der Distinguished Name (DN) der Organisationseinheit wird abgefragt und auf seine Existenz überprüft. Ein vorbelegter Standardpfad erleichtert die Ausführung des PowerShell-Skripts.

Sicherheitsgruppen erstellen

Für die rollenbasierte Berechtigungsverwaltung in NoSpamProxy Server können AD Sicherheitsgruppen verwendet werden. Dadurch lassen sich die Berechtigungen zentral über AD verwalten und den jeweiligen Benutzern über die Gruppenmitgliedschaft zuweisen.

Im ersten Schritt werden die benötigten Sicherheitsgruppen im Active Directory angelegt. Für die spätere Konfiguration der Authentifizierung und Autorisierung werden folgende fünf Gruppen verwendet:

Active Directory Gruppe	Zweck
gg-nsp-auth-ConfigurationAdministrator	Administration der Konfiguration
gg-nsp-auth-DisclaimerAdministrator	Verwaltung von Disclaimern
gg-nsp-auth-GlobalAdministrator	Globale Administrationsberechtigungen
gg-nsp-auth-IdentityAdministrator	Verwaltung der Identitäten
gg-nsp-auth-MonitoringAdministrator	Administration des Monitorings

Die Gruppen werden in einer OU angelegt. Das PowerShell-Skript fragt den DN dieser OU ab.

#
# AD groups
#
$defaultGroupPath = "OU=nospamproxy,OU=_groups,DC=lab03,DC=daniel,DC=wydler,DC=eu"

do {
    $inputPath = Read-Host "Distinguished Name der Gruppen-OU [$defaultGroupPath]"

    $groupPath = if ([string]::IsNullOrWhiteSpace($inputPath)) {
        $defaultGroupPath
    }
    else {
        $inputPath.Trim()
    }

    try {
        $null = Get-ADOrganizationalUnit -Identity $groupPath -ErrorAction Stop
        $valid = $true
    }
    catch {
        Write-Warning "Die angegebene OU existiert nicht oder ist nicht erreichbar."
        $valid = $false
    }
} until ($valid)

Write-Host "Gueltige Gruppen-OU: $groupPath" -ForegroundColor Green

$adGroups = @(
    "gg-nsp-auth-ConfigurationAdministrator"
    "gg-nsp-auth-DisclaimerAdministrator"
    "gg-nsp-auth-GlobalAdministrator"
    "gg-nsp-auth-IdentityAdministrator"
    "gg-nsp-auth-MonitoringAdministrator"
)


#
# Create AD groups
#
foreach ($groupName in $adGroups) {

    $group = Get-ADGroup -Filter "Name -eq '$groupName'" -SearchBase $groupPath -ErrorAction SilentlyContinue

    if (-not $group) {
        $group = New-ADGroup -Name $groupName -Path $groupPath -GroupScope Global -GroupCategory Security -PassThru
    }
}

Vor dem Anlegen der Gruppen überprüft das Skript, ob die angegebene OU im AD existiert. Ist die Prüfung erfolgreich, wird der DN für die Erstellung aller fünf Gruppen verwendet.

Benutzer zuordnen

Die vorgesehenen Benutzer werden den passenden Sicherheitsgruppen zugeordnet. Die Gruppenmitgliedschaften bilden die Grundlage für die spätere Zuordnung der Berechtigungen.

OpenID Connect Anwendung in Microsoft AD FS einrichten

Für die Integration von NoSpamProxy Server mit AD FS müssen die erforderlichen Anwendungskomponenten und die zugehörigen Claim-Regeln eingerichtet werden. Diese Konfiguration lässt sich vollständig über PowerShell automatisieren.

Das nachfolgende Skript erstellt die benötigten AD FS Komponenten, konfiguriert die erforderlichen Anwendungsberechtigungen und richtet die Transformationsregeln für die Benutzeridentität und Gruppenmitgliedschaften ein.

Konfiguration automatisieren

Das Skript wird auf einem Server mit installierten AD FS Verwaltungstools und den erforderlichen PowerShell-Berechtigungen ausgeführt. Außerdem muss das AD PowerShell Modul verfügbar sein, da das Skript die konfigurierten Gruppen aus dem Verzeichnis abfragt.

Bitte prüfe vor der Ausführung die folgenden Angaben im Skript und passe sie bei Bedarf an deine Umgebung an:

Zeile 15: Den FQDN des NoSpamProxy Servers mit der Intranet-Rolle durch den eigenen Hostnamen ersetzen.
Zeilen 21-25: Die Namen der AD Gruppen an die eigene Gruppenstruktur anpassen. Die Gruppen müssen in AD bereits vorhanden sein.

Die übrigen Einstellungen können bei einer entsprechenden AD FS und NoSpamProxy Konfiguration unverändert bleiben.

#
# Configuration
#

$arrSunmanagedRules = @()
$arrRuleBlocks = @()


$strApplicationGroupName = "NoSpamProxy"
$strApplicationGroupDescription = "NoSpamProxy OpenID Connect"

$strServerApplicationName = "NoSpamProxy - Server application"
$strWebApiApplicationName = "NoSpamProxy - Web API"

$strNoSpamProxyWebApiIdentifier = "https://nsp01.lab03.daniel.wydler.eu:6061"
$strNoSpamProxyOidcResponseUrl = "$($strNoSpamProxyWebApiIdentifier)/api/identity-service/oidc-code-response"

$strPreferredUsernameRuleName = "NoSpamProxy"

$adGroups = @(
    "gg-nsp-auth-ConfigurationAdministrator"
    "gg-nsp-auth-DisclaimerAdministrator"
    "gg-nsp-auth-GlobalAdministrator"
    "gg-nsp-auth-IdentityAdministrator"
    "gg-nsp-auth-MonitoringAdministrator"
)


#
# Claim types
#
$strGroupsClaimType = "http://schemas.microsoft.com/ws/2008/06/identity/claims/groups"
$strpreferredUsernameClaimType = "http://schemas.openid.net/claims/preferred_username"


#
# Claim descriptions
#
$strGroupsClaimDescription = Get-AdfsClaimDescription | Where-Object { $_.ClaimType -eq $strGroupsClaimType }
$strPreferredUsernameClaimDescription = Get-AdfsClaimDescription | Where-Object { $_.ClaimType -eq $strpreferredUsernameClaimType }

if (-not $strGroupsClaimDescription) {
    Add-AdfsClaimDescription -Name "Groups" -ShortName "groups" -ClaimType $strGroupsClaimType -IsAccepted $true -IsOffered $true -IsRequired $false
}

if (-not $strPreferredUsernameClaimDescription) {
    Add-AdfsClaimDescription -Name "Preferred Username" -ShortName "preferred_username" -ClaimType $strpreferredUsernameClaimType -IsAccepted $true -IsOffered $true -IsRequired $false -Notes "Preferred username for OpenID Connect"
}


#
# Application Group
#

$strApplicationGroup = Get-AdfsApplicationGroup -Name $strApplicationGroupName -ErrorAction SilentlyContinue

if (-not $strApplicationGroup) {
    $strApplicationGroup = New-AdfsApplicationGroup -Name $strApplicationGroupName -Description $strApplicationGroupDescription -PassThru
    $strApplicationGroupId = $strApplicationGroup.ApplicationGroupIdentifier
}

$strApplicationGroupId = $strApplicationGroup.ApplicationGroupIdentifier

#
# Server Application
#

$strServerApplication = Get-AdfsServerApplication -Name $strServerApplicationName -ErrorAction SilentlyContinue

if ($strServerApplication) {

    if ($strServerApplication.ApplicationGroupIdentifier -ne $strApplicationGroupId) {
        throw "The existing server application '$strServerApplicationName' belongs to another application group."
    }

    $clientId = $strServerApplication.Identifier

    # The client secret cannot be retrieved from an existing AD FS server application.
    $clientSecret = $null
}
else {

    $clientId = [guid]::NewGuid().Guid

    $strServerApplication = Add-AdfsServerApplication -ApplicationGroupIdentifier $strApplicationGroupId -Name $strServerApplicationName `
        -Identifier $clientId -RedirectUri $strNoSpamProxyOidcResponseUrl -GenerateClientSecret

    # The client secret is only available when the application is created.
    $clientSecret = $strServerApplication.ClientSecret
}


#
# Web API
#
$strWebApiApplication = Get-AdfsWebApiApplication -Name $strWebApiApplicationName -ErrorAction SilentlyContinue

if ($strWebApiApplication) {

    if ($strWebApiApplication.ApplicationGroupIdentifier -ne $strApplicationGroupId) {
        throw "The existing Web API '$strWebApiApplicationName' belongs to another application group."
    }

    $strWebApiIdentifierExists = $strWebApiApplication.Identifier -contains $strNoSpamProxyWebApiIdentifier

    if (-not $strWebApiIdentifierExists) {
        throw "The existing Web API '$strWebApiApplicationName' does not contain the expected identifier '$strNoSpamProxyWebApiIdentifier'."
    }
}
else {

    $strWebApiApplication = Add-AdfsWebApiApplication -ApplicationGroupIdentifier $strApplicationGroupId -Name $strWebApiApplicationName -AccessControlPolicyName "Permit everyone" `
        -Identifier @(
            $clientId
            $strNoSpamProxyWebApiIdentifier
        )
}


#
# Application Permission
#

$strApplicationPermissions = Get-AdfsApplicationPermission -ServerRoleIdentifiers $strNoSpamProxyWebApiIdentifier -ErrorAction SilentlyContinue

$strApplicationPermission = $strApplicationPermissions | Where-Object { $_.ClientRoleIdentifier -eq $clientId }

if (-not $strApplicationPermission) {

    Grant-AdfsApplicationPermission -ServerRoleIdentifier $strNoSpamProxyWebApiIdentifier -ClientRoleIdentifier $clientId -ScopeNames "allatclaims", "openid"
}


#
# Preferred username transform rule
#
$preferredUsernameRule = @"
@RuleTemplate = "LdapClaims"
@RuleName = "$strPreferredUsernameRuleName"
c:[Type == "http://schemas.microsoft.com/ws/2008/06/identity/claims/windowsaccountname",
   Issuer == "AD AUTHORITY"]
 => issue(
      store = "Active Directory",
      types = ("preferred_username"),
      query = ";userPrincipalName;{0}",
      param = c.Value
    );
"@


#
# Build group transform rules dynamically
#
$arrGroupRules = foreach ($groupName in $adGroups) {

    $group = Get-ADGroup -Identity $groupName -Properties SID -ErrorAction Stop

    @"
@RuleTemplate = "EmitGroupClaims"
@RuleName = "$($group.Name)"
c:[Type == "http://schemas.microsoft.com/ws/2008/06/identity/claims/groupsid",
   Value == "$($group.SID.Value)",
   Issuer == "AD AUTHORITY"]
 => issue(
      Type = "$strGroupsClaimType",
      Value = "$($group.Name)",
      Issuer = c.Issuer,
      OriginalIssuer = c.OriginalIssuer,
      ValueType = c.ValueType
    );
"@
}


#
# Rules managed by this script
#
$managedRuleNames = @($strPreferredUsernameRuleName) + $adGroups


#
# Read existing transform rules
#
$strWebApiApplication = Get-AdfsWebApiApplication -Name $strWebApiApplicationName

$existingRules = $strWebApiApplication.IssuanceTransformRules


#
# Extract existing rule blocks
#
# AD FS may return rules with indentation. A rule starts with
# @RuleTemplate and continues until the next @RuleTemplate.
#

$existingRuleBlocks = @()

if (-not [string]::IsNullOrWhiteSpace($existingRules)) {

    $ruleMatches = [regex]::Matches($existingRules, '(?ms)^\s*@RuleTemplate\s*=.*?(?=^\s*@RuleTemplate\s*=|\z)')

    foreach ($match in $ruleMatches) {
        $existingRuleBlocks += $match.Value.Trim()
    }
}


#
# Preserve rules which are not managed by this script
#
foreach ($rule in $existingRuleBlocks) {

    $ruleNameMatch = [regex]::Match($rule, '(?m)^\s*@RuleName\s*=\s*"([^"]+)"')

    if (-not $ruleNameMatch.Success) {
        
        # Preserve rules whose name cannot be determined.
        $arrSunmanagedRules += $rule
        continue
    }

    $ruleName = $ruleNameMatch.Groups[1].Value

    if ($managedRuleNames -notcontains $ruleName) {
        $arrSunmanagedRules += $rule
    }
}


#
# Build complete transform rule set
#
$arrRuleBlocks += $arrSunmanagedRules
$arrRuleBlocks += $preferredUsernameRule.Trim()
$arrRuleBlocks += $arrGroupRules

$issuanceTransformRules = $arrRuleBlocks |
    Where-Object { -not [string]::IsNullOrWhiteSpace($_) } | ForEach-Object {
        $_.Trim()
    }

$issuanceTransformRules = $issuanceTransformRules -join "`r`n`r`n"


#
# Apply transform rules
#
Set-AdfsWebApiApplication -TargetName $strWebApiApplicationName -IssuanceTransformRules $issuanceTransformRules


#
# Output
#
Write-Host "`nNoSpamProxy AD FS configuration completed.`n" -ForegroundColor Green
Write-Host "Application Group: $strApplicationGroupName"
Write-Host "Client ID:         $clientId"
Write-Host "Web API:           $strNoSpamProxyWebApiIdentifier`n"

if ($clientSecret) {
    Write-Host "Client Secret:     $clientSecret`n" -ForegroundColor Yellow
    Write-Host "IMPORTANT: Store the client secret securely. It is only available when the server application is created." -ForegroundColor Yellow
}
else {
    Write-Host "Client Secret:     Existing application - secret was not retrieved.`n"
}

Anwendungskomponenten erstellen

Das Skript richtet eine AD FS Anwendungsgruppe mit dem Namen NoSpamProxy ein. Diese umfasst eine Server Application und eine Web API. Die Web API wird über die konfigurierte NoSpamProxy URL identifiziert. Zusätzlich wird die Rücksprungadresse für die OpenID Connect Anmeldung hinterlegt.

Anwendungsberechtigungen konfigurieren

Damit NoSpamProxy die erforderlichen Identitätsinformationen abrufen kann, werden der Server Application die benötigten Berechtigungen für die Web API zugewiesen.

Claims für die Benutzeridentität konfigurieren

Über den Claim preferred_username wird der Benutzername an NoSpamProxy übermittelt. Das Skript ordnet hierzu das Active-Directory-Attribut userPrincipalName dem entsprechenden Claim zu.

Gruppenmitgliedschaften als Claims übermitteln

Die AD FS Konfiguration übermittelt die für NoSpamProxy relevanten Gruppenmitgliedschaften als groups-Claims. Dazu ermittelt das Skript die Sicherheitskennungen (SIDs) der konfigurierten AD Gruppen und erstellt die entsprechenden Transformationsregeln.

Vorhandene Konfiguration berücksichtigen

Das Skript berücksichtigt bereits vorhandene Anwendungskomponenten und verwaltet die von ihm angelegten Transformationsregeln gezielt. Andere, nicht vom Skript verwaltete Regeln bleiben erhalten.

Client Secret sicher aufbewahren

Bei der erstmaligen Erstellung der Server Application wird ein Client Secret ausgegeben. Dieses muss sicher gespeichert werden, da AD FS ein bereits vorhandenes Secret nicht erneut im Klartext bereitstellt. Das Secret wird später bei der Konfiguration des OpenID Connect Providers in NoSpamProxy benötigt.

OpenID Connect in NoSpamProxy konfigurieren

Nachdem Microsoft AD FS als IdP eingerichtet wurde, erfolgt die Konfiguration auf dem NoSpamProxy-Server mit der Intranet-Rolle über die PowerShell-Schnittstelle. Die erforderlichen Cmdlets werden nacheinander ausgeführt.

Administrativen Zugriff sicherstellen

Bevor der OpenID-Connect-Provider registriert werden kann, wird zunächst eine administrative Rollenberechtigung für den aktuell angemeldeten Benutzer eingerichtet.

Dazu wird eine Verbindung mit NoSpamProxy hergestellt und dem aktuellen Benutzer die Rolle GlobalAdministrator zugewiesen.

Connect-Nsp -Credential $(Get-Credential)
New-NspUserRoleAssignment -Identity (whoami) -Role GlobalAdministrator

Anschließend kann die PowerShell-Sitzung beendet werden:

exit

OpenID Connect-Provider registrieren

Im nächsten Schritt wird der OpenID Connect-Provider in NoSpamProxy registriert. Hierzu wird erneut eine Verbindung hergestellt und das Client Secret als SecureString eingelesen.

Connect-Nsp -Credential $(Get-Credential)

$clientsec = Read-Host -AsSecureString

$strClientId = "a50c15f9-7ad9-463d-a563-1a018231e0c2"

$strIdpDiscoveryEndpoint = "https://login.lab03.daniel.wydler.eu/adfs/.well-known/openid-configuration"

New-NspOpenIdProvider -Name "Microsoft ADFS" -DisplayName "Login LAB03" -ClientId $strClientId -ClientSecret $clientsec -DiscoveryEndpoint $strIdpDiscoveryEndpoint -Force

Hinweise:

Übernimm die Client ID und das Client Secret aus der Ausgabe des zuvor ausgeführten PowerShell-Skripts zur AD FS Konfiguration. Passe außerdem den Discovery Endpoint an deine Umgebung an.
Der verwendete Endpunkt folgt üblicherweise diesem Schema: https://<FQDN>/adfs/.well-known/openid-configuration. Ersetze <FQDN> durch den vollständig qualifizierten Domänennamen deines AD FS Servers.

AD Gruppen den NoSpamProxy Rollen zuordnen

Abschließend werden die zuvor angelegten AD Gruppen den entsprechenden Rollen in NoSpamProxy zugewiesen.

New-NspUserRoleAssignment -TenantId 0 -Identity "gg-nsp-auth-GlobalAdministrator" -Role GlobalAdministrator
New-NspUserRoleAssignment -TenantId 0 -Identity "gg-nsp-auth-ConfigurationAdministrator" -Role ConfigurationAdministrator
New-NspUserRoleAssignment -TenantId 0 -Identity "gg-nsp-auth-DisclaimerAdministrator" -Role DisclaimerAdministrator
New-NspUserRoleAssignment -TenantId 0 -Identity "gg-nsp-auth-IdentityAdministrator" -Role IdentityAdministrator
New-NspUserRoleAssignment -TenantId 0 -Identity "gg-nsp-auth-MonitoringAdministrator" -Role MonitoringAdministrator

Damit sind die Gruppen den vorgesehenen Rollen zugeordnet. Die Gruppenmitgliedschaften im AD bestimmen anschließend, welche Benutzer über die jeweilige Gruppenrolle die entsprechenden Berechtigungen erhalten.