SAMLAssertion-Richtlinien

Diese Seite gilt für Apigee und Apigee Hybrid.

Apigee Edge-Dokumentation aufrufen

Was

Eingehende Authentifizierung und Autorisierung: Validieren Sie die SAML-Assertion-Richtlinie
Wenn Sie den SAML-Richtlinientyp verwenden, können API-Proxys SAML-Assertions validieren, die an eingehende ESP-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.
Generierung ausgehender Tokens: SAML-Assertion-Richtlinie generieren
Mit dem SAML-Richtlinientyp können API-Proxys SAML-Assertions an ausgehende XML-Anfragen anhängen. Diese Assertions stehen dann zur Verfügung, damit Backend-Dienste die zusätzliche Sicherheitsverarbeitung für die Authentifizierung und Autorisierung anwenden können.

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

Beispiele

SAML-Assertion generieren

<GenerateSAMLAssertion name="SAML" ignoreContentType="false">
  <CanonicalizationAlgorithm />
  <Issuer ref="reference">Issuer name</Issuer>
  <KeyStore>
    <Name ref="reference">keystorename</Name>
    <Alias ref="reference">alias</Alias>
  </KeyStore>
  <OutputVariable>
    <FlowVariable>assertion.content</FlowVariable>
    <Message 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>
      </Namespaces>
      <XPath>/soap:Envelope/soap:Header/wsse:Security</XPath>
    </Message>
  </OutputVariable>
  <SignatureAlgorithm />
  <Subject ref="reference">Subject name</Subject>
  <Template ignoreUnresolvedVariables="false">
    <!-- A lot of XML goes here, within CDATA, with {} around
         each variable -->
  </Template>
</GenerateSAMLAssertion>

Eine SAML-Assertion generieren

SAML-Assertion validieren

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

Eine SAML-Assertion validieren

Elementverweis

SAML-Assertion generieren

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 generiert, 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.
`Issuer`	Die eindeutige Kennung des Identitätsanbieters. Wenn das optionale Attribut `ref` vorhanden ist, wird der Wert des Ausstellers zur Laufzeit auf der Grundlage der angegebenen Variable zugewiesen. Wenn das optionale Attribut `ref` nicht vorhanden ist, wird der Wert des Ausstellers verwendet.
`KeyStore`	Der Name des KeyStore, der den privaten Schlüssel und den Alias des privaten Schlüssels enthält, mit dem SAML-Assertions signiert werden können.
`OutputVariable`
`FlowVariable`
`Message`	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 Anfragefluss angehängt wird, wird `message` in die Anfrage aufgelöst. Wenn sie an den Antwortablauf angehängt wird, löst die Richtlinie `message` als Antwort auf.
`XPath`	Ein XPath-Ausdruck, der das Element im ausgehenden XML-Dokument angibt, an das die Richtlinie die SAML-Assertion anhängen.
`SignatureAlgorithm`	SHA1 oder SHA256
`Subject`	Die eindeutige ID des Themas der SAML-Assertion. Wenn das optionale Attribut `ref` vorhanden ist, wird der Wert von "Subject" zur Laufzeit auf der Grundlage der angegebenen Variable zugewiesen. Wenn das optionale Attribut `ref` vorhanden ist, wird der Wert von "Subject" verwendet.
`Template`	Wenn die Assertion vorhanden ist, wird die Assertion generiert. Dazu wird die Vorlage mit `{}` ersetzt, wobei alle Werte mit der entsprechenden Variable ersetzt werden und das Ergebnis anschließend digital signiert wird. Die Vorlage wird gemäß den AssignMessage-Richtlinienregeln verarbeitet. Siehe Nachricht zuweisen. Das Element `<Template>` unterstützt die Funktion zur dynamischen Stringersetzung, die als Nachrichtenvorlage bezeichnet wird. Die Nachrichtenvorlagen werden nur unterstützt, wenn die Richtliniensignatur `GenerateSamlAssertion` lautet.

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 generiert, 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

Die Spezifikation für die Security Assertion Markup Language (SAML) definiert Formate und Protokolle, mit denen Anwendungen XML-formatierte Informationen für die Authentifizierung und Autorisierung austauschen können.

Eine "Sicherheitsassertion" ist ein vertrauenswürdiges Token, das ein Attribut einer App, eines App-Nutzers oder eines anderen Teilnehmers einer Transaktion beschreibt. Sicherheitsassertions werden von zwei Arten von Entitäten verwaltet und verbraucht:

Identitätsanbieter: Sicherheitsbewertungen im Namen der Teilnehmer generieren
Dienstanbieter: Assertions über vertrauenswürdige Beziehungen mit Identitätsanbietern validieren

Die API-Plattform kann als Identitätsanbieter und als Dienstanbieter fungieren. Es fungiert als Identitätsanbieter, indem Assertions generiert und an Anfragen angefügt werden, um diese Assertions zur Verarbeitung durch Back-End-Dienste verfügbar zu machen. Sie dient als Dienstanbieter, indem Assertions für eingehende Anfragenachrichten überprüft werden.

Der SAML-Richtlinientyp unterstützt SAML-Assertions, die mit Version 2.0 der SAML Core-Spezifikation und Version 1.0 der Profilspezifikation für das WS-Security SAML-Token-Profil übereinstimmen.

SAML-Assertion generieren

Richtlinienverarbeitung:

Wenn die Nachricht nicht XML ist und IgnoreContentType nicht auf true gesetzt ist, wird ein Fehler ausgelöst.
Wenn "Vorlage" festgelegt ist, verarbeiten Sie die Vorlage wie in der Richtlinie "AssignMessage" beschrieben. Wenn Variablen fehlen und "IgnoreUnresolvedVariables" nicht festgelegt ist, wird ein Fehler ausgegeben.
Wenn "Vorlage" nicht festgelegt ist, erstellen Sie eine Assertion, die die Werte der Parameter "Subject" und "Issuer" oder "Verweis" enthält.
Signieren Sie die Assertion mit dem angegebenen Schlüssel.
Fügen Sie der Assertion den angegebenen XPath hinzu.

SAML-Assertion validieren

Richtlinienverarbeitung:

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 <IgnoreContentType> nicht festgelegt ist, gibt die Richtlinie einen Fehler aus.
Die Richtlinie parst den XML. Wenn das Parsen fehlschlägt, wird ein Fehler ausgelöst.
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.
Die Richtlinie überprüft, ob die Assertion mit dem signierten Element übereinstimmt oder dem signierten Element untergeordnet ist. Wenn dies nicht der Fall ist, gibt die Richtlinie einen Fehler aus.
Wenn eines der Elemente <NotBefore> oder <NotOnOrAfter> in der Assertion vorhanden ist, prüft die Richtlinie den aktuellen Zeitstempel mit diesen Werten, wie im Abschnitt SAML 2.5.1 beschrieben.
Die Richtlinie wendet alle zusätzlichen Regeln zur Verarbeitung der „Bedingungen“ (siehe SAML Core Abschnitt 2.5.1.1) an.
Die Richtlinie validiert die digitale XML-Signatur mit den oben beschriebenen Werten von <TrustStore> und <ValidateSigner>. 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	Beheben
`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

Hinweis: Bei der Fehlerbehandlung besteht die Best Practice darin, den Teil errorcode der Fehlerantwort zu beachten. Verlassen Sie sich nicht auf den Text in faultstring. Er kann sich ändern.

{
  "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