Règle GenerateSAMLAssertion

Règle extensible

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

Consultez la documentation d' Apigee Edge.

La règle GenerateSAMLAssertion permet aux proxys d'API d'associer des assertions SAML aux requêtes XML sortantes. Ces assertions sont ensuite mises à disposition pour permettre aux services de backend d'appliquer un traitement de sécurité supplémentaire pour l'authentification et l'autorisation. 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

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

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

Cette section liste les éléments et les attributs de la règle GenerateSAMLAssertion.

Attributs qui s'appliquent à l'élément de premier niveau

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

Les attributs suivants sont communs à tous les éléments parents de la stratégie.

Attribut	Description	Par défaut	Présence
nom	Nom interne de la stratégie. Les caractères que vous pouvez utiliser dans le nom se limitent à : `A-Z0-9._\-$ %`. L'interface utilisateur Apigee applique cependant des restrictions supplémentaires, telles que la suppression automatique des caractères qui ne sont pas alphanumériques. Vous pouvez également utiliser l'élément `<displayname></displayname>` pour ajouter un libellé à la règle dans l'éditeur de proxy de l'interface utilisateur d'Apigee, en utilisant un nom différent, en langage naturel.	N/A	Obligatoire
activé	Définissez la valeur sur `true` pour appliquer la stratégie. Définissez la valeur sur `false` pour "désactiver" la stratégie. La stratégie ne sera pas appliquée même si elle reste associée à un flux.	vrai	Facultatif

Éléments et attributs pour la génération d'assertions SAML

Nom du champ	Description
Attribut `ignoreContentType`	Valeur booléenne pouvant être définie sur `true` ou `false`. Par défaut, l'assertion n'est pas généré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.
`Issuer`	Identifiant unique du fournisseur d'identité. Si l'attribut facultatif `ref` est présent, la valeur de l'émetteur est attribuée au moment de l'exécution en fonction de la variable spécifiée. Si l'attribut facultatif `ref` n'est pas présent, la valeur de l'émetteur est utilisée.
`KeyStore`	Nom du keystore contenant la clé privée et l'alias de la clé privée utilisée pour signer numériquement les assertions SAML.
`OutputVariable`	Indique où l'assertion SAML générée sera placée. L'assertion peut être stockée dans une variable de flux ou insérée dans un message existant.
`FlowVariable`	Spécifie le nom de la variable de flux dans laquelle le contenu de l'assertion SAML générée sera stocké. Il s'agit d'une alternative à l'utilisation de l'élément `<Message>` pour insérer l'assertion dans un message XML existant.
`Message`	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 résout `message` pour la requête et, lorsqu'elle est associée au flux de réponse, la stratégie résout `message` en réponse.
`XPath`	Expression XPath qui indique l'élément du document XML sortant auquel la règle va associer l'assertion SAML.
`SignatureAlgorithm`	SHA1 ou SHA256
`Subject`	Identifiant unique de l'objet de l'assertion SAML. Si l'attribut facultatif `ref` est présent, la valeur du champ "Subject" est attribuée au moment de l'exécution en fonction de la variable spécifiée. Si l'attribut facultatif `ref` n'est pas présent, la valeur de "Subject" est utilisée.
`Template`	Si elle est présente, l'assertion sera générée en exécutant ce modèle, en remplaçant tout ce qui désigne `{}` par la variable correspondante, puis en signant numériquement le résultat. Le modèle est traité conformément au contenu de la règle AssignMessage. Consultez la section sur la règle AssignMessage. L'élément `<Template>` accepte la fonctionnalité de substitution de chaîne dynamique appelée modélisation de messages. La modélisation de messages n'est acceptée que lorsque la signature de la règle est `GenerateSamlAssertion`.

Remarques sur l'utilisation

Traitement des règles :

Si le message n'est pas au format XML et que ignoreContentType n'est pas défini sur true, une erreur est générée.
Si Template est défini, le modèle est traité comme décrit dans la règle AssignMessage. Si des variables sont manquantes et que ignoreUnresolvedVariables n'est pas défini, une erreur est générée.
Si Template n'est pas défini, créez une assertion qui inclut les valeurs des paramètres "Subject" et "Issuer", ou leurs références.
Signez l'assertion à l'aide de la clé spécifiée.
Ajoutez l'assertion au message sur le chemin XPath spécifié.

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