Políticas de SAMLAssertion

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

Consulta la documentación de Apigee Edge.

Qué

Autenticación y autorización entrantes: Valida la política de aserciones de SAML
El tipo de política de SAML permite que los proxies de API validen las aserciones de SAML adjuntas a las solicitudes de 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.
Generación de tokens de salida: Genera una política de aserciones de SAML
El tipo de política de SAML permite que los proxies de API adjunten aserciones de SAML para solicitudes XML salientes. Esas aserciones están disponibles para permitir que los servicios de backend apliquen más procesos de seguridad para la autenticación y la autorización.

Esta política es una política extensible, y el uso de esta 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

Genera una aserción de 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>

Genera una aserción de SAML

Valida la aserción de 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>

Valida una aserción de SAML

Referencia del elemento

Genera una 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 generará si el tipo de contenido del mensaje no es un tipo de contenido XML. Si el valor es `true`, el mensaje se tratará como XML independientemente del tipo de contenido.
`Issuer`	Es el identificador único del proveedor de identidad. Si el atributo `ref` opcional está presente, el valor de la entidad emisora se asignará en el entorno de ejecución en función de la variable especificada. Si el atributo opcional `ref` no está presente, se usará el valor de la entidad emisora.
`KeyStore`	El nombre del KeyStore que contiene la clave privada y el alias de la clave privada que se usa para firmar las afirmaciones SAML de manera digital.
`OutputVariable`
`FlowVariable`
`Message`	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` para solicitar y, cuando se adjunta al flujo de respuesta, la política resuelve `message` como respuesta.
`XPath`	Una expresión XPath que indica el elemento del documento XML saliente al que la política adjuntará la aserción de SAML.
`SignatureAlgorithm`	SHA1 o SHA256
`Subject`	El identificador único del sujeto de la aserción SAML. Si el atributo opcional `ref` está presente, el valor de asunto se asignará en el tiempo de ejecución según la variable especificada. Si el atributo opcional `ref`está presente, se usará el valor del asunto.
`Template`	Si está presente, la aserción se generará mediante la ejecución de esta plantilla, y reemplazará todo lo que indica `{}` con la variable correspondiente y, luego, firmará el resultado de manera digital. La plantilla se procesa según las reglas de la política de AssignMessage. Consulta Política AssignMessage. El elemento `<Template>` admite la función de sustitución dinámica de string llamada plantillas de mensajes. La plantilla de mensajes solo se admite cuando la firma de la política es `GenerateSamlAssertion`.

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 generará si el tipo de contenido del mensaje no es un tipo de contenido XML. 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

La especificación del Lenguaje de marcado para confirmaciones de seguridad (SAML) define formatos y protocolos que permiten a las aplicaciones intercambiar información con formato XML para la autenticación y la autorización.

Una “aserción de seguridad” es un token de confianza que describe el atributo de una app, un usuario de la app o algún otro participante en una transacción. Dos tipos de entidades administran y consumen las aserciones de seguridad:

Proveedores de identidad: Generan aserciones de seguridad en nombre de los participantes
Proveedores de servicios: Validan las aserciones de seguridad a través de relaciones de confianza con proveedores de identidad

La plataforma de API puede actuar como un proveedor de identidad y como proveedor de servicios. Actúa como un proveedor de identidad mediante la generación de aserciones y los adjunta para solicitar mensajes, lo que hace que estén disponibles para que los servicios de backend las procesen. Funciona como un proveedor de servicios mediante la validación de las aserciones en los mensajes de solicitudes entrantes.

El tipo de política de SAML admite aserciones de SAML que coinciden con la versión 2.0 de la Especificación principal de SAML y la versión 1.0 de la especificación del perfil de token de SAML de WS-Security.

Genera una aserción de SAML

Procesamiento de políticas:

Si el mensaje no es XML y IgnoreContentType no está configurado en true, se genera un error.
Si la opción "Plantilla" está configurada, procesa la plantilla como se describe para la política AssignMessage. Si falta alguna variable y no se configura IgnoreUnresolvedVariables se, genera un error.
Si la "Plantilla" no está configurada, crea una aserción que incluya los valores de los parámetros Asunto y Emisor o sus referencias.
Firma la aserción mediante la clave especificada.
Agrega la aserción al mensaje en la XPath especificada.

Valida la aserción de SAML

Procesamiento de políticas:

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 no se configuró <IgnoreContentType>, la política mostrará una falla.
La política analizará el XML. Si no se realiza correctamente el análisis, se producirá un error.
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.
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.
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.
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.
La política validará la firma digital XML mediante los valores de <TrustStore> y <ValidateSigner> como se describió antes. 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

Nota: Para controlar errores, se recomienda capturar la parte errorcode de la respuesta de error. No dependas del texto en la faultstring, ya que podría cambiar.

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