ValidateSAMLAssertion-Richtlinie

Erweiterbare Richtlinie

Diese Seite gilt für Apigee und Apigee Hybrid.

Apigee Edge-Dokumentation aufrufen

Mit der ValidateSAMLAssertion-Richtlinie können API-Proxys SAML-Assertions validieren, die an eingehende SOAP-Anfragen angehängt sind. Die SAML-Richtlinie validiert eingehende Nachrichten, die eine digital signierte SAML-Assertion enthalten, lehnt sie ab, wenn sie ungültig sind, und legt Variablen fest, die es zusätzlichen Richtlinien oder den Back-End-Diensten selbst ermöglichen, die Informationen in der Assertion zusätzlich zu validieren. Weitere Informationen finden Sie unter SAML-Richtlinien – Übersicht.

Diese Richtlinie ist eine erweiterbare Richtlinie, deren Verwendung je nach Apigee-Lizenz Auswirkungen auf die Kosten oder die Nutzung haben kann. Informationen zu Richtlinientypen und Auswirkungen auf die Nutzung finden Sie unter Richtlinientypen.

Beispiele

<ValidateSAMLAssertion name="SAML" ignoreContentType="false">
  <Source name="request">
    <Namespaces>
      <Namespace prefix='soap'>http://schemas.xmlsoap.org/soap/envelope/</Namespace>
      <Namespace prefix='wsse'>http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wssecurity-secext-1.0.xsd</Namespace>
      <Namespace prefix='saml'>urn:oasis:names:tc:SAML:2.0:assertion</Namespace>
    </Namespaces>
    <AssertionXPath>/soap:Envelope/soap:Header/wsse:Security/saml:Assertion</AssertionXPath>
    <SignedElementXPath>/soap:Envelope/soap:Header/wsse:Security/saml:Assertion</SignedElementXPath>
  </Source>
  <TrustStore>TrustStoreName</TrustStore>
  <RemoveAssertion>false</RemoveAssertion>
</ValidateSAMLAssertion>

Elementverweis

SAML-Assertion validieren

Feldname Beschreibung
name Attribut
Der Name der Richtlinieninstanz. Der Name darf innerhalb der Organisation nur einmal vorkommen. Folgende Zeichen sind im Namen zulässig: A-Z0-9._\-$ %. Die Apigee-Benutzeroberfläche erzwingt jedoch zusätzliche Einschränkungen, z. B. das automatische Entfernen nicht alphanumerischer Zeichen.
ignoreContentType Attribut Ein boolescher Wert, der auf true oder false gesetzt werden kann. Standardmäßig wird die Assertion nicht validiert, wenn der Inhaltstyp der Nachricht kein XML-Inhaltstyp ist. Wenn diese Einstellung auf true gesetzt ist, wird die Nachricht unabhängig vom Inhaltstyp als XML behandelt.
Source Das Ziel der Richtlinie. Gültige Werte sind message, request und response. Wenn diese Richtlinie auf message gesetzt ist, ruft die Richtlinie das Nachrichtenobjekt orientiert am Anhangspunkt der Richtlinie ab. Wenn die Richtlinie an den Anfrageablauf angehängt ist, wird message in request aufgelöst, und wenn sie an den Antwortablauf angehängt ist, wird message in response aufgelöst.
XPath
Veraltet. Untergeordnet unter Source. Verwenden Sie AssertionXPath und SignedElementXPath.
AssertionXPath
Untergeordnet unter Source. Ein XPath-Ausdruck, der das Element im eingehenden XML-Dokument angibt, aus dem die Richtlinie die SAML-Assertion extrahieren kann.
SignedElementXPath
Untergeordnet unter Source. Ein XPath-Ausdruck, der das Element im eingehenden XML-Dokument angibt, aus dem die Richtlinie das signierte Element extrahieren kann. Dies kann ein anderer oder derselbe XPath sein wie der für AssertionXPath.
TrustStore
Der Name des TrustStore, der vertrauenswürdige X.509-Zertifikate enthält, die zur Überprüfung digitaler Signaturen auf SAML-Assertions verwendet werden.
RemoveAssertion
Ein boolescher Wert, der auf true oder false gesetzt werden kann. Bei true wird die SAML-Assertion aus der Anfragenachricht entfernt, bevor die Nachricht an den Back-End-Dienst weitergeleitet wird.

