Política de ValidateSAMLAssertion

Política extensible

Esta página se aplica a Apigee y Apigee Hybrid.

Consulta la documentación de Apigee Edge.

La política ValidateSAMLAssertion permite que los proxies de API validen las aserciones de SAML que se adjuntan a las solicitudes SOAP entrantes. La política de SAML valida los mensajes entrantes que contienen una aserción SAML con firma digital, los rechaza si no son válidos y configura variables que permiten políticas adicionales, o los servicios de backend, para validar aún más la información en la aserción. Consulta Descripción general de las políticas de SAML para obtener más información.

Esta política es una política extensible y el uso de esta política puede tener implicaciones de costo o uso, según tu licencia de Apigee. Para obtener información sobre los tipos de políticas y sus implicaciones de uso, consulta Tipos de políticas.

Muestras

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

Referencia del elemento

Valida la aserción de SAML

Nombre del campo Descripción
Atributo name
El nombre de la instancia de política. El nombre debe ser único en la organización. Los caracteres que puede usar en el nombre están restringidos a: A-Z0-9._\-$ %. Sin embargo, la IU de Apigee aplica restricciones adicionales, como quitar automáticamente los caracteres que no son alfanuméricos.
Atributo ignoreContentType Un valor booleano que se puede establecer en true o false. De forma predeterminada, la aserción no se validará si el tipo de contenido del mensaje no es un tipo de contenido XML de contenido. Si el valor es true, el mensaje se tratará como XML sin importar el tipo de contenido.
Source Es el destino de la política. Los valores válidos son message, request, y response. Cuando se establece en message, la política recupera de forma condicional el objeto de mensaje en función del punto de unión de la política. Cuando se adjunta al flujo de solicitudes, la política resuelve message como request y, cuando se adjunta al flujo de respuesta, la política resuelve message como response.
XPath
Obsoleto. Secundario de Source. Usa AssertionXPath y SignedElementXPath.
AssertionXPath
Secundario de Source. Una expresión XPath que indica el elemento en el documento XML entrante en el que la política puede extraer la aserción de SAML.
SignedElementXPath
Secundario de Source. Una expresión XPath que indica el elemento en el documento XML entrante desde el que la política puede extraer el elemento firmado. Puede ser diferente o igual que la XPath de AssertionXPath.
TrustStore
El nombre de TrustStore que contiene certificados X.509 de confianza que se usan para validar firmas digitales en las aserciones de SAML.
RemoveAssertion
Un valor booleano que se puede establecer en true o false. Cuando es true, la aserción de SAML se quitará del mensaje de solicitud antes de que el mensaje se reenvíe al servicio de backend.

Notas de uso

Procesamiento de políticas:

  1. La política comprueba el mensaje entrante para verificar que el tipo de medio de la solicitud sea XML y comprueba si el tipo de contenido coincide con los formatos text/(.*+)?xml o application/(.*+)?xml. Si el tipo de medio no es XML y el ignoreContentType atributo no está configurado en true, la política mostrará una falla.
  2. La política analizará el XML. Si no se realiza correctamente el análisis, se producirá un error.
  3. La política extraerá el elemento firmado y la aserción mediante las respectivas XPaths especificadas (<SignedElementXPath> y <AssertionXPath>). Si alguna de estas rutas no muestra un elemento, la política generará una falla.
  4. La política verificará que la aserción sea la misma que el elemento firmado o sea un elemento secundario del elemento firmado. Si este no es el caso, la política generará una falla.
  5. Si alguno de los elementos <NotBefore> o <NotOnOrAfter> está presente en la aserción, la política verificará la marca de tiempo actual con estos valores, como se describe en la sección principal de SAML 2.5.1.
  6. La política aplicará cualquier regla adicional para procesar las "Condiciones" como se describe en la sección principal de SAML 2.5.1.1.
  7. La política valida la firma digital XML con el valor del almacén de confianza (<TrustStore>) que se describió anteriormente. Si la validación falla, la política generará una falla.

