ValidateSAMLAssertion policy

Policy estensibile

Questa pagina si applica ad Apigee e Apigee hybrid.

Visualizza la documentazione di Apigee Edge.

Il criterio ValidateSAMLAssertion consente ai proxy API di convalidare le asserzioni SAML allegate alle richieste SOAP in entrata. La policy SAML convalida i messaggi in entrata che contengono un'asserzione SAML con firma digitale, li rifiuta se non sono validi e imposta variabili che consentono a policy aggiuntive o ai servizi di backend stessi di convalidare ulteriormente le informazioni nell'asserzione. Per saperne di più, consulta la panoramica delle norme SAML.

Queste norme sono estendibili e il loro utilizzo potrebbe avere implicazioni in termini di costi o utilizzo, a seconda della licenza Apigee. Per informazioni sui tipi di policy e sulle implicazioni di utilizzo, consulta Tipi di policy.

Esempi

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

Riferimento elemento

Convalida l'asserzione SAML

Nome campo	Descrizione
Attributo name	Il nome dell'istanza del criterio. Il nome deve essere univoco nell'organizzazione. I caratteri che puoi utilizzare nel nome sono limitati a: A-Z0-9._\-$ %. Tuttavia, la UI di Apigee applica ulteriori limitazioni, ad esempio la rimozione automatica dei caratteri non alfanumerici.
Attributo ignoreContentType	Un valore booleano che può essere impostato su true o false. Per impostazione predefinita, l'asserzione non verrà convalidata se il tipo di contenuto del messaggio non è un Content-Type XML. Se questo valore è impostato su true, il messaggio verrà trattato come XML indipendentemente dal tipo di contenuto.
Source	La destinazione della policy. I valori validi sono message, request e response. Se impostato su message, il criterio recupera in modo condizionale l'oggetto del messaggio in base al punto di collegamento del criterio. Se collegata al flusso di richiesta, la norma risolve message in request, mentre se collegata al flusso di risposta, la norma risolve message in response.
XPath	Deprecato. Figlio di Source. Utilizza AssertionXPath e SignedElementXPath.
AssertionXPath	Figlio di Source. Un'espressione XPath che indica l'elemento del documento XML in entrata da cui il criterio può estrarre l'asserzione SAML.
SignedElementXPath	Figlio di Source. Un'espressione XPath che indica l'elemento del documento XML in entrata da cui il criterio può estrarre l'elemento firmato. Questo può essere diverso o uguale all'XPath per AssertionXPath.
TrustStore	Il nome dell'archivio attendibilità contenente i certificati X.509 attendibili utilizzati per convalidare le firme digitali nelle asserzioni SAML.
RemoveAssertion	Un valore booleano che può essere impostato su true o false. Quando true, l'asserzione SAML verrà rimossa dal messaggio di richiesta prima che il messaggio venga inoltrato al servizio di backend.

Note sull'utilizzo

Elaborazione delle norme:

1. Il criterio controlla il messaggio in entrata per verificare che il tipo di media della richiesta sia XML, controllando se il tipo di contenuti corrisponde ai formati text/(.*+)?xml o application/(.*+)?xml. Se il tipo di media non è XML e l'attributo ignoreContentType non è impostato su true, la policy genererà un errore.
2. Il criterio analizzerà il file XML. Se l'analisi non riesce, viene generato un errore.
3. Il criterio estrae l'elemento firmato e l'asserzione utilizzando i rispettivi XPath specificati (<SignedElementXPath> e <AssertionXPath>). Se uno di questi percorsi non restituisce un elemento, il criterio genera un errore.
4. I criteri verificheranno che l'asserzione sia uguale all'elemento firmato o sia un elemento secondario dell'elemento firmato. Se non è vero, il criterio genererà un errore.
5. Se uno dei due elementi <NotBefore> o <NotOnOrAfter> è presente nell'asserzione, il criterio controllerà il timestamp corrente rispetto a questi valori, come descritto nella sezione 2.5.1 di SAML Core.
6. Il criterio applicherà eventuali regole aggiuntive per il trattamento delle "Condizioni" come descritto nella sezione 2.5.1.1 di SAML Core.
7. Il criterio convalida la firma digitale XML utilizzando il valore dell'archivio di attendibilità (<TrustStore>) descritto sopra. Se la convalida non va a buon fine, le norme generano un errore.

Una volta completata la policy senza generare un errore, lo sviluppatore del proxy può essere certo di quanto segue:

• La firma digitale nell'asserzione è valida ed è stata firmata da una CA attendibile
• L'asserzione è valida per il periodo di tempo corrente
• Il soggetto e l'emittente dell'asserzione verranno estratti e impostati nelle variabili di flusso. È responsabilità di altre policy utilizzare questi valori per l'autenticazione aggiuntiva, ad esempio verificare che il nome del soggetto sia valido o passarlo a un sistema di destinazione per la convalida.

Per una convalida più complessa, possono essere utilizzati altri criteri, come ExtractVariables, per analizzare l'XML non elaborato dell'asserzione.

Variabili di flusso

In un'asserzione SAML possono essere specificate molte informazioni. L'asserzione SAML stessa è un XML che può essere analizzato utilizzando il criterio ExtractVariables e altri meccanismi per implementare convalide più complesse.

Variabile	Descrizione
saml.id	L'ID asserzione SAML
saml.issuer	L'"emittente" dell'asserzione, convertita dal tipo XML nativo a una stringa
saml.subject	Il "Soggetto" dell'asserzione, convertito dal tipo XML nativo a una stringa
saml.valid	Restituisce true o false in base al risultato del controllo di validità
saml.issueInstant	IssueInstant
saml.subjectFormat	Formato dell'oggetto
saml.scmethod	Metodo di conferma del soggetto
saml.scdaddress	Indirizzo dei dati di conferma del soggetto
saml.scdinresponse	Dati di conferma del soggetto nella risposta
saml.scdrcpt	Destinatario dei dati di conferma del soggetto
saml.authnSnooa	AuthnStatement SessionNotOnOrAfter
saml.authnContextClassRef	AuthnStatement AuthnContextClassRef
saml.authnInstant	AuthnStatement AuthInstant
saml.authnSessionIndex	Indice sessione AuthnStatement

Messaggi di errore

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.

Tip: Need help resolving an error? Click in the Fix column for detailed troubleshooting information.

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>

Argomenti correlati

Estrazione delle variabili: Extract Variables policy