ValidateSAMLAssertion policy

Policy estensibile

Questa pagina si applica ad Apigee e Apigee hybrid.

Visualizza Apigee Edge documentazione.

La policy 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 le variabili che consentono ad altre policy o ai servizi di backend stessi di convalidare ulteriormente le informazioni nell'asserzione. Per saperne di più, consulta la panoramica delle policy SAML.

Questa policy è una policy estensibile e il suo utilizzo potrebbe comportare costi o implicazioni di 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 della policy. Il nome deve essere univoco nell'organizzazione. I caratteri che puoi utilizzare nel nome sono limitati a: A-Z0-9._\-$ %. Tuttavia, l'interfaccia utente di Apigee applica ulteriori restrizioni, 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 tipo di contenuto 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 impostata su message, la policy recupera in modo condizionale l'oggetto del messaggio in base al punto di collegamento della policy. Se collegata al flusso della richiesta, la policy risolve message in request e, se collegata al flusso della risposta, la policy risolve message in response.
XPath
Obsoleta. Elemento secondario di Source. Utilizza AssertionXPath e SignedElementXPath.
AssertionXPath
Elemento secondario di Source. Un'espressione XPath che indica l'elemento nel documento XML in entrata da cui la policy può estrarre l'asserzione SAML.
SignedElementXPath
Elemento secondario di Source. Un'espressione XPath che indica l'elemento nel documento XML in entrata da cui la policy può estrarre l'elemento firmato. Questo può essere diverso o uguale al percorso XPath per il AssertionXPath.
TrustStore
Il nome dell'archivio attendibilità che contiene i certificati X.509 attendibili utilizzati per convalidare le firme digitali sulle asserzioni SAML.
RemoveAssertion
Un valore booleano che può essere impostato su true o false. Se 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 policy:

  1. La policy controlla il messaggio in entrata per verificare che il tipo di supporto della richiesta sia XML, controllando se il tipo di contenuto corrisponde ai formati text/(.*+)?xml o application/(.*+)?xml. Se il tipo di supporto non è XML e l' ignoreContentType attributo non è impostato su true, la policy genererà un errore.
  2. La policy analizzerà il codice XML. Se l'analisi non riesce, verrà generato un errore.
  3. La policy estrarrà l'elemento firmato e l'asserzione utilizzando i rispettivi percorsi XPath specificati (<SignedElementXPath> e <AssertionXPath>). Se uno di questi percorsi non restituisce un elemento, la policy genererà un errore.
  4. La policy verificherà che l'asserzione sia uguale all'elemento firmato o sia un elemento secondario dell'elemento firmato. In caso contrario, la policy genererà un errore.
  5. Se uno degli elementi <NotBefore> o <NotOnOrAfter> è presente nell'asserzione, la policy controllerà il timestamp corrente rispetto a questi valori, come descritto nella sezione 2.5.1 di SAML Core.
  6. La policy applicherà eventuali regole aggiuntive per l'elaborazione delle "Condizioni" come descritto in SAML Core sezione 2.5.1.1.
  7. La policy convalida la firma digitale XML utilizzando il valore dell'archivio di attendibilità (<TrustStore>) descritto sopra. Se la convalida non riesce, la policy genera un errore.

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

  • La firma digitale sull'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.

Altre policy, come ExtractVariables, possono essere utilizzate per analizzare il codice XML non elaborato dell'asserzione per una convalida più complessa.

Variabili di flusso

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

Variabile Descrizione
saml.id L'ID dell'asserzione SAML
saml.issuer L'"emittente" dell'asserzione, convertito 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 del soggetto
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 della sessione AuthnStatement

Messaggi di errore

Questa sezione descrive i codici di errore e i messaggi di errore restituiti nonché le variabili di errore impostate da Apigee quando questo criterio attiva un errore. Queste informazioni sono importanti se stai sviluppando regole di errore per gestire gli errori. Per scoprire di più, consulta Informazioni importanti sugli errori relativi alle norme e Gestione degli errori.

Errori di deployment

Questi errori possono verificarsi quando esegui il deployment di un proxy contenente questo criterio.

Nome dell'errore Causa Correggi
SourceNotConfigured Uno o più dei seguenti elementi del criterio ValidateSAMLAssertion non sono definiti o sono vuoti: <Source>, <XPath>, <Namespaces>, <Namespace>.
TrustStoreNotConfigured Se l'elemento <TrustStore> è vuoto o non specificato nel criterio ValidateSAMLAssertion, il deployment del proxy API non va a buon fine. È necessario un truststore valido.
NullKeyStoreAlias Se l'elemento figlio <Alias> è vuoto o non specificato nell'elemento <Keystore> del criterio GenerateSAMLAssertion, il deployment del proxy dell'API non va a buon fine. È necessario un alias del keystore valido.
NullKeyStore Se l'elemento figlio <Name> è vuoto o non specificato nell'elemento <Keystore> del criterio GenerateSAMLAssertion, il deployment del proxy dell'API non va a buon fine. È necessario un nome del keystore valido.
NullIssuer Se l'elemento <Issuer> è vuoto o non specificato nel criterio GenerateSAMLAssertion, il deployment del proxy API non va a buon fine. È obbligatorio un valore <Issuer> valido.

Variabili di errore

Queste variabili vengono impostate quando si verifica un errore di runtime. Per ulteriori informazioni, consulta Informazioni importanti sugli errori relativi alle norme.

Variabili Dove Esempio
fault.name="fault_name" fault_name è il nome dell'errore. Il nome dell'errore è l'ultima parte del codice dell'errore. fault.name = "InvalidMediaTpe"
GenerateSAMLAssertion.failed Per una configurazione del criterio di asserzione SAML convalidata, il prefisso dell'errore è ValidateSAMLAssertion. GenerateSAMLAssertion.failed = true

Esempio di risposta di errore

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

Esempio di regola di errore

<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