Règles SAMLAssertion

<ph type="x-smartling-placeholder"></ph> Vous consultez la documentation Apigee Edge.
Accédez à la page Documentation sur Apigee X. En savoir plus

Quoi

• Authentification et autorisation entrantes : valider la règle SAMLAssertion
  Le type de règle SAML 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.
• Génération de jetons sortants : générer une règle SAMLAssertion
  Le type de règle SAML 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.

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

<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

Générer une assertion SAML

Valider une assertion SAML

Remarques sur l'utilisation

La spécification SAML (Security Assertion Markup Language) définit les formats et les protocoles permettant aux applications d'échanger des informations au format XML pour l'authentification et l'autorisation.

Une "assertion de sécurité" est un jeton de confiance qui décrit un attribut d'une application, d'un utilisateur de l'application ou d'un autre participant à une transaction. Les assertions de sécurité sont gérées et utilisées par deux types d'entités :

• Fournisseurs d'identité : générer des assertions de sécurité pour le compte des participants
• Fournisseurs de services : valider les assertions de sécurité via des relations de confiance avec les fournisseurs d'identité

La plate-forme d'API peut agir en tant que fournisseur d'identité et en tant que fournisseur de services. Elle agit comme fournisseur d'identité en générant des assertions et en les associant aux messages de requête, ce qui les rend disponibles pour traitement par les services de backend. Elle agit en tant que fournisseur de services en validant les assertions sur les messages de requête entrants.

La règle de type SAML accepte les assertions SAML correspondant à la version 2.0 de la spécification SAML Core et à la version 1.0 de la spécification de profil de jeton SAML WS-Security.

Générer une assertion SAML

Traitement des règles :

1. Si le message n'est pas au format XML et que le paramètre IgnoreContentType n'est pas défini sur true, une erreur est générée.
2. Si le champ "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.
3. Si le champ "Template" (Modèle) n'est pas défini, créez une assertion qui inclut les valeurs des paramètres "Subject" et "Issuer", ou leurs références.
4. Signez l'assertion à l'aide de la clé spécifiée.
5. Ajoutez l'assertion au message sur le chemin XPath spécifié.

Valider une assertion SAML

Traitement des règles :

1. La règle vérifie le message entrant pour s'assurer que le type de support de la demande est XML, par vérifier si le type de contenu correspond aux formats text/(.*+)?xml ou application/(.*+)?xml Si le type de support n'est pas XML et <IgnoreContentType> n'est pas défini, la règle génère une erreur.
2. La règle analyse le fichier XML. Si l'analyse échoue, une erreur est générée.
3. La règle extrait l'élément signé et l'assertion à l'aide des chemins XPath correspondants. spécifiées (<SignedElementXPath> et <AssertionXPath>). Si l'un de ces chemins ne renvoie pas d'élément, la règle génère une erreur.
4. La règle vérifiera que l'assertion est identique à l'élément signé, ou est un enfant de l'élément signé. Si ce n'est pas le cas, la règle génère une erreur.
5. Si <NotBefore> ou <NotOnOrAfter> sont présents dans l'assertion, la stratégie vérifie le code temporel actuel par rapport ces valeurs, comme indiqué dans la section 2.5.1 de SAML Core.
6. Elles s'appliqueront à toute règle supplémentaire pour traiter les "Conditions". tel que décrit dans la section 2.5.1.1 de SAML Core.
7. La règle valide la signature numérique XML à l'aide des valeurs <TrustStore> et <ValidateSigner> comme décrit 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.

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 de panne définies par Edge 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.

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.

Exemple de réponse d'erreur

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