GenerateSAMLAssertion policy

Policy estensibile

Questa pagina si applica ad Apigee e Apigee hybrid.

Visualizza Apigee Edge documentazione.

La policy GenerateSAMLAssertion consente ai proxy API di allegare asserzioni SAML alle richieste XML in uscita. Queste asserzioni sono quindi disponibili per i servizi di backend per applicare un'ulteriore elaborazione di sicurezza per l'autenticazione e l'autorizzazione. Per saperne di più, consulta la panoramica delle policy SAML.

Questa policy è una policy estensibile e il suo utilizzo potrebbe avere implicazioni in termini di costi o utilizzo, a seconda della licenza Apigee. Per informazioni sui tipi di policy e sulle implicazioni di utilizzo, consulta Tipi di policy.

Esempi

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

Riferimento elemento

Questa sezione elenca gli elementi e gli attributi della policy GenerateSAMLAssertion.

Attributi che si applicano all'elemento di primo livello

<GenerateSAMLAssertion name="SAML-A1" continueOnError="false" enabled="true" async="false">

I seguenti attributi sono comuni a tutti gli elementi principali della policy.

Attributo	Descrizione	Predefinito	Presenza
nome	Il nome interno della policy. I caratteri che puoi utilizzare nel nome sono limitati a: `A-Z0-9._\-$ %`. Tuttavia, l'interfaccia utente di Apigee applica ulteriori restrizioni, ad esempio la rimozione automatica dei caratteri non alfanumerici. Facoltativamente, utilizza l'elemento `<displayname></displayname>` per etichettare la policy nell'editor dei proxy dell'interfaccia utente di Apigee con un nome diverso in linguaggio naturale.	N/D	Obbligatorio
abilitato	Imposta su `true` per applicare la policy. Imposta su `false` per "disattivare" la policy. La policy non verrà applicata anche se rimane collegata a un flusso.	true	Facoltativo

Elementi e attributi per la generazione di asserzioni SAML

Nome campo	Descrizione
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 tipo di contenuto XML Content-Type. 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 `ref` facoltativo, il valore di Issuer verrà assegnato in fase di runtime in base alla variabile specificata. Se l'attributo `ref` facoltativo non è presente, verrà utilizzato il valore di Issuer.
`KeyStore`	Il nome del KeyStore che contiene la chiave privata e l'alias della chiave privata utilizzata per firmare digitalmente le asserzioni SAML.
`OutputVariable`	Specifica dove verrà inserita l'asserzione SAML generata. L'asserzione può essere archiviata in una variabile di flusso o inserita in un messaggio esistente.
`FlowVariable`	Specifica il nome della variabile di flusso in cui verranno archiviati i contenuti dell'asserzione SAML generata. Questa è un'alternativa all'utilizzo dell'elemento `<Message>` per inserire l'asserzione in un messaggio XML esistente.
`Message`	La destinazione della policy. I valori validi sono `message`, `request`, e `response`. Se impostata su `message`, la policy recupera in modo condizionale l'oggetto messaggio in base al punto di collegamento della policy. Quando è collegata al flusso della richiesta, la policy risolve `message` nella richiesta e, quando è collegata al flusso della risposta, la policy risolve `message` nella risposta.
`XPath`	Un'espressione XPath che indica l'elemento del documento XML in uscita a cui la policy allegherà l'asserzione SAML.
`SignatureAlgorithm`	SHA1 o SHA256
`Subject`	L'identificatore univoco del soggetto dell'asserzione SAML. Se è presente l'attributo facoltativo `ref`, il valore di Subject verrà assegnato in fase di runtime in base alla variabile specificata. Se l'attributo facoltativo `ref` non è presente, verrà utilizzato il valore di Subject.
`Template`	Se presente, l'asserzione verrà generata eseguendo questo modello, sostituendo tutto ciò che è indicato `{}` con la variabile corrispondente e firmando digitalmente il risultato. Il modello viene elaborato seguendo le regole della policy AssignMessage. Consulta la policy AssignMessage. L'elemento `<Template>` supporta la funzionalità di sostituzione dinamica delle stringhe denominata creazione di modelli di messaggi. La creazione di modelli di messaggi è supportata solo quando la firma della policy è `GenerateSamlAssertion`.

Note sull'utilizzo

Elaborazione delle policy:

Se il messaggio non è XML e ignoreContentType non è impostato su true, allora genera un errore.
Se Template è impostato, elabora il modello come descritto per la policy AssignMessage. Se mancano delle variabili e ignoreUnresolvedVariables non è impostato, genera un errore.
Se Template non è impostato, crea un'asserzione che includa i valori dei parametri Subject e Issuer o i relativi riferimenti.
Firma l'asserzione utilizzando la chiave specificata.
Aggiungi l'asserzione al messaggio nel percorso XPath specificato.

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

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: Extract Variables policy