Verwendungshinweise

Richtlinienverarbeitung:

  1. Die Richtlinie überprüft die eingehende Nachricht, um sicherzustellen, dass der Medientyp der Anfrage XML ist, indem überprüft wird, ob der Inhaltstyp den Formaten text/(.*+)?xml oder application/(.*+)?xml entspricht. Wenn der Medientyp nicht XML ist und das Attribut ignoreContentType nicht auf true gesetzt ist, gibt die Richtlinie einen Fehler aus.
  2. Die Richtlinie parst den XML. Wenn das Parsen fehlschlägt, wird ein Fehler ausgelöst.
  3. Die Richtlinie extrahiert das signierte Element und die Assertion mithilfe der entsprechenden XPaths (<SignedElementXPath> und <AssertionXPath>). Wenn einer dieser Pfade kein Element zurückgibt, löst die Richtlinie einen Fehler aus.
  4. Die Richtlinie prüft, ob die Behauptung mit dem signierten Element übereinstimmt oder ein untergeordnetes Element des signierten Elements ist. Wenn dies nicht "true" ist, gibt die Richtlinie einen Fehler aus.
  5. Wenn eines der Elemente <NotBefore> oder <NotOnOrAfter> in der Assertion vorhanden ist, prüft die Richtlinie den aktuellen Zeitstempel mit diesen Werten, wie im SAML Core Abschnitt 2.5.1 beschrieben.
  6. Die Richtlinie wendet alle zusätzlichen Regeln zur Verarbeitung der „Bedingungen“ (siehe SAML Core Abschnitt 2.5.1.1) an.
  7. Die Richtlinie validiert die digitale XML-Signatur mit dem oben beschriebenen Truststore-Wert (<TrustStore>). Wenn die Validierung fehlschlägt, gibt die Richtlinie einen Fehler aus.

Wenn die Richtlinie abgeschlossen ist, ohne einen Fehler auszugeben, kann der Entwickler des Proxys Folgendes ermitteln:

  • Die digitale Signatur in der Assertion ist gültig und wurde von einer vertrauenswürdigen Zertifizierungsstelle signiert.
  • Die Assertion ist für den aktuellen Zeitraum gültig.
  • Der Betreff und der Aussteller der Assertion werden extrahiert und in Ablaufvariablen festgelegt. Es liegt in der Verantwortung anderer Richtlinien, diese Werte für eine zusätzliche Authentifizierung zu verwenden, z. B. um zu überprüfen, ob der Antragstellername gültig ist, oder um ihn zur Validierung an ein Zielsystem zu übergeben.

Andere Richtlinien wie ExtractVariables können verwendet werden, um die Roh-XML der Assertion für eine komplexere Validierung zu parsen.

Ablaufvariablen

Es gibt viele Informationen, die in einer SAML-Assertion angegeben werden können. Die SAML-Assertion selbst ist XML, das mit der ExtractVariables-Richtlinie und anderen Mechanismen geparst werden kann, um komplexere Validierungen zu implementieren.

