Règles SAMLAssertion

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

Consultez la documentation d'Apigee Edge.

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.

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

Générer une assertion SAML

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

Générer une assertion SAML

Valider une assertion SAML

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

Valider une assertion SAML

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

Générer 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 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`
`FlowVariable`
`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` est 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`.

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

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 :

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.
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.
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.
Signez l'assertion à l'aide de la clé spécifiée.
Ajoutez l'assertion au message sur le chemin XPath spécifié.

Valider une assertion SAML

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 <IgnoreContentType> n'est pas défini, 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 des valeurs de <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.

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

This section describes the fault codes and error messages that are returned and fault variables that are set by Apigee when this policy triggers an error. This information is important to know if you are developing fault rules to handle faults. To learn more, see What you need to know about policy errors and Handling faults.

Deployment errors

These errors can occur when you deploy a proxy containing this policy.

Error name	Cause	Fix
`SourceNotConfigured`	One or more of the following elements of the `ValidateSAMLAssertion` policy is not defined or empty: `<Source>`, `<XPath>`, `<Namespaces>`, `<Namespace>`.
`TrustStoreNotConfigured`	If the `<TrustStore>` element is empty or not specified in the `ValidateSAMLAssertion` policy, then the deployment of the API proxy fails. A valid truststore is required.
`NullKeyStoreAlias`	If the child element `<Alias>` is empty or not specified in the `<Keystore>` element of `GenerateSAMLAssertion` policy, then the deployment of the API proxy fails. A valid keystore alias is required.
`NullKeyStore`	If the child element `<Name>` is empty or not specified in the `<Keystore>` element of `GenerateSAMLAssertion` policy, then the deployment of the API proxy fails. A valid keystore name is required.
`NullIssuer`	If the `<Issuer>` element is empty or not specified in the `GenerateSAMLAssertion` policy, then the deployment of the API proxy fails. A valid `<Issuer>` value is required.

Fault variables

These variables are set when a runtime error occurs. For more information, see What you need to know about policy errors.

Variables	Where	Example
`fault.name="fault_name"`	`fault_name` is the name of the fault. The fault name is the last part of the fault code.	`fault.name = "InvalidMediaTpe"`
`GenerateSAMLAssertion.failed`	For a validate SAML assertion policy configuration, the error prefix is `ValidateSAMLAssertion`.	`GenerateSAMLAssertion.failed = true`

Example error response

Note: For error handling, the best practice is to trap the errorcode part of the error response. Do not rely on the text in the faultstring, because it could change.

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

Example fault rule

<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