Esta página se ha traducido con Cloud Translation API.

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 aserción SAML
El tipo de política SAML permite que los proxies de API validen las aserciones SAML que se adjuntan a las solicitudes SOAP entrantes. La política SAML valida los mensajes entrantes que contienen una aserción SAML firmada digitalmente, los rechaza si no son válidos y define variables que permiten que otras políticas o los propios servicios backend validen la información de la aserción.
Generación de tokens salientes: Generar política de aserción SAML
El tipo de política SAML permite que los proxies de API adjunten aserciones SAML a solicitudes XML salientes. Esas aserciones están disponibles para permitir que los servicios de backend apliquen un procesamiento de seguridad adicional para la autenticación y la autorización.

Esta política es una política extensible y su uso puede tener implicaciones en cuanto a costes o utilización, en función de tu licencia de Apigee. Para obtener información sobre los tipos de políticas y las implicaciones de uso, consulta Tipos de políticas.

Ejemplos

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

Generar una aserción SAML

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

Validar una aserción SAML

Referencia de elemento

Generar aserción SAML

Nombre del campo	Descripción
Atributo `name`	El nombre de la instancia de la política. El nombre debe ser único en la organización. Solo puedes usar los siguientes caracteres en el nombre: `A-Z0-9._\-$ %`. Sin embargo, la interfaz de usuario de Apigee aplica restricciones adicionales, como eliminar automáticamente los caracteres que no son alfanuméricos.
Atributo `ignoreContentType`	Valor booleano que puede ser `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 se asigna el valor `true`, el mensaje se tratará como XML independientemente del tipo de contenido.
`Issuer`	Identificador único del proveedor de identidades. Si está presente el atributo opcional `ref`, el valor de Issuer se asignará en el tiempo de ejecución en función de la variable especificada. Si no se incluye el atributo opcional `ref`, se usará el valor de Issuer.
`KeyStore`	El nombre del almacén de claves que contiene la clave privada y el alias de la clave privada utilizada para firmar digitalmente las aserciones SAML.
`OutputVariable`
`FlowVariable`
`Message`	El objetivo de la política. Los valores válidos son `message`, `request` y `response`. Si se le asigna el valor `message`, la política recupera de forma condicional el objeto de mensaje en función del punto de adjunto de la política. Cuando se asocia al flujo de solicitud, la política resuelve `message` en la solicitud. Cuando se asocia al flujo de respuesta, la política resuelve `message` en la respuesta.
`XPath`	Una expresión XPath que indica el elemento del documento XML saliente al que la política adjuntará la aserción SAML.
`SignatureAlgorithm`	SHA1 o SHA256
`Subject`	Identificador único del asunto de la aserción SAML. Si se incluye el atributo opcional `ref`, el valor de Subject se asignará en el tiempo de ejecución en función de la variable especificada. Si se incluye el atributo opcional `ref`, se usará el valor de Subject.
`Template`	Si está presente, la aserción se generará ejecutando esta plantilla, sustituyendo todo lo que se indica con `{}` por la variable correspondiente y, a continuación, firmando digitalmente el resultado. La plantilla se procesa siguiendo las reglas de la política AssignMessage. Consulta la política AssignMessage. El elemento `<Template>` admite la función de sustitución de cadenas dinámicas llamada plantillas de mensajes. Las plantillas de mensajes solo se admiten cuando la firma de la política es `GenerateSamlAssertion`.

Validar la aserción SAML

Nombre del campo	Descripción
Atributo `name`	El nombre de la instancia de la política. El nombre debe ser único en la organización. Solo puedes usar los siguientes caracteres en el nombre: `A-Z0-9._\-$ %`. Sin embargo, la interfaz de usuario de Apigee aplica restricciones adicionales, como la eliminación automática de caracteres que no sean alfanuméricos.
Atributo `ignoreContentType`	Valor booleano que puede ser `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 se asigna el valor `true`, el mensaje se tratará como XML independientemente del tipo de contenido.
`Source`	El objetivo de la política. Los valores válidos son `message`, `request` y `response`. Si se le asigna el valor `message`, la política recupera de forma condicional el objeto de mensaje en función del punto de adjunto de la política. Cuando se asocia al flujo de solicitud, la política resuelve `message` en `request`. Cuando se asocia al flujo de respuesta, la política resuelve `message` en `response`.
`XPath`	Obsoleta. Hijo/a de `Source`. Utiliza `AssertionXPath` y `SignedElementXPath`.
`AssertionXPath`	Hijo/a de `Source`. Una expresión XPath que indica el elemento del documento XML entrante del que la política puede extraer la aserción SAML.
`SignedElementXPath`	Hijo/a de `Source`. Una expresión XPath que indica el elemento del documento XML entrante del que la política puede extraer el elemento firmado. Puede ser diferente o igual al XPath de `AssertionXPath`.
`TrustStore`	Nombre del almacén de confianza que contiene los certificados X.509 de confianza que se usan para validar las firmas digitales de las aserciones SAML.
`RemoveAssertion`	Valor booleano que puede ser `true` o `false`. Cuando `true`, la aserción SAML se eliminará del mensaje de solicitud antes de que se reenvíe al servicio 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 en formato XML para la autenticación y la autorización.

