Stai visualizzando la documentazione di Apigee Edge.
Vai alla sezione
Documentazione di Apigee X. Informazioni

Cosa
- Autenticazione e autorizzazione in entrata: convalida l'asserzione SAML
norme
Il tipo di criterio SAML consente ai proxy API di convalidare le asserzioni SAML collegate a richieste SOAP in entrata. Il criterio SAML convalida i messaggi in arrivo che contengono un asserzione SAML con firma digitale, le rifiuta se non sono valide e imposta variabili che consentire criteri aggiuntivi, o i servizi di backend stessi, per convalidare ulteriormente le informazioni nell'asserzione. - Generazione di token in uscita: genera 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 consentire ai servizi di backend di applicare ulteriore sicurezza per l'autenticazione e l'autorizzazione.
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="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 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 nel
dell'organizzazione. I caratteri che puoi utilizzare nel nome sono limitati a: A-Z0-9._\-$
% . Tuttavia, l'interfaccia utente di gestione applica restrizioni aggiuntive, come
rimuove automaticamente i 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 XML
Content-Type (Tipo di contenuto). Se viene impostato su true , il messaggio verrà trattato come XML
a prescindere dal tipo di contenuto. |
||
Issuer |
L'identificatore univoco del provider di identità. Se l'attributo facoltativo
ref
, il valore di Issuer verrà assegnato in fase di runtime in base
specificata. Se l'attributo facoltativo ref non è presente, la classe
verrà utilizzato il valore dell'emittente.
|
||
KeyStore |
Il nome dell'archivio chiavi che contiene la chiave privata e l'alias della chiave privata
per firmare digitalmente le asserzioni SAML.
|
||
OutputVariable |
|||
FlowVariable |
|||
Message |
Il target del criterio. I valori validi sono message , request ,
e response . Se impostato su message , il criterio viene applicato in modo condizionale
recupera l'oggetto del messaggio in base al punto di collegamento del criterio. Se associato a
flusso della richiesta, il criterio risolve message in richiesta e, quando è collegato a
il flusso di risposta, il criterio risolve message in risposta. |
||
XPath |
Un'espressione XPath che indica l'elemento sul 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 l'oggetto facoltativo
L'attributo
ref è presente, il valore di Subject verrà assegnato a
in base alla variabile specificata. Se l'attributo facoltativo ref è
presente, verrà usato il valore Subject.
|
||
Template |
Se presente, l'asserzione verrà generata eseguendo questo modello, sostituendo
tutto ciò è indicato come
{} con la variabile corrispondente, quindi digitalmente
firmando il risultato. Il modello viene elaborato in base alle regole del criterioAssignMessage.
Vedi Assegna
Criteri relativi ai messaggi.
|
Convalida asserzione SAML
Nome campo | Descrizione |
---|---|
name attributo |
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, l'interfaccia utente di gestione applica restrizioni aggiuntive, come la configurazione
rimuovendo 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 XML
Content-Type (Tipo di contenuto). Se viene impostato su true , il messaggio verrà trattato come XML
a prescindere dal tipo di contenuto. |
Source |
Il target del criterio. I valori validi sono message , request ,
e response . Se impostato su message , il criterio viene applicato in modo condizionale
recupera l'oggetto del messaggio in base al punto di collegamento del criterio. Se associato a
flusso della richiesta, il criterio risolve message in richiesta e, quando è collegato a
il flusso di risposta, il criterio risolve message in risposta. |
XPath |
Obsoleta. Secondario di
Source . Utilizza le funzionalità di
AssertionXPath e SignedElementXPath .
|
AssertionXPath |
Secondario di
Source . Un'espressione XPath che indica l'elemento nella
documento XML in entrata da cui il criterio può estrarre l'asserzione SAML.
|
SignedElementXPath |
Secondario di
Source . Un'espressione XPath che indica l'elemento nella
documento XML in entrata da cui il criterio può estrarre l'elemento firmato. Questo
potrebbe essere diverso o uguale all'XPath di AssertionXPath .
|
TrustStore |
Il nome del TrustStore che contiene i certificati X.509 attendibili utilizzati per la convalida
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
il messaggio viene inoltrato al servizio di backend.
|
Note sull'utilizzo
La specifica SAML (Security Assertion Markup Language) definisce i formati e i protocolli che consente alle applicazioni di scambiare informazioni in formato XML per l'autenticazione e autorizzazione.
Una "asserzione di sicurezza" è un token attendibile che descrive un attributo di un'app, un utente di app o qualche altro partecipante a una transazione. Le asserzioni di sicurezza sono gestite e utilizzate da due tipi di entità:
- Provider di identità: generazione di asserzioni di sicurezza per conto dei partecipanti
- Provider di servizi: convalida le asserzioni di sicurezza attraverso relazioni di fiducia con identità provider
La piattaforma API può fungere da provider di identità e da fornitore di servizi. Funge da il provider di identità generando asserzioni e allegandole ai messaggi di richiesta, in modo che disponibili per l'elaborazione da parte dei servizi di backend. Funge da fornitore di servizi convalidare le asserzioni nei messaggi di richiesta in entrata.
Il tipo di criterio SAML supporta le asserzioni SAML corrispondenti alla versione 2.0 del componente SAML Core Specifica e versione 1.0 della specifica del profilo token SAML di WS-Security.
Genera asserzione SAML
Elaborazione criteri:
- Se il messaggio non è in formato XML e IgnoraContentType non è impostato su
true
, segnalare un errore. - Se "Modello" , quindi elabora il modello come descritto per il criterioAssignMessage. Se mancano delle variabili e IgnoraUnresolvedVariables non è impostata, genera un errore.
- Se "Modello" se non è impostato, crea un'asserzione che includa i valori dei Parametri soggetto ed emittente o relativi riferimenti.
- Firma l'asserzione utilizzando la chiave specificata.
- Aggiungi l'asserzione al messaggio nell'XPath specificato.
Convalida asserzione SAML
Elaborazione criteri:
- 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<IgnoreContentType>
non è configurato, il criterio genererà un errore. - Il criterio analizzerà il file XML. Se l'analisi non riesce, genera un errore.
- Il criterio estrarrà l'elemento firmato e l'asserzione, utilizzando i rispettivi XPath
specificato (
<SignedElementXPath>
e<AssertionXPath>
). Se uno di questi percorsi non restituisce un elemento, il criterio genera un errore. - Il criterio verificherà che l'asserzione corrisponda all'elemento firmato oppure è un elemento secondario dell'elemento firmato. In caso contrario, il criterio genererà un errore.
- Se
<NotBefore>
o<NotOnOrAfter>
sono presenti elementi nell'asserzione, il criterio controllerà il timestamp corrente con 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 in SAML Core, sezione 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 genera un errore.
Quando il criterio viene completato senza segnalare un errore, lo sviluppatore del proxy può essere certo dei seguenti:
- La firma digitale sull'asserzione è valida ed è stata firmata da un'autorità di certificazione 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 relativi all'utilizzo di questi valori per un'autenticazione aggiuntiva, come controllare che il nome dell'oggetto sia valido o passarlo a un sistema di destinazione per la convalida.
Per analizzare il codice XML non elaborato dell'asserzione è possibile utilizzare altri criteri, come ExtractVariables per una convalida più complessa.
Variabili di flusso
In un'asserzione SAML è possibile specificare molte informazioni. Il protocollo SAML l'asserzione stessa è un file XML che può essere analizzato utilizzando il criterio ExtractVariables e altro in modo da implementare convalide più complesse.
Variabile | Descrizione |
---|---|
saml.id |
ID asserzione SAML |
saml.issuer |
L'"Emittente" dell'asserzione, convertito dal tipo XML nativo in una stringa |
saml.subject |
"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 |
IssueInstant |
saml.subjectFormat |
Formato 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 dell'oggetto |
saml.authnSnooa |
AuthnStatement SessionNotOnOrAfter |
saml.authnContextClassRef |
AuthnStatement AuthnContextClassRef |
saml.authnInstant |
AuthnStatement AuthIstantanea |
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 Edge 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.
Error name | Cause | Fix |
---|---|---|
SourceNotConfigured |
One or more of the following elements of the Validate SAML Assertion
policy is not defined or empty: <Source> , <XPath> ,
<Namespaces> , <Namespace> .
|
build |
TrustStoreNotConfigured |
If the <TrustStore> element is empty or not specified in the
ValidateSAMLAssertion policy, then the deployment of the API proxy fails.
A valid Trust Store is required.
|
build |
NullKeyStoreAlias |
If the child element <Alias> is empty or not specified in the <Keystore>
element of Generate SAML Assertion policy, then the deployment of the API
proxy fails. A valid Keystore alias is required.
|
build |
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.
|
build |
NullIssuer |
If the <Issuer> element is empty or not specified in the Generate SAML
Assertion policy, then the deployment of the API proxy fails. A
valid <Issuer> value is required.
|
build |
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
{ "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 di variabili: Estrai variabili norme