Sie sehen die Dokumentation zu Apigee Edge.
Zur Apigee X-Dokumentation weitere Informationen
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 prüft eingehende Nachrichten, die eine digital signierte SAML-Assertion enthalten, lehnt sie ab, wenn sie ungültig sind, und legt Variablen fest, die zusätzliche Richtlinien zulassen, oder legt die Back-End-Dienste selbst fest, um die Informationen in der Assertion weiter 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.
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="test">http://www.example.com/test</Namespace> </Namespaces> <XPath>/envelope/header</XPath> </Message> </OutputVariable> <SignatureAlgorithm /> <Subject ref="reference">Subject name</Subject> <Template ignoreUnresolvedVariables="false"> <!-- A lot of XML goes here, in 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 Verwaltungs-UI erzwingt jedoch zusätzliche Einschränkungen, z. B. werden nicht alphanumerische Zeichen automatisch entfernt. |
||
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 KeyStores, der den privaten Schlüssel und den Alias des privaten Schlüssels enthält, der zum digitalen Signieren von SAML-Assertions verwendet wird.
|
||
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.
|
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 Verwaltungs-UI erzwingt jedoch zusätzliche Einschränkungen, z. B. werden nicht alphanumerische Zeichen automatisch entfernt.
|
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 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 |
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. Dieser kann sich vom XPath für AssertionXPath unterscheiden oder mit ihm identisch sein.
|
TrustStore |
Der Name des TrustStores, der vertrauenswürdige X.509-Zertifikate enthält, mit denen digitale Signaturen in SAML-Assertions validiert werden.
|
RemoveAssertion |
Ein boolescher Wert, der auf
true oder false gesetzt werden kann. Beim 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. Als Identitätsanbieter generiert er Assertions, hängt sie an Anfragenachrichten an und stellt diese Assertions für die Verarbeitung durch Back-End-Dienste zur Verfügung. 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 prüft in der eingehenden Nachricht, ob der Medientyp der Anfrage XML ist. Dazu wird geprüft, ob der Inhaltstyp den Formaten
text/(.*+)?xml
oderapplication/(.*+)?xml
entspricht. Wenn der Medientyp nicht XML und<IgnoreContentType>
nicht festgelegt ist, löst 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 angegebenen 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 dem signierten Element entspricht oder ein untergeordnetes Element des signierten Elements ist. Wenn dies nicht wahr ist, löst die Richtlinie einen Fehler aus.
- Wenn in der Assertion entweder das Element
<NotBefore>
oder das Element<NotOnOrAfter>
vorhanden ist, gleicht die Richtlinie den aktuellen Zeitstempel mit diesen Werten ab, wie in Abschnitt 2.5.1 zu SAML Core beschrieben. - Die Richtlinie wendet alle zusätzlichen Regeln für die Verarbeitung der „Bedingungen“ an, wie im Abschnitt 2.5.1.1 zu SAML Core beschrieben.
- Die Richtlinie validiert die digitale XML-Signatur mit den Werten von
<TrustStore>
und<ValidateSigner>
wie oben beschrieben. Wenn die Validierung fehlschlägt, löst 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 Fehlercodes und Fehlermeldungen beschrieben, die zurückgegeben werden, sowie die Fehlervariablen, die von Edge festgelegt werden, wenn diese 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 bereitstellen, der diese Richtlinie enthält.
Fehlername | Ursache | Problembehebung |
---|---|---|
SourceNotConfigured |
Mindestens eines der folgenden Elemente der SAML-Assertion-Richtlinie validieren ist nicht definiert oder leer: <Source> , <XPath> , <Namespaces> , <Namespace> .
|
build |
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.
|
build |
NullKeyStoreAlias |
Wenn das untergeordnete Element <Alias> leer oder nicht im Element <Keystore> der SAML-Assertion-Richtlinie angegeben ist, schlägt die Bereitstellung des API-Proxys fehl. Ein gültiger Keystore-Alias ist erforderlich.
|
build |
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.
|
build |
NullIssuer |
Wenn das Element <Issuer> leer oder nicht in der Richtlinie "SAML-Assertion generieren" angegeben ist, schlägt die Bereitstellung des API-Proxys fehl. Bitte geben Sie einen gültigen <Issuer> -Wert ein.
|
build |
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