Una vez que se complete la política sin generar un error, el desarrollador del proxy puede estar seguro de lo siguiente:

  • La firma digital de la aserción es válida y cuenta con la firma de una CA de confianza
  • La aserción es válida para el período actual
  • El sujeto y la entidad emisora de la aserción se extraerán y se configurarán en las variables de flujo. Es responsabilidad de otras políticas usar estos valores para la autenticación adicional, por ejemplo, verificar que el nombre del asunto sea válido o transferirlo a un sistema de destino para validarlo.

Otras políticas, como ExtractVariables, se pueden usar para analizar el XML sin procesar de la aserción para obtener una validación más compleja.

Variables de flujo

Existen muchos datos que pueden especificarse en una aserción de SAML. La aserción de SAML es XML y se puede analizar mediante la política ExtractVariables y otros mecanismos para implementar validaciones más complejas.

Variable Descripción
saml.id El ID de aserción de SAML
saml.issuer El "Emisor" de la aserción, convertido de su tipo XML nativo a una string
saml.subject El "asunto" de la aserción, convertido de su tipo XML nativo a una string
saml.valid Muestra verdadero o falso según el resultado de la verificación de validez.
saml.issueInstant IssueInstant
saml.subjectFormat Formato del asunto
saml.scmethod Método de confirmación del asunto
saml.scdaddress Dirección de datos de confirmación del asunto
saml.scdinresponse Datos de confirmación del asunto en respuesta
saml.scdrcpt Receptor de datos de confirmación del asunto
saml.authnSnooa AuthnStatement SessionNotOnOrAfter
saml.authnContextClassRef AuthnStatement AuthnContextClassRef
saml.authnInstant AuthnStatement AuthInstant
saml.authnSessionIndex Índice de sesión de AuthnStatement

Referencia de errores

En esta sección, se describen los códigos de fallas y los mensajes de error que se muestran, así como las variables de fallas que establece Apigee cuando esta política activa un error. Esta información es importante para saber si estás desarrollando reglas de fallas con el propósito de manejar fallas. Para obtener más información, consulta Qué debes saber sobre los errores de políticas y Cómo solucionar fallas.

Errores en la implementación

Estos errores pueden generarse cuando implementas un proxy que contiene esta política.

Nombre del error Causa Corregir
SourceNotConfigured Uno o más de los siguientes elementos de la política ValidateSAMLAssertion no están definidos o están vacíos: <Source>, <XPath>, <Namespaces>, <Namespace>.
TrustStoreNotConfigured Si el elemento <TrustStore> está vacío o no se especifica en la política ValidateSAMLAssertion, falla la implementación del proxy de API. Se requiere un almacenamiento de confianza válido.
NullKeyStoreAlias La implementación del proxy de API fallará si el elemento secundario <Alias> está vacío o no se especifica en el elemento <Keystore> de la política GenerateSAMLAssertion. Se requiere un alias del almacén de claves válido.
NullKeyStore La implementación del proxy de API fallará si el elemento secundario <Name> está vacío o no se especifica en el elemento <Keystore> de la política GenerateSAMLAssertion. Se requiere el nombre de almacén de claves válido.
NullIssuer Si el elemento <Issuer> está vacío o no se especifica en la política GenerateSAMLAssertion, falla la implementación del proxy de API. Se requiere un valor válido de <Issuer>.

Variables con fallas

Estas variables se configuran cuando se genera un error de entorno de ejecución. Para obtener más información, consulta Qué debes saber sobre los errores de la política.

Variables Donde Ejemplo
fault.name="fault_name" fault_name es el nombre de la falla . El nombre de la falla es la última parte del código de la falla. fault.name = "InvalidMediaTpe"
GenerateSAMLAssertion.failed Para la configuración de una política de confirmación de SAML validada, el prefijo de error es ValidateSAMLAssertion. GenerateSAMLAssertion.failed = true

Ejemplo de respuesta de error

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

Ejemplo de regla de falla

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

Temas relacionados

Extrae variables: política de extracción de variables