Variable Beschreibung
saml.id Die SAML-Assertion-ID
saml.issuer Der "Issuer" der Assertion, der vom nativen XML-Typ in einen String konvertiert wird
saml.subject Der Betreff der Assertion, der aus dem nativen XML-Typ in einen String konvertiert wird
saml.valid Gibt wahr oder falsch zurück, basierend auf dem Ergebnis der Gültigkeitsprüfung
saml.issueInstant IssueInstant
saml.subjectFormat Subject-Format
saml.scmethod Subject-Bestätigungsmethode
saml.scdaddress Adresse der Subject-Bestätigungsdaten
saml.scdinresponse Subject-Bestätigungsdaten als Antwort
saml.scdrcpt Empfänger der Subject-Bestätigungsdaten
saml.authnSnooa AuthnStatement SessionNotOnOrAfter
saml.authnContextClassRef AuthnStatement AuthnContextClassRef
saml.authnInstant AuthnStatement AuthInstant
saml.authnSessionIndex AuthnStatement Sitzungsindex

Fehlerreferenz

In diesem Abschnitt werden die zurückgegebenen Fehlercodes und Fehlermeldungen beschrieben, die von Apigee festgelegt werden, wenn die Richtlinie einen Fehler auslöst. Diese Informationen sind wichtig, wenn Sie Fehlerregeln zur Verarbeitung von Fehlern entwickeln. Weitere Informationen finden Sie unter Was Sie über Richtlinienfehler wissen müssen und Fehler beheben.

Bereitstellungsfehler

Diese Fehler können auftreten, wenn Sie einen Proxy mit dieser Richtlinie bereitstellen.

Fehlername Ursache Diverse Fehlerkorrekturen
SourceNotConfigured Mindestens eines der folgenden Elemente der Richtlinie ValidateSAMLAssertion ist nicht definiert oder leer: <Source>, <XPath>, <Namespaces>, <Namespace>.
TrustStoreNotConfigured Wenn das Element <TrustStore> leer oder nicht in der ValidateSAMLAssertion-Richtlinie angegeben ist, schlägt die Bereitstellung des API-Proxys fehl. Ein gültiger Trust Store ist erforderlich.
NullKeyStoreAlias Wenn das untergeordnete Element <Alias> leer oder im Element <Keystore> der GenerateSAMLAssertion-Richtlinie nicht angegeben ist, schlägt die Bereitstellung des API-Proxys fehl. Ein gültiger Keystore-Alias ist erforderlich.
NullKeyStore Wenn das untergeordnete Element <Name> leer oder im Element <Keystore> der GenerateSAMLAssertion-Richtlinie nicht angegeben ist, schlägt die Bereitstellung des API-Proxys fehl. Ein gültiger Keystore-Name ist erforderlich.
NullIssuer Wenn das Element <Issuer> leer oder nicht in der GenerateSAMLAssertion-Richtlinie angegeben ist, schlägt die Bereitstellung des API-Proxys fehl. Geben Sie einen gültigen <Issuer>-Wert ein.

Fehlervariablen

Diese Variablen werden bei Laufzeitfehlern festgelegt. Weitere Informationen finden Sie unter Was Sie über Richtlinienfehler wissen müssen.

Variablen Wo Beispiel
fault.name="fault_name" fault_name ist der Name des Fehlers. Der Fehlername ist der letzte Teil des Fehlercodes. fault.name = "InvalidMediaTpe"
GenerateSAMLAssertion.failed Bei einer validierten SAML-Assertion-Richtlinienkonfiguration lautet das Fehlerpräfix ValidateSAMLAssertion. GenerateSAMLAssertion.failed = true

Beispiel für eine Fehlerantwort

{
  "fault": {
    "faultstring": "GenerateSAMLAssertion[GenSAMLAssert]: Invalid media type",
    "detail": {
      "errorcode": "steps.saml.generate.InvalidMediaTpe"
    }
  }
}

Beispiel für eine Fehlerregel

<FaultRules>
    <FaultRule name="invalid_saml_rule">
        <Step>
            <Name>invalid-saml</Name>
        </Step>
        <Condition>(GenerateSAMLAssertion.failed = "true")</Condition>
    </FaultRule>
</FaultRules>

Weitere Informationen

Variablen extrahieren: Richtlinie zum Extrahieren von Variablen