Questa pagina si applica ad Apigee e Apigee hybrid.
Visualizza la documentazione di Apigee Edge.
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 della sicurezza per l'autenticazione e l'autorizzazione.
Questo criterio è un criterio estendibile e il suo utilizzo potrebbe avere implicazioni in termini di costi o 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 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 usare nel nome sono limitati a: A-Z0-9._\-$
% . Tuttavia, la UI di Apigee applica limitazioni aggiuntive, come 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 viene generata se il tipo di contenuto del messaggio non è un Content-Type XML. Se viene impostato su true , il messaggio verrà considerato come XML, indipendentemente 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 |
Il target del criterio. I valori validi sono message , request e response . Se viene impostato su message , il criterio recupera l'oggetto del messaggio in modo condizionale in base al punto di allegato del criterio. Se associato al flusso di richiesta, il criterio risolve message nella richiesta e, se associato al flusso di risposta, il criterio 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 verrà assegnato durante il 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 del criterio AttributionMessage.
Vedi Assegnare i criteri per i messaggi.
|
Convalida asserzione SAML
Nome campo | Descrizione |
---|---|
Attributo name |
Il nome dell'istanza del criterio. Il nome deve essere univoco nell'organizzazione.
I caratteri che puoi usare nel nome sono limitati a:
A-Z0-9._\-$ % .
Tuttavia, la UI di Apigee applica limitazioni aggiuntive, come 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 viene generata se il tipo di contenuto del messaggio non è un Content-Type XML. Se viene impostato su true , il messaggio verrà considerato come XML, indipendentemente dal tipo di contenuto. |
Source |
Il target del criterio. I valori validi sono message , request e response . Se viene impostato su message , il criterio recupera l'oggetto del messaggio in modo condizionale in base al punto di allegato del criterio. Se associato al flusso di richiesta, il criterio risolve message in request e, se associato al flusso di risposta, il criterio risolve message in response . |
XPath |
Obsoleta. Secondario di
Source . Usa
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. Questo
può essere diverso o uguale all'XPath di AssertionXPath .
|
TrustStore |
Il nome dell'archivio attendibilità 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 viene 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 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: convalida le asserzioni di sicurezza attraverso relazioni di fiducia con provider di identità
La piattaforma API può fungere da provider di identità e da fornitore di servizi. Agisce come 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 che corrispondono 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 delle norme:
- Se il messaggio non è XML e IgnoraContentType non è impostato su
true
, genera un errore. - Se è impostata l'opzione "Template" (Modello), elabora il modello come descritto per il criterio AttributionMessage. Se mancano variabili e ignoreUnresolvedVariables non è impostato, genera un errore.
- Se "Template" (Modello) non è impostato, crea un'asserzione che includa i valori dei parametri Subject ed Issuer o dei relativi riferimenti.
- Firma l'asserzione utilizzando la chiave specificata.
- Aggiungi l'asserzione al messaggio nel XPath specificato.
Convalida asserzione SAML
Elaborazione delle norme:
- Il criterio controlla il messaggio in entrata per verificare che il tipo multimediale della richiesta sia XML, controllando se il tipo di contenuti corrisponde ai formati
text/(.*+)?xml
oapplication/(.*+)?xml
. Se il tipo multimediale non è XML e il criterio<IgnoreContentType>
non è configurato, il criterio genererà un errore. - Il criterio analizzerà il codice XML. Se l'analisi non va a buon fine, verrà segnalato un errore.
- 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 genererà un errore. - Il criterio verificherà che l'asserzione corrisponda all'elemento firmato o sia un elemento secondario dell'elemento firmato. Se questo non è vero, il criterio genererà un errore.
- Se nell'asserzione è presente uno degli elementi
<NotBefore>
o<NotOnOrAfter>
, il criterio controllerà il timestamp attuale rispetto a questi valori, come descritto nella sezione 2.5.1 di SAML Core. - Il criterio applicherà eventuali regole aggiuntive per l'elaborazione delle "Condizioni" come descritto nella sezione SAML Core 2.5.1.1.
- Il criterio convaliderà la firma digitale XML utilizzando i valori di
<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
- Il soggetto e l'emittente dell'asserzione verranno estratti e impostati in variabili di flusso. È responsabilità di altri criteri utilizzare questi valori per un'autenticazione aggiuntiva, ad esempio per verificare che il nome del soggetto sia valido o passarlo a un sistema di destinazione per la convalida.
Altri criteri, come ExtractVariables, possono essere usati per analizzare il codice XML non elaborato dell'asserzione per una convalida più complessa.
Variabili di flusso
È possibile specificare molte informazioni in un'asserzione SAML. L'asserzione SAML stessa è un file 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, convertito dal tipo XML nativo in una stringa |
saml.subject |
Il "Subject" 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 |
IssueInstant |
saml.subjectFormat |
Formato oggetto |
saml.scmethod |
Metodo di conferma dell'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 dell'oggetto |
saml.authnSnooa |
Sessione sulla dichiarazione di autorizzazioneNonOODopo |
saml.authnContextClassRef |
AuthnStatement AuthnContextClassRef - Dichiarazione di autenticazione |
saml.authnInstant |
AuthnStatement AuthIstantanea |
saml.authnSessionIndex |
Indice delle sessioni AuthnStatement |
Messaggi di errore
Questa sezione descrive i codici e i messaggi di errore restituiti e le variabili di errore impostate da Apigee quando questo criterio attiva un errore. Queste informazioni sono importanti per sapere se si stanno sviluppando regole di errore per gestire gli errori. Per scoprire di più, consulta gli articoli Cosa devi sapere 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 errore | Causa | Correggi |
---|---|---|
SourceNotConfigured |
Uno o più dei seguenti elementi del criterio ValidateSAMLAssertion
non sono definiti o vuoti: <Source> , <XPath> ,
<Namespaces> , <Namespace> .
|
build |
TrustStoreNotConfigured |
Se l'elemento <TrustStore> è vuoto o non specificato nel criterio ValidateSAMLAssertion , il deployment del proxy API non va a buon fine.
È richiesto un archivio di attendibilità valido.
|
build |
NullKeyStoreAlias |
Se l'elemento secondario <Alias> è vuoto o non è specificato nell'elemento <Keystore> del criterio GenerateSAMLAssertion , il deployment del proxy API non riesce. È richiesto un alias di archivio chiavi valido.
|
build |
NullKeyStore |
Se l'elemento secondario <Name> è vuoto o non è specificato nell'elemento <Keystore> del criterio GenerateSAMLAssertion , il deployment del proxy API non riesce. È necessario un nome di archivio chiavi valido.
|
build |
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.
|
build |
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 relativi ai criteri.
Variabili | Dove | Esempio |
---|---|---|
fault.name="fault_name" |
fault_name è il nome dell'errore. Il nome del guasto è l'ultima parte del codice di errore. | fault.name = "InvalidMediaTpe" |
GenerateSAMLAssertion.failed |
Per una configurazione di convalida del criterio di asserzione SAML, 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: criterio Estrai variabili