Una "afirmación de seguridad" es un token de confianza que describe un atributo de una aplicación, un usuario de una aplicación u otro participante en una transacción. Las aserciones de seguridad se gestionan y consumen mediante dos tipos de entidades:

Proveedores de identidades: 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 identidades.

La plataforma de APIs puede actuar como proveedor de identidades y como proveedor de servicios. Actúa como proveedor de identidad generando aserciones y adjuntándolas a los mensajes de solicitud, lo que permite que los servicios de backend procesen esas aserciones. Actúa como proveedor de servicios validando las aserciones en los mensajes de solicitud entrantes.

El tipo de política SAML admite aserciones SAML que coinciden con la versión 2.0 de la especificación SAML Core y la versión 1.0 de la especificación WS-Security SAML Token Profile.

Generar aserción SAML

Procesamiento de las políticas:

Si el mensaje no es XML e IgnoreContentType no está definido como true, se producirá un error.
Si se ha definido "Template", procesa la plantilla como se describe en la política AssignMessage. Si faltan variables y no se ha definido IgnoreUnresolvedVariables, se producirá un error.
Si no se ha definido "Template", crea una aserción que incluya los valores de los parámetros Subject e Issuer o sus referencias.
Firma la aserción con la clave especificada.
Añade la aserción al mensaje en el XPath especificado.

Validar la aserción SAML

Procesamiento de las políticas:

La política comprueba el mensaje entrante para verificar que el tipo de contenido multimedia de la solicitud es XML. Para ello, comprueba si el tipo de contenido coincide con los formatos text/(.*+)?xml o application/(.*+)?xml. Si el tipo de contenido multimedia no es XML y <IgnoreContentType> no se ha definido, la política generará un error.
La política analizará el XML. Si el análisis falla, se producirá un error.
La política extraerá el elemento firmado y la aserción mediante los XPaths respectivos especificados (<SignedElementXPath> y <AssertionXPath>). Si alguno de estos elementos no devuelve un elemento, la política generará un error.
La política verificará que la aserción sea la misma que el elemento firmado o que sea un elemento secundario del elemento firmado. Si no es así, la política generará un error.
Si alguno de los elementos <NotBefore> o <NotOnOrAfter> está presente en la aserción, la política comprobará la marca de tiempo actual con estos valores, tal como se describe en la sección 2.5.1 de SAML Core.
La política aplicará las reglas adicionales para procesar las "Condiciones" tal como se describe en la sección 2.5.1.1 de SAML Core.
La política validará la firma digital XML mediante los valores de <TrustStore> y <ValidateSigner>, tal como se ha descrito anteriormente. Si la validación falla, la política generará un error.

Una vez que la política se haya completado sin generar ningún error, el desarrollador del proxy podrá tener la certeza de lo siguiente:

La firma digital de la aserción es válida y la ha firmado una autoridad de certificación de confianza.
La aserción es válida durante el periodo actual
El asunto y el emisor de la aserción se extraerán y se definirán en variables de flujo. Es responsabilidad de otras políticas usar estos valores para la autenticación adicional, como comprobar que el nombre del asunto es válido o pasarlo a un sistema de destino para su validación.

