Políticas de SAMLAssertion

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

Consulta la documentación de Apigee Edge.

ícono de política

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 refestá 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.

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:

  1. Si el mensaje no es XML y IgnoreContentType no está configurado en true, se genera un error.
  2. 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.
  3. Si la "Plantilla" no está configurada, crea una aserción que incluya los valores de los parámetros Asunto y Emisor o sus referencias.
  4. Firma la aserción mediante la clave especificada.
  5. Agrega la aserción al mensaje en la XPath especificada.

Valida la aserción de SAML

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 no se configuró <IgnoreContentType>, 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 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

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