Audis.Authentication 2.0.0

Audis.Authentication

Gemeinsame Authentifizierung für das AUDIS-Ökosystem (AUDIS, Trust, Storage, Adapter, Analyzer, ...): Policies mit Modus Disabled/Audit/Enforce, X-Api-Key-Mechanismus, Erweiterungspunkt für weitere Mechanismen (z.B. Audis.Authentication.Hmac, Audis.Authentication.Jwt) und Authentifizierung ausgehender Requests über HttpClient.

Verwendung

Der Code legt nur fest, was geschützt wird (Policy). Welche Mechanismen eine Policy erfüllen und in welchem Modus sie läuft, steht in der Konfiguration. Policies ohne Konfiguration sind Disabled, das Verhalten der Anwendung bleibt dann unverändert.

Policies: Browser, ServiceToService, Webhook, Administration, Diagnostics (siehe AudisAuthPolicies). Weitere Policies müssen mit AddPolicy("<Name>") registriert werden; unbekannte Policy-Namen unter Authentication:Inbound:Policies lassen den Start fehlschlagen (Vergleich ohne Groß-/Kleinschreibung).

// Inbound (jeder Dienst)
builder.Services.AddAudisAuthentication(builder.Configuration)
    .AddApiKey();

app.UseAuthentication();
app.UseAuthorization();

group.MapPost("/{tenantId}/{externalId}/external-knowledge", ...)
     .RequireAudisAuth(AudisAuthPolicies.ServiceToService);
// Endpunkte ohne Policy bleiben unverändert.

// Outbound: ein HttpClient für viele Ziele, Credential pro Request
services.AddHttpClient<IEndpointNotifier, HttpEndpointNotifier>()
        .AddAudisOutboundAuthentication();

request.Options.Set(AudisAuthRequestOptions.Credential, endpoint.Credential); // z.B. "analyzer-xy"

// Outbound: ein HttpClient für ein Ziel (Adapter, Analyzer), Credential fest am Client
services.AddHttpClient<IAudisClient, AudisClient>()
        .AddAudisOutboundAuthentication("audis");

// ... oder Name aus der Konfiguration der Integration (leer = ohne Auth, opt-in)
services.AddHttpClient("weather-analyzer")
        .AddAudisOutboundAuthentication(sp => sp.GetRequiredService<IConfiguration>()["Analyzers:Weather:Credential"]);

AddAudisAuthentication ist für Hosts (AUDIS) und Clients (Adapter, Analyzer) gleich: Ein Dienst, der nur authentifiziert sendet, registriert es ebenso; ohne konfigurierte Policies ändert sich für eingehende Requests nichts.

Konfiguration (appsettings.json bzw. Key Vault):

"Authentication": {
  "Inbound": {
    "ApiKey": {
      "Clients": [
        { "Name": "health-dashboard", "Keys": [ "<neu>", "<alt>" ], "Policies": [ "Diagnostics" ] },
        { "Name": "cobra-adapter", "Keys": [ "<key>" ], "Policies": [ "ServiceToService" ], "Tenants": [ "tenant-a" ] }
      ]
    },
    "Policies": {
      "ServiceToService": { "Schemes": [ "ApiKey" ], "Mode": "Audit" },
      "Diagnostics":      { "Schemes": [ "ApiKey" ], "Mode": "Enforce" }
    }
  },
  "Outbound": {
    "Credentials": {
      "analyzer-xy": {
        "Type": "ApiKey",
        "Key": "<secret>",
        "AllowedOrigins": [ "https://analyzer.example.org" ]
      },
      "function-analyzer": {
        "Type": "ApiKey",
        "Key": "<secret>",
        "QueryParameter": "code",
        "AllowedOrigins": [ "https://function.example.org" ]
      }
    }
  }
}

Hinweise:

• UseAuthentication() und UseAuthorization() sind erforderlich. AUDIS-Schemes werden nie Default-Scheme und laufen nur über AUDIS-Policies. Hat der Host genau ein eigenes Scheme (z.B. Cookie), bleibt es Default-Scheme wie ohne AUDIS; ein explizit gesetztes Default-Scheme bleibt unverändert.

