Questa pagina è stata tradotta dall'API Cloud Translation.

Criteri SAMLAssertion

Questa pagina si applica ad Apigee e Apigee hybrid.

Visualizza la documentazione di Apigee Edge.

Cosa

Autenticazione e autorizzazione in entrata: convalida del criterio di asserzione SAML
Il tipo di criterio SAML consente ai proxy API di convalidare le asserzioni SAML allegate alle richieste SOAP in entrata. Il criterio SAML convalida i messaggi in arrivo che contengono un'affermazione SAML firmata digitalmente, li rifiuta se non sono validi e imposta variabili che consentono a criteri aggiuntivi o ai servizi di backend stessi di convalidare ulteriormente le informazioni nell'affermazione.
Generare token in uscita: genera criterio di asserzione SAML
Il tipo di criterio 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 elaborazione di sicurezza per l'autenticazione e l'autorizzazione.

Questo criterio è un criterio estensibile e il suo utilizzo potrebbe comportare implicazioni in termini di costi o utilizzo, a seconda della licenza Apigee. Per informazioni sui tipi di criteri e sulle implicazioni per l'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'affermazione SAML

Convalida dell'affermazione 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'affermazione SAML

Riferimento elemento

Genera asserzione SAML

Nome campo	Descrizione
Attributo `name`	Il nome dell'istanza del criterio. Il nome deve essere univoco all'interno dell'organizzazione. I caratteri che puoi utilizzare nel nome sono limitati a: `A-Z0-9._\-$ %`. Tuttavia, l'interfaccia utente 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, la dichiarazione 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.
`Issuer`	L'identificatore univoco del provider di identità. Se è presente l'attributo facoltativo `ref`, il valore di Issuer verrà assegnato in fase di esecuzione in base alla variabile specificata. Se l'attributo facoltativo `ref` non è presente, verrà utilizzato il valore di Issuer.
`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 del criterio. I valori validi sono `message`, `request` e `response`. Se impostato su `message`, il criterio recupera condizionatamente l'oggetto messaggio in base al punto di attacco del criterio. Se è associato al flusso di richiesta, il criterio risolve `message` in richiesta e, se è associato al flusso di risposta, risolve `message` in risposta.
`XPath`	Un'espressione XPath che indica l'elemento del documento XML in uscita a cui il criterio collegherà l'affermazione SAML.
`SignatureAlgorithm`	SHA1 o SHA256
`Subject`	L'identificatore univoco del soggetto dell'affermazione SAML. Se è presente l'attributo facoltativo `ref`, 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'affermazione verrà generata eseguendo questo modello, sostituendo tutto ciò che è indicato con `{}` con la variabile corrispondente e poi firmando digitalmente il risultato. Il modello viene elaborato in base alle regole del criterio AssignMessage. Consulta le norme di AssignMessage. L'elemento `<Template>` supporta la funzionalità di sostituzione di stringhe dinamiche chiamata modello di messaggio. La creazione di modelli di messaggi è supportata solo quando la firma del criterio è `GenerateSamlAssertion`.

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 utilizzare nel nome sono limitati a: `A-Z0-9._\-$ %`. Tuttavia, l'interfaccia utente di Apigee applica limitazioni aggiuntive, 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, la dichiarazione 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 del criterio. I valori validi sono `message`, `request` e `response`. Se impostato su `message`, il criterio recupera condizionatamente l'oggetto messaggio in base al punto di attacco del criterio. Se è associato al flusso di richiesta, il criterio risolve `message` in `request` e, se è associato al flusso di risposta, risolve `message` in `response`.
`XPath`	Ritiro. Figlio di `Source`. Utilizza `AssertionXPath` e `SignedElementXPath`.
`AssertionXPath`	Figlio di `Source`. Un'espressione XPath che indica l'elemento nel documento XML in entrata da cui il criterio può estrarre l'affermazione SAML.
`SignedElementXPath`	Figlio di `Source`. Un'espressione XPath che indica l'elemento nel documento XML in entrata da cui il criterio può estrarre l'elemento firmato. Questo valore 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 sulle asserzioni SAML.
`RemoveAssertion`	Un valore booleano che può essere impostato su `true` o `false`. Quando `true`, l'affermazione 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 formati e protocolli che consentono alle applicazioni di scambiare informazioni in formato XML per l'autenticazione e l'autorizzazione.

Un'"affermazione 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 affermazioni di sicurezza per conto dei partecipanti
Fornitori di servizi: convalida delle affermazioni di sicurezza tramite relazioni attendibili con i provider di identità

La piattaforma API può fungere da provider di identità e da fornitore di servizi. Agisce come fornitore di identità generando asserzioni e associandole 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 di base di SAML e alla versione 1.0 della specifica del profilo token SAML di WS-Security.

Genera asserzione SAML

Elaborazione delle norme:

Se il messaggio non è XML e IgnoreContentType non è impostato su true, segnala un errore.
Se è impostato il valore "Modello", elabora il modello come descritto per il criterio AssignMessage. Se mancano delle variabili e IgnoreUnresolvedVariables non è impostato, viene generato un errore.
Se "Modello" non è impostato, crea un'affermazione che includa i valori dei parametri Subject e Issuer o i relativi riferimenti.
Firma l'affermazione utilizzando la chiave specificata.
Aggiungi l'affermazione al messaggio nell'XPath specificato.

Convalida asserzione SAML

Elaborazione delle norme:

Il criterio controlla il messaggio in entrata per verificare che il tipo di media della richiesta sia XML, controllando se il tipo di contenuto corrisponde ai formati text/(.*+)?xml o application/(.*+)?xml. Se il tipo di media non è XML e <IgnoreContentType> non è impostato, il criterio genera un errore.
Il criterio analizzerà il file XML. Se l'analisi non va a buon fine, viene generato un errore.
Il criterio estrae l'elemento firmato e l'affermazione utilizzando i rispettivi XPath specificati (<SignedElementXPath> e <AssertionXPath>). Se uno di questi percorsi non restituisce un elemento, il criterio genera un errore.
Il criterio verificherà che l'affermazione sia uguale all'elemento firmato o sia un elemento secondario dell'elemento firmato. In caso contrario, il criterio genererà un errore.
Se nell'affermazione sono presenti gli elementi <NotBefore> o <NotOnOrAfter>, il criterio controllerà il timestamp corrente in base 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 2.5.1.1 di SAML Core.
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.

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

La firma digitale dell'affermazione è valida ed è stata firmata da un'autorità di certificazione attendibile
L'affermazione è valida per il periodo di tempo corrente
Il soggetto e l'emittente dell'affermazione verranno estratti e impostati nelle variabili di flusso. È compito di altri criteri utilizzare questi valori per un'autenticazione aggiuntiva, ad esempio per verificare che il nome dell'oggetto sia valido o per trasmetterlo a un sistema di destinazione per la convalida.

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

Variabili di flusso

Esistono molti elementi di informazione che possono essere specificati in un'asserzione SAML. L'affermazione SAML stessa è XML che può essere analizzata utilizzando il criterio ExtractVariables e altri meccanismi per implementare convalide più complesse.

Variabile	Descrizione
`saml.id`	L'ID asserzione SAML
`saml.issuer`	L'"Issuer" dell'affermazione, convertito dal tipo XML nativo in una stringa
`saml.subject`	L'attributo "Subject" dell'affermazione, 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 dell'oggetto
`saml.scmethod`	Metodo di conferma dell'oggetto
`saml.scdaddress`	Indirizzo dati per la conferma dell'oggetto
`saml.scdinresponse`	Dati di conferma dell'oggetto nella risposta
`saml.scdrcpt`	Destinatario dei dati di conferma dell'oggetto
`saml.authnSnooa`	AuthnStatement SessionNotOnOrAfter
`saml.authnContextClassRef`	AuthnStatement AuthnContextClassRef
`saml.authnInstant`	AuthnStatement AuthInstant
`saml.authnSessionIndex`	AuthnStatement Session Index

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 dei criteri di asserzione SAML convalidata, il prefisso dell'errore è `ValidateSAMLAssertion`.	`GenerateSAMLAssertion.failed = true`

Esempio di risposta di errore

Nota: per la gestione degli errori, la best practice è intercettare la parte errorcode della risposta all'errore. Non fare affidamento sul testo in faultstring, perché potrebbe cambiare.

{
  "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: Norme per l'estrazione delle variabili