Règle ValidateSAMLAssertion

Règle extensible

Cette page s'applique à Apigee et à Apigee hybrid.

Consultez la documentation d' Apigee Edge.

La règle ValidateSAMLAssertion permet aux proxys d'API de valider les assertions SAML associées aux requêtes SOAP entrantes. La règle SAML valide les messages entrants contenant une assertion SAML signée numériquement, les rejette s'ils ne sont pas valides et définit des variables autorisant des règles supplémentaires, ou les services de backend, à valider davantage les informations dans l'assertion. Pour en savoir plus, consultez Présentation des règles SAML.

Cette règle est une règle extensible et son utilisation peut avoir des conséquences sur le coût ou l'utilisation, en fonction de votre licence Apigee. Pour en savoir plus sur les types de règles et les implications en termes d'utilisation, consultez la section Types de règles.

Exemples

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

Documentation de référence des éléments

Valider une assertion SAML

Nom du champ	Description
Attribut `name`	Nom de l'instance de règle. Le nom doit être unique au sein de l'organisation. Les caractères que vous pouvez utiliser dans le nom se limitent à : `A-Z0-9._\-$ %`. L'UI Apigee applique cependant des restrictions supplémentaires, telles que la suppression automatique des caractères non alphanumériques.
Attribut `ignoreContentType`	Valeur booléenne pouvant être définie sur `true` ou `false`. Par défaut, l'assertion n'est pas validée si le type de contenu du message n'est pas un type de contenu XML. Si cet attribut est défini sur `true`, le message est traité au format XML indépendamment du type de contenu.
`Source`	Cible de la règle. Les valeurs valides sont `message`, `request` et `response`. Lorsque ce champ est défini sur `message`, la règle récupère l'objet du message de manière conditionnelle en fonction de son point de rattachement. Lorsqu'elle est associée au flux de requête, la règle évalue `message` en `request` et, lorsqu'elle est associée au flux de réponse, la stratégie évalue `message` en `response`.
`XPath`	Obsolète. Enfant de `Source`. Utiliser `AssertionXPath` et `SignedElementXPath`.
`AssertionXPath`	Enfant de `Source`. Expression XPath indiquant l'élément du document XML entrant à partir duquel la règle peut extraire l'assertion SAML.
`SignedElementXPath`	Enfant de `Source`. Expression XPath indiquant l'élément du document XML entrant à partir duquel la règle peut extraire l'élément signé. Cette valeur peut être différente ou non de la valeur XPath de `AssertionXPath`.
`TrustStore`	Nom du truststore contenant les certificats X.509 approuvés pour valider les signatures numériques sur les assertions SAML.
`RemoveAssertion`	Valeur booléenne pouvant être définie sur `true` ou `false`. Si elle définie sur `true`, l'assertion SAML est supprimée du message de la requête avant que le message soit transféré au service de backend.

Remarques sur l'utilisation

Traitement des règles :

La règle vérifie le message entrant pour vérifier que le média de la requête est de type XML, en vérifiant si le type de contenu correspond aux formats text/(.*+)?xml ou application/(.*+)?xml. Si le contenu n'est pas de type XML et que l'attribut ignoreContentType n'est pas défini sur true, la règle génère une erreur.
La règle analyse le fichier XML. Si l'analyse échoue, une erreur est générée.
La règle extrait l'élément signé et l'assertion, en utilisant les XPaths respectifs spécifiés (<SignedElementXPath> et <AssertionXPath>). Si l'un de ces chemins ne renvoie pas d'élément, la règle génère une erreur.
La règle vérifie que l'assertion est identique à l'élément signé ou qu'elle est un enfant de l'élément signé. Si ce n'est pas le cas, la règle génère une erreur.
Si l'un des éléments <NotBefore> ou <NotOnOrAfter> est présent dans l'assertion, la règle vérifie le code temporel actuel par rapport à ces valeurs, comme décrit dans la section 2.5.1 du document SAML Core.
Elle appliquera toutes les règles supplémentaires pour le traitement des "Conditions", comme décrit dans la section 2.5.1.1 du document SAML Core.
La règle valide la signature numérique XML à l'aide de la valeur du truststore (<TrustStore>) décrite ci-dessus. Si la validation échoue, la règle génère une erreur.

Une fois la règle appliquée sans générer d'erreur, le développeur du proxy peut s'assurer des points suivants :

La signature numérique de la déclaration est valide et a été signée par une autorité de certification de confiance.
L'assertion est valide pour la période en cours.
L'objet et l'émetteur de l'assertion sont extraits et définis dans des variables de flux. Il est de la responsabilité des autres règles d'utiliser ces valeurs pour une authentification supplémentaire, par exemple pour vérifier que le nom de l'objet est valide ou qu'il est transmis à un système cible pour validation.

