Criteri SAMLAssertion

Stai visualizzando la documentazione di Apigee Edge.
Vai alla documentazione di Apigee X.
informazioni

Cosa

  • Autenticazione e autorizzazione in entrata: convalida criterio di asserzione SAML
    Il tipo di criterio SAML consente ai proxy API di convalidare le asserzioni SAML collegate alle richieste SOAP in entrata. Il criterio SAML convalida i messaggi in arrivo che contengono un'asserzione SAML con firma digitale, li rifiuta se non sono validi e imposta variabili che consentono criteri aggiuntivi, o i servizi di backend stessi, per convalidare ulteriormente le informazioni nell'asserzione.
  • Generazione di token in uscita: genera un criterio di asserzione SAML
    Il tipo di criterio SAML consente ai proxy API di collegare le asserzioni SAML alle richieste XML in uscita. Queste asserzioni sono quindi disponibili per abilitare i servizi di backend per applicare ulteriori elaborazioni di sicurezza per l'autenticazione e l'autorizzazione.

Samples

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

Generazione di un'asserzione SAML

Convalida l'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
name attributo Il nome dell'istanza del criterio. Il nome deve essere univoco nell'organizzazione. I caratteri utilizzabili nel nome sono limitati a: A-Z0-9._\-$ %. Tuttavia, l'interfaccia utente di gestione applica restrizioni aggiuntive, come la rimozione automatica dei caratteri non alfanumerici.
ignoreContentType attributo 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 il criterio viene impostato su true, il messaggio verrà considerato come XML, a prescindere dal tipo di contenuto.
Issuer
L'identificatore univoco del provider di identità. Se è presente l'attributo facoltativo ref, il valore dell'emittente verrà assegnato in fase di runtime in base alla variabile specificata. Se l'attributo facoltativo ref non è presente, verrà utilizzato il valore dell'emittente.
KeyStore
Il nome dell'archivio chiavi che contiene la chiave privata e l'alias della chiave privata utilizzata per firmare digitalmente le asserzioni SAML.
OutputVariable
FlowVariable
Message La destinazione del criterio. 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 allegato del criterio. Una volta associato al flusso di richiesta, il criterio risolve la richiesta di message e, quando collegato al flusso di risposta, risolve message in risposta.
XPath Un'espressione XPath che indica l'elemento nel documento XML in uscita a cui il criterio collegherà l'asserzione SAML.
SignatureAlgorithm SHA1 o SHA256
Subject
L'identificatore univoco del soggetto dell'asserzione SAML. Se è presente l'attributo facoltativo ref, il valore dell'oggetto Oggetto verrà assegnato in fase di runtime in base alla variabile specificata. Se è presente l'attributo facoltativo ref, verrà utilizzato il valore dell'oggetto.
Template
Se presente, l'asserzione verrà generata eseguendo questo modello, sostituendo tutto ciò che indica {} con la variabile corrispondente, quindi firmando digitalmente il risultato. Il modello viene elaborato in base alle regole dei criteri di AttributionMessage. Vedi Assegnare i criteri per i messaggi.

Convalida asserzione SAML

Nome campo Descrizione
name attributo
Il nome dell'istanza del criterio. Il nome deve essere univoco all'interno dell'organizzazione. I caratteri utilizzabili nel nome sono limitati a: A-Z0-9._\-$ %. Tuttavia, l'interfaccia utente di gestione applica restrizioni aggiuntive, come la rimozione automatica dei caratteri non alfanumerici.
ignoreContentType attributo 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 il criterio viene impostato su true, il messaggio verrà considerato come XML, indipendentemente dal tipo di contenuto.
Source La destinazione del criterio. 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 allegato del criterio. Una volta associato al flusso di richiesta, il criterio risolve la richiesta di message e, quando collegato al flusso di risposta, risolve message in risposta.
XPath
Obsoleto. Secondario di Source. Utilizza AssertionXPath e SignedElementXPath.
AssertionXPath
Secondario di Source. Un'espressione XPath che indica l'elemento nel documento XML in entrata da cui il criterio può estrarre l'asserzione SAML.
SignedElementXPath
Secondario di Source. Un'espressione XPath che indica l'elemento nel documento XML in entrata da cui il criterio può estrarre l'elemento firmato. Potrebbe essere diverso o uguale all'XPath di AssertionXPath.
TrustStore
Il nome del TrustStore che contiene 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. 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 i formati e i 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, un utente dell'app o un altro partecipante a una transazione. Le dichiarazioni di sicurezza vengono gestite e utilizzate da due tipi di entità:

  • Provider di identità: generano asserzioni di sicurezza per conto dei partecipanti
  • Provider di servizi: convalida le dichiarazioni di sicurezza tramite relazioni di fiducia con i provider di identità

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

Il tipo di criterio SAML supporta le asserzioni SAML corrispondenti alla versione 2.0 della specifica SAML Core e alla versione 1.0 della specifica del profilo token SAML WS-Security.

Genera asserzione SAML

