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:

1. Si el mensaje no es XML e IgnoreContentType no está definido como true, se producirá un error.
2. 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.
3. Si no se ha definido "Template", crea una aserción que incluya los valores de los parámetros Subject e Issuer o sus referencias.
4. Firma la aserción con la clave especificada.
5. Añade la aserción al mensaje en el XPath especificado.

Validar la aserción SAML

Procesamiento de las políticas:

1. 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.
2. La política analizará el XML. Si el análisis falla, se producirá un error.
3. 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.
4. 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.
5. 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.
6. 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.
7. 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

This section describes the fault codes and error messages that are returned and fault variables that are set by Apigee when this policy triggers an error. This information is important to know if you are developing fault rules to handle faults. To learn more, see What you need to know about policy errors and Handling faults.

Deployment errors

These errors can occur when you deploy a proxy containing this policy.

Tip: Need help resolving an error? Click in the Fix column for detailed troubleshooting information.

Error name	Cause	Fix
SourceNotConfigured	One or more of the following elements of the ValidateSAMLAssertion policy is not defined or empty: <Source>, <XPath>, <Namespaces>, <Namespace>.
TrustStoreNotConfigured	If the <TrustStore> element is empty or not specified in the ValidateSAMLAssertion policy, then the deployment of the API proxy fails. A valid truststore is required.
NullKeyStoreAlias	If the child element <Alias> is empty or not specified in the <Keystore> element of GenerateSAMLAssertion policy, then the deployment of the API proxy fails. A valid keystore alias is required.
NullKeyStore	If the child element <Name> is empty or not specified in the <Keystore> element of GenerateSAMLAssertion policy, then the deployment of the API proxy fails. A valid keystore name is required.
NullIssuer	If the <Issuer> element is empty or not specified in the GenerateSAMLAssertion policy, then the deployment of the API proxy fails. A valid <Issuer> value is required.

Fault variables

These variables are set when a runtime error occurs. For more information, see What you need to know about policy errors.

Variables	Where	Example
fault.name="fault_name"	fault_name is the name of the fault. The fault name is the last part of the fault code.	fault.name = "InvalidMediaTpe"
GenerateSAMLAssertion.failed	For a validate SAML assertion policy configuration, the error prefix is ValidateSAMLAssertion.	GenerateSAMLAssertion.failed = true

Example error response

Note: For error handling, the best practice is to trap the errorcode part of the error response. Do not rely on the text in the faultstring, because it could change.

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

Example fault rule

<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