D'autres règles, telles que ExtractVariables, peuvent être utilisées pour analyser le code XML brut de l'assertion pour une validation plus complexe.

Variables de flux

De nombreuses informations peuvent être spécifiées dans une assertion SAML. L'assertion SAML elle-même est un fichier XML pouvant être analysé à l'aide de la règle ExtractVariables et d'autres mécanismes afin de mettre en œuvre des validations plus complexes.

Variable	Description
`saml.id`	ID d'assertion SAML
`saml.issuer`	Émetteur de l'assertion, converti de son type XML natif en chaîne
`saml.subject`	Objet de l'assertion, converti de son type XML natif en chaîne
`saml.valid`	Renvoie "true" ou "false" en fonction du résultat de la vérification de validité
`saml.issueInstant`	IssueInstant
`saml.subjectFormat`	Format de l'objet
`saml.scmethod`	Méthode de confirmation de l'objet
`saml.scdaddress`	Adresse de données de confirmation de l'objet
`saml.scdinresponse`	Données de confirmation de l'objet en réponse
`saml.scdrcpt`	Destinataire des données de confirmation de l'objet
`saml.authnSnooa`	Authentification SessionNotOnOrAfter
`saml.authnContextClassRef`	AuthnStatement AuthnContextClassRef
`saml.authnInstant`	AuthnStatement AuthInstant
`saml.authnSessionIndex`	Index de session AuthnStatement

Informations de référence sur les erreurs

Cette section décrit les codes d'erreur et les messages d'erreur renvoyés et les variables d'erreur définies par Apigee lorsque cette règle déclenche une erreur. Ces informations sont importantes si vous développez des règles de défaillance afin de gérer les pannes. Pour en savoir plus, consultez les pages Ce que vous devez savoir à propos des erreurs liées aux règles et Gérer les pannes.

Erreurs de déploiement

Ces erreurs peuvent se produire lorsque vous déployez un proxy contenant cette règle.

Nom de l'erreur	Cause	Corriger
`SourceNotConfigured`	Un ou plusieurs des éléments suivants de la règle `ValidateSAMLAssertion` ne sont pas définis ou sont vides : `<Source>`, `<XPath>`, `<Namespaces>`, `<Namespace>`.
`TrustStoreNotConfigured`	Si l'élément `<TrustStore>` est vide ou non spécifié dans la règle `ValidateSAMLAssertion`, le déploiement du proxy d'API échoue. Vous devez indiquer un truststore valide.
`NullKeyStoreAlias`	Si l'élément enfant `<Alias>` est vide ou non spécifié dans l'élément `<Keystore>` de la règle `GenerateSAMLAssertion`, le déploiement du proxy d'API échoue. Vous devez saisir un alias de keystore valide.
`NullKeyStore`	Si l'élément enfant `<Name>` est vide ou non spécifié dans l'élément `<Keystore>` de la règle `GenerateSAMLAssertion`, le déploiement du proxy d'API échoue. Veuillez indiquer un nom de keystore valide.
`NullIssuer`	Si l'élément `<Issuer>` est vide ou non spécifié dans la règle `GenerateSAMLAssertion`, le déploiement du proxy d'API échoue. Vous devez saisir une valeur `<Issuer>` valide.

Variables de panne

Ces variables sont définies lorsqu'une erreur d'exécution se produit. Pour en savoir plus, consultez la section Ce que vous devez savoir sur les erreurs liées aux règles.

Variables	Lieu	Exemple
`fault.name="fault_name"`	`fault_name` est le nom de l'erreur . Le nom d'erreur est la dernière partie du code d'erreur.	`fault.name = "InvalidMediaTpe"`
`GenerateSAMLAssertion.failed`	Pour une configuration de règle d'assertion SAML valide, le préfixe d'erreur est `ValidateSAMLAssertion`.	`GenerateSAMLAssertion.failed = true`

Exemple de réponse d'erreur

Remarque : Pour le traitement des erreurs, la meilleure pratique consiste à intercepter la partie errorcode de la réponse. Ne vous fiez pas au texte dans faultstring, car il pourrait changer.

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

Exemple de règle de défaillance

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

Articles associés

Extraction de variables : règle d'extraction de variables

Règle ValidateSAMLAssertion Restez organisé à l'aide des collections Enregistrez et classez les contenus selon vos préférences.

Exemples

Documentation de référence des éléments

Valider une assertion SAML

Remarques sur l'utilisation

Variables de flux

Informations de référence sur les erreurs

Erreurs de déploiement

Variables de panne

Exemple de réponse d'erreur

Exemple de règle de défaillance

Articles associés

Règle ValidateSAMLAssertion