Criteri SAMLAssertion

Questa pagina si applica ad Apigee e Apigee hybrid.

Visualizza la documentazione di Apigee Edge.

icona delle norme

Cosa

  • Autenticazione e autorizzazione in entrata: convalida della policy SAML Assertion
    Il tipo di policy SAML 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.
  • Generazione di token in uscita: genera criteri di asserzione SAML
    Il tipo di criteri SAML consente ai proxy API di allegare asserzioni SAML alle richieste XML in uscita. Queste asserzioni sono quindi disponibili per consentire ai servizi di backend di applicare un ulteriore trattamento di sicurezza per l'autenticazione e l'autorizzazione.

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

Esempi

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

Generazione di un'asserzione SAML

Convalida dell'asserzione 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>

Convalida di un'asserzione SAML

Riferimento elemento

Genera 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à generata se il tipo di contenuto del messaggio non è un Content-Type XML. Se questa opzione è impostata su true, il messaggio verrà trattato come XML indipendentemente dal tipo di contenuti.
Issuer
L'identificatore univoco del provider di identità. Se è presente l'attributo facoltativo ref, il valore di Emittente verrà assegnato in fase di runtime in base alla variabile specificata. Se l'attributo facoltativo ref non è presente, verrà utilizzato il valore di Emittente.
KeyStore
Il nome dell'archivio chiavi contenente la chiave privata e l'alias della chiave privata utilizzata per firmare digitalmente le asserzioni SAML.
OutputVariable
FlowVariable
Message 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 collegato al flusso di richiesta, il criterio risolve message nella richiesta. Se collegato al flusso di risposta, il criterio risolve message nella risposta.
XPath Un'espressione XPath che indica l'elemento del documento XML in uscita a cui la norma collegherà l'asserzione SAML.
SignatureAlgorithm SHA1 o SHA256
Subject
L'identificatore univoco del soggetto dell'asserzione SAML. Se è presente l'attributo ref facoltativo, il valore di Subject verrà assegnato in fase di runtime in base alla variabile specificata. Se è presente l'attributo facoltativo ref, verrà utilizzato il valore di Oggetto.
Template
Se presente, l'asserzione verrà generata eseguendo questo modello, sostituendo tutto ciò che è indicato con {} con la variabile corrispondente e firmando digitalmente il risultato. Il modello viene elaborato seguendo le regole dei criteri AssignMessage. Consulta le norme AssignMessage.

Convalida dell'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à generata 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

La specifica SAML (Security Assertion Markup Language) definisce formati e protocolli che consentono alle applicazioni di scambiare informazioni in formato XML per l'autenticazione e l'autorizzazione.

Un'asserzione di sicurezza è un token attendibile che descrive un attributo di un'app, di un utente dell'app o di un altro partecipante a una transazione. Le asserzioni di sicurezza vengono gestite e utilizzate da due tipi di entità:

  • Provider di identità: generano asserzioni di sicurezza per conto dei partecipanti
  • Fornitori di servizi: convalidare le asserzioni di sicurezza tramite relazioni attendibili con i fornitori di identità

La piattaforma API può fungere da provider di identità e da fornitore di servizi. Funge da provider di identità generando asserzioni e allegandole ai messaggi di richiesta, rendendole disponibili per l'elaborazione da parte dei servizi di backend. Funge da fornitore di servizi convalidando le asserzioni nei messaggi di richiesta in entrata.

Il tipo di criterio SAML supporta le asserzioni SAML che corrispondono alla versione 2.0 della specifica SAML Core e alla versione 1.0 della specifica WS-Security SAML Token Profile.

Genera asserzione SAML

Elaborazione delle norme:

  1. Se il messaggio non è XML e IgnoreContentType non è impostato su true, allora genera un errore.
  2. Se è impostato "Template", elabora il modello come descritto per il criterio AssignMessage. Se mancano variabili e IgnoreUnresolvedVariables non è impostato, genera un errore.
  3. Se "Template" non è impostato, crea un'asserzione che includa i valori dei parametri Subject e Issuer o i relativi riferimenti.
  4. Firma l'asserzione utilizzando la chiave specificata.
  5. Aggiungi l'asserzione al messaggio nel percorso XPath specificato.

Convalida dell'asserzione SAML

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 <IgnoreContentType> non è impostato, il criterio 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 convaliderà la firma digitale XML utilizzando i valori di <TrustStore> e <ValidateSigner> come descritto in precedenza. Se la convalida non riesce, il criterio genererà un errore.

Una volta completata la policy senza errori, 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 norme 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

Esistono molte informazioni che possono essere specificate in un'asserzione SAML. 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 "Subject" 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 dell'oggetto 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

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