Se pueden usar otras políticas, como ExtractVariables, para analizar el XML sin formato de la aserción para realizar validaciones más complejas.

Variables de flujo

Hay muchos datos que se pueden especificar en una aserción SAML. La aserción SAML es un archivo XML que se puede analizar con la política ExtractVariables y otros mecanismos para implementar validaciones más complejas.

Variable	Descripción
`saml.id`	El ID de la aserción SAML
`saml.issuer`	El "Emisor" de la aserción, convertido de su tipo XML nativo a una cadena
`saml.subject`	El "Subject" de la aserción, convertido de su tipo XML nativo a una cadena
`saml.valid`	Devuelve true o false en función del resultado de la comprobación de validez.
`saml.issueInstant`	IssueInstant
`saml.subjectFormat`	Formato del asunto
`saml.scmethod`	Método de confirmación del sujeto
`saml.scdaddress`	Dirección de datos de confirmación del asunto
`saml.scdinresponse`	Datos de confirmación del asunto en la respuesta
`saml.scdrcpt`	Destinatario de datos de confirmación de 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 error y los mensajes de error que devuelve Apigee, así como las variables de error que se definen cuando esta política activa un error. Es importante que conozcas esta información si vas a desarrollar reglas de errores para gestionarlos. Para obtener más información, consulta Qué debes saber sobre los errores de políticas y Cómo gestionar los fallos.

Errores de implementación

Estos errores pueden producirse al implementar un proxy que contenga esta política.

Nombre del error	Causa	Solucionar
`SourceNotConfigured`	No se ha definido o está vacío uno o varios de los siguientes elementos de la política `ValidateSAMLAssertion`: `<Source>`, `<XPath>`, `<Namespaces>` y `<Namespace>`.
`TrustStoreNotConfigured`	Si el elemento `<TrustStore>` está vacío o no se especifica en la política `ValidateSAMLAssertion`, se produce un error en la implementación del proxy de API. Se necesita un almacén de confianza válido.
`NullKeyStoreAlias`	Si el elemento secundario `<Alias>` está vacío o no se especifica en el elemento `<Keystore>` de la política `GenerateSAMLAssertion`, se producirá un error en la implementación del proxy de la API. Es obligatorio indicar un alias de almacén de claves válido.
`NullKeyStore`	Si el elemento secundario `<Name>` está vacío o no se especifica en el elemento `<Keystore>` de la política `GenerateSAMLAssertion`, se producirá un error en la implementación del proxy de la API. Es obligatorio indicar un 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`, se produce un error en la implementación del proxy de API. Se requiere un valor `<Issuer>` válido.

Variables de error

Estas variables se definen cuando se produce un error de tiempo de ejecución. Para obtener más información, consulta el artículo Información sobre los errores de las políticas.

Variables	Dónde	Ejemplo
`fault.name="fault_name"`	`fault_name` es el nombre del fallo. El nombre del error es la última parte del código de error.	`fault.name = "InvalidMediaTpe"`
`GenerateSAMLAssertion.failed`	En el caso de una configuración de política de validación de aserciones SAML, el prefijo de error es `ValidateSAMLAssertion`.	`GenerateSAMLAssertion.failed = true`

Ejemplo de respuesta de error

Nota: Para gestionar los errores, la práctica recomendada es detectar la parte errorcode de la respuesta de error. No te fíes del texto de la faultstring, ya que podría cambiar.

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

Regla de error de ejemplo

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

Temas relacionados

Extracción de variables: Extract Variables policy

Políticas de SAMLAssertion Organízate con las colecciones Guarda y clasifica el contenido según tus preferencias.

Qué

Ejemplos

Generar una aserción SAML

Validar la aserción SAML

Referencia de elemento

Generar aserción SAML

Validar la aserción SAML

Notas de uso

Generar aserción SAML

Validar la aserción SAML

Variables de flujo

Referencia de errores

Errores de implementación

Variables de error

Ejemplo de respuesta de error

Regla de error de ejemplo

Temas relacionados

Políticas de SAMLAssertion