Elaborazione dei criteri:

  1. Se il messaggio non è XML e IgnoraContentType non è impostato su true, segnala un errore.
  2. Se "Modello" è impostato, elabora il modello come descritto per il criterio AssegnaMessage. Se mancano variabili e IgnoraUnresolvedVariables non è impostato, genera un errore.
  3. Se "Template" (Modello) non è impostato, costruisci un'asserzione che includa i valori dei parametri Subject ed Issuer o i relativi riferimenti.
  4. Firma l'asserzione utilizzando la chiave specificata.
  5. Aggiungi l'asserzione al messaggio nell'XPath specificato.

Convalida asserzione SAML

Elaborazione dei criteri:

  1. Il criterio controlla il messaggio in entrata per verificare che il tipo multimediale 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 il criterio <IgnoreContentType> non è impostato, il criterio causerà un errore.
  2. Il criterio analizzerà il codice XML. Se l'analisi non va a buon fine, verrà generato un errore.
  3. Il criterio estrarrà 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 causerà un errore.
  4. Il criterio verificherà che l'asserzione sia uguale all'elemento firmato o sia un elemento secondario dell'elemento firmato. Se non è vero, il criterio causerà un errore.
  5. Se nell'asserzione è presente uno degli elementi <NotBefore> o <NotOnOrAfter>, il criterio controllerà il timestamp attuale con questi valori, come descritto nella sezione 2.5.1 di SAML Core.
  6. Il criterio applicherà eventuali regole aggiuntive per l'elaborazione delle "Condizioni", come descritto nella sezione 2.5.1.1 di SAML Core.
  7. Il criterio convaliderà la firma digitale XML utilizzando i valori <TrustStore> e <ValidateSigner> come descritto sopra. Se la convalida non va a buon fine, il criterio causerà un errore.

Una volta completato il criterio senza segnalare un errore, lo sviluppatore del proxy può garantire quanto segue:

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

Altri criteri, come ExtractVariables, possono essere utilizzati per analizzare il codice XML non elaborato dell'asserzione per una convalida più complessa.


Variabili di flusso

Esistono molte informazioni che possono essere specificate in un'asserzione SAML. L'asserzione SAML stessa è un codice 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 in una stringa
saml.subject Il "Oggetto" dell'asserzione, convertito dal tipo XML nativo in una stringa
saml.valid Restituisce true o false in base al risultato del controllo di validità
saml.issueInstant Problema istantaneo
saml.subjectFormat Formato oggetto
saml.scmethod Metodo conferma oggetto
saml.scdaddress Indirizzo dati di conferma del soggetto
saml.scdinresponse Dati di conferma del soggetto in risposta
saml.scdrcpt Destinatario dei dati di conferma del soggetto
saml.authnSnooa AuthnStatement SessionNotOnOrAfter
saml.authnContextClassRef AuthnContextClassRef AuthnStatement
saml.authnInstant AuthnStatement AuthInstant
saml.authnSessionIndex Indice sessione AuthnStatement

Messaggi di errore

Questa sezione descrive i codici e i messaggi di errore che vengono restituiti e le variabili di errore impostate da Edge quando il criterio attiva un errore. Queste informazioni sono importanti per sapere se stai sviluppando regole di errore per gestire gli errori. Per scoprire di più, consulta le informazioni relative agli errori dei criteri e la gestione degli errori.

Errori di deployment

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

Nome errore Causa Correggi
SourceNotConfigured Uno o più dei seguenti elementi del criterio Convalida l'asserzione SAML non sono definiti o vuoti: <Source>, <XPath>, <Namespaces> e <Namespace>.
TrustStoreNotConfigured Se l'elemento <TrustStore> è vuoto o non è specificato nel criterio Validate SAMLAssertion, il deployment del proxy API non riesce. È necessario un Trust Store valido.
NullKeyStoreAlias Se l'elemento figlio <Alias> è vuoto o non è specificato nell'elemento <Keystore> del criterio Genera asserzione SAML, il deployment del proxy API non riesce. È necessario un alias di archivio chiavi valido.
NullKeyStore Se l'elemento figlio <Name> è vuoto o non è specificato nell'elemento <Keystore> del criterio Genera SAMLAssertion, il deployment del proxy API non riesce. È necessario un nome di archivio chiavi valido.
NullIssuer Se l'elemento <Issuer> è vuoto o non è specificato nel criterio Genera asserzione SAML, il deployment del proxy API non riesce. È richiesto un valore <Issuer> valido.

Variabili di errore

Queste variabili vengono impostate quando si verifica un errore di runtime. Per maggiori informazioni, consulta la sezione Cosa devi sapere sugli errori delle 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 di errore è ValidateSAMLAssertion. GenerateSAMLAssertion.failed = true

Esempio di risposta all'errore

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

Regola di errore di esempio

<FaultRules>
    <FaultRule name="invalid_saml_rule">
        <Step>
            <Name>invalid-saml</Name>
        </Step>
        <Condition>(GenerateSAMLAssertion.failed = "true")</Condition>
    </FaultRule>
</FaultRules>

Argomenti correlati

Estrazione delle variabili: Estrai criterio delle variabili