GenerateSAMLAssertion-Richtlinie

Erweiterbare Richtlinie

Diese Seite gilt für Apigee und Apigee Hybrid.

Apigee Edge-Dokumentation aufrufen

Mit der GenerateSAMLAssertion-Richtlinie können API-Proxys SAML-Assertions an ausgehende XML-Anfragen anhängen. Diese Assertions stehen dann Back-End-Diensten zur Verfügung, um die zusätzliche Sicherheitsverarbeitung für die Authentifizierung und Autorisierung anzuwenden. Weitere Informationen finden Sie unter Übersicht über SAML-Richtlinien.

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

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

Elementverweis

In diesem Abschnitt werden die Elemente und Attribute der GenerateSAMLAssertion-Richtlinie aufgeführt.

Attribute, die auf das oberste Element angewendet werden

<GenerateSAMLAssertion name="SAML-A1" continueOnError="false" enabled="true" async="false">

Die folgenden Attribute gelten für alle übergeordneten Richtlinienelemente.

Attribut	Beschreibung	Standard	Präsenz
Name	Der interne Name der Richtlinie. 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. Optional können Sie das Element `<displayname></displayname>` verwenden, um die Richtlinie im Proxy-Editor der Apigee-Benutzeroberfläche mit einem anderen Namen in der natürlichen Sprache zu versehen.	–	Erforderlich
aktiviert	Legen Sie `true` fest, um die Richtlinie zu erzwingen. Legen Sie `false` fest, um die Richtlinie zu "deaktivieren". Die Richtlinie wird nicht erzwungen, selbst wenn sie mit einem Ablauf verknüpft ist.	true	Optional

Elemente und Attribute für die Generierung von SAML-Assertions

Feldname	Beschreibung
Attribut `ignoreContentType`	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`	Gibt an, wo die generierte SAML-Assertion platziert wird. Die Assertion kann in einer Ablaufvariablen gespeichert oder in eine vorhandene Nachricht eingefügt werden.
`FlowVariable`	Gibt den Namen der Ablaufvariablen an, in der der generierte SAML-Assertion-Inhalt gespeichert wird. Dies ist eine Alternative zur Verwendung des Elements `<Message>`, um die Assertion in eine vorhandene XML-Nachricht einzufügen.
`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 `ref` Attribut vorhanden ist, wird der Wert von "Subject" zur Laufzeit auf der Grundlage der angegebenen Variable zugewiesen. Wenn das optionale `ref` Attribut nicht 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 AssignMessage-Richtlinie. 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.

Verwendungshinweise

Richtlinienverarbeitung:

Wenn die Nachricht nicht XML ist und ignoreContentType nicht auf true gesetzt ist, dann wird ein Fehler ausgelöst.
Wenn Template 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 Template 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.

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

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