• Disabled- und Audit-Policies verändern die Autorisierung eines Endpunkts nicht: Ohne eigene Autorisierung des Hosts gilt dessen FallbackPolicy (wie ohne AUDIS-Metadaten), mit eigener Autorisierung (z.B. RequireAuthorization(...)) entscheidet nur diese. In Enforce zählen für die Rechte nur Identitäten aus den Schemes der AUDIS-Policy, nie die eines kombinierten Host-Schemes.

• Die Konfiguration wird beim Start (ValidateOnStart) und bei jedem Config-Reload validiert: unbekannte Policies (nicht well-known und nicht mit AddPolicy registriert), unbekannte Schemes, Audit/Enforce ohne Schemes, ApiKey-Clients ohne Namen oder Key, unbekannte Policies oder ungültige Mandanten in Policies/Tenants eines Clients, ungültige Header/Prefix/QueryParameter, Credentials ohne bzw. mit unbekanntem Type, Credentials ohne oder mit ungültigen AllowedOrigins und die Settings jedes Credentials durch den Authenticator seines Type (z.B. ApiKey ohne Key). Fehlermeldungen enthalten nie Secrets.

• Alles wirkt ohne Neustart und ohne neues Release, sobald die Konfiguration neu geladen wird: Modus und Schemes einer Policy (Rollout Disabled → Audit → Enforce, Wechsel z.B. von ApiKey auf Hmac), Clients, Keys, Policies/Tenants, Header-Einstellungen und Outbound-Credentials (Wechsel des Type, Key-Rotation). Voraussetzung ist, dass der Dienst alle verwendeten Mechanismen registriert (AddApiKey(), AddHmac(), AddJwt()); die Konfiguration wählt nur aus. Ein ungültiger Reload wird nicht übernommen: Es bleibt die zuletzt gültige Konfiguration aktiv, inklusive der Secrets der Credentials, und es wird ein Fehler geloggt (EventId 1002, ohne Secrets). Key Vault lädt nur neu, wenn beim Einbinden ein ReloadInterval gesetzt ist.

• Rechte pro Client: Policies beschränkt einen Client auf bestimmte Policies, Tenants auf bestimmte Mandanten (beides ohne Groß-/Kleinschreibung). Leere Listen beschränken nicht, bestehende Clients behalten ihre Rechte. Der Mandant eines Requests kommt aus dem Route-Wert Authentication:Inbound:TenantRouteValue (Default tenantId) oder aus einem eigenen IAudisTenantResolver (AddTenantResolver<T>()); Endpunkte ohne Mandant sind nur über Policies beschränkt. In Enforce wird ein Request außerhalb der Rechte mit 403 abgewiesen, in Audit läuft er durch und wird als Warnung geloggt (EventId 1006, Policy, Pfad, Client-Name). Die Claims audis:policy und audis:tenant stellt AudisClientScope.CreateClaims aus; eigene Mechanismen nutzen dafür IAudisClientScope.

• ApiKey-Transport (eingehend unter Inbound:ApiKey, ausgehend pro Credential): Header (Default X-Api-Key), optional Prefix (z.B. Bearer für Authorization: Bearer <key>; Werte ohne Präfix ignoriert das Scheme, damit z.B. JWT auf demselben Header weiter funktioniert) oder QueryParameter statt Header (z.B. code für Azure Functions). QueryParameter ist mit Header/Prefix nicht kombinierbar. Keys im Query-String können in Access-Logs landen; wenn möglich Header verwenden.

• ApiKey-Client-Namen müssen eindeutig sein (ohne Groß-/Kleinschreibung) und ein Key darf nur zu einem Client gehören.

• Ist die ApiKey-Konfiguration nach einem Reload ungültig, bleiben die zuletzt gültigen Keys aktiv und es wird ein Fehler geloggt (EventId 1002 bei Validierungsfehlern, ohne Secrets; EventId 1003, wenn sich die Konfiguration nicht binden lässt, z.B. Text statt Zahl, nur mit Exception-Typ). Beim Start schlägt ungültige Konfiguration weiterhin sofort fehl.

• Ausgehende Requests ohne AudisAuthRequestOptions.Credential (und ohne am Client gebundenes Credential) werden unverändert gesendet. Ein am Client gebundenes Credential (AddAudisOutboundAuthentication("<name>")) gilt für jeden Request, außer der Request setzt AudisAuthRequestOptions.Credential selbst; ein explizit leerer Wert sendet ohne Credential. Ein unbekanntes Credential oder ein unbekannter Type führt zu einer AudisOutboundAuthenticationException (fail closed). In Tenant- oder Revision-Settings und in Hangfire-Jobs steht nur der Name des Credentials, nie das Secret.

• Jedes Credential braucht AllowedOrigins: die Origins (Schema, Host und optional Port, ohne Pfad, Query oder Fragment), an die das Credential gesendet werden darf, z.B. https://trust.example.org oder https://trust.example.org:8443. Erlaubt ist nur https; http nur für Loopback-Hosts (localhost, 127.0.0.1, [::1]). Die Liste wird beim Start und bei jedem Config-Reload validiert und danach geparst zwischengespeichert (kein erneutes Parsen pro Request). Ist die Konfiguration nach einem Reload ungültig (z.B. ein ungültiger oder fehlender Origin), bleiben die zuletzt gültigen AllowedOrigins aktiv und es wird ein Fehler geloggt (EventId 1002, ohne Secrets); ein gültiger Reload wirkt ohne Neustart.

• Zielt ein Request mit Credential auf einen Origin, der nicht in AllowedOrigins steht, wird er weder authentifiziert noch gesendet (fail closed, für alle Mechanismen wie ApiKey und Hmac): AudisOutboundOriginNotAllowedException (abgeleitet von AudisOutboundAuthenticationException) und ein Error-Log (EventId 1004) mit Credential-Name und Request-Origin, ohne Pfad, Query oder Secret. So kann ein Credential nicht durch eine geänderte Ziel-URL (z.B. in Tenant-Settings) an einen fremden Host gelangen.

• Redirects (3xx) werden bei Clients mit AddAudisOutboundAuthentication() nicht automatisch verfolgt: Am Primary-Handler (SocketsHttpHandler bzw. HttpClientHandler) wird AllowAutoRedirect = false gesetzt, alle übrigen Einstellungen eines vom Host konfigurierten Primary-Handlers bleiben erhalten. Die 3xx-Response geht an den Aufrufer; ein verfolgter Redirect auf einen anderen Origin würde sonst das Credential (z.B. X-Api-Key) an einen nicht geprüften Host senden. Das gilt für alle Requests des Clients, auch ohne Credential (die Einstellung gehört zum Primary-Handler, nicht zum Request). Sollen Requests ohne Credential Redirects weiterhin folgen, sendet der Host sie über einen eigenen Client ohne AddAudisOutboundAuthentication(). Wird der Primary-Handler danach ersetzt und folgt Redirects, wird eine Response von einem anderen Origin verworfen: AudisOutboundOriginNotAllowedException und Error-Log (EventId 1005) mit Credential-Name und Origins.

• Key Vault: Listen werden mit Index benannt, z.B. Authentication--Outbound--Credentials--analyzer-xy--AllowedOrigins--0.

• Retry-Handler vor AddAudisOutboundAuthentication() registrieren, damit jeder Versuch neu authentifiziert wird.

• Neue Verfahren brauchen Code, aber nur an einer Stelle pro Richtung: eingehend ein IAudisAuthMechanism (AddMechanism, Settings unter Inbound:<Name>, Rechte über IAudisClientScope und AudisClientScope), ausgehend ein IOutboundAuthenticator (AddOutboundAuthenticator<T>()), der mit ValidateSettings seine Credential-Settings beim Start und bei jedem Reload selbst prüft. Policies, Modi, Audit-Log, Rechte pro Client, AllowedOrigins, Redirect-Schutz und LastValid-Schutz gelten dann ohne weitere Änderung.

• AUDIS-Policies wirken auf Endpunkt-Ebene (RequireAudisAuth(...), auch für MapHub(...)). Die Anforderungen werten den HttpContext des Requests aus: Bei einer Autorisierung mit einer anderen Ressource (z.B. [Authorize(Policy = ...)] an einer SignalR-Hub-Methode oder IAuthorizationService.AuthorizeAsync mit eigener Ressource) wird der Zugriff in Enforce abgewiesen (fail closed) und in Audit als fehlendes Credential geloggt.

Lizenz

MIT, © softaware gmbh.