Estás viendo la documentación de Apigee Edge.
Ve a la
Documentación de Apigee X. información
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.
Ejemplos
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="test">http://www.example.com/test</Namespace> </Namespaces> <XPath>/envelope/header</XPath> </Message> </OutputVariable> <SignatureAlgorithm /> <Subject ref="reference">Subject name</Subject> <Template ignoreUnresolvedVariables="false"> <!-- A lot of XML goes here, in 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 administración aplica restricciones adicionales, como
quita 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.
|
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 administración aplica restricciones adicionales, como
quitando 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 para solicitar y, cuando se adjunta al flujo de respuesta, la política resuelve message como respuesta. |
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. Esta
puede ser diferente o igual a la XPath del 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 verifica el mensaje entrante para verificar que el tipo de medio de la solicitud sea XML. Para ello,
comprobar si el tipo de contenido coincide con los formatos
text/(.*+)?xml
oapplication/(.*+)?xml
Si el tipo de medio no es XML<IgnoreContentType>
no se establece, la política generará 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 con las XPaths respectivas
especificado (
<SignedElementXPath>
y<AssertionXPath>
). Si cualquiera de estas rutas no devuelve un elemento, la política generará una falla. - La política verificará que la aserción sea la misma que el elemento firmado. es un elemento secundario del elemento firmado. Si este no es el caso, la política generará una falla.
- Si cualquiera de los valores de
<NotBefore>
o<NotOnOrAfter>
están presentes en la aserción, la política verificará la marca de tiempo actual en estos valores, como se describe en la sección 2.5.1 de SAML Core. - La política aplicará cualquier regla adicional para el procesamiento de las "Condiciones". como se describe en la sección 2.5.1.1 de SAML Core.
- La política validará la firma digital XML usando los valores de
<TrustStore>
y<ValidateSigner>
, como 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
This section describes the fault codes and error messages that are returned and fault variables that are set by Edge 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.
Error name | Cause | Fix |
---|---|---|
SourceNotConfigured |
One or more of the following elements of the Validate SAML Assertion
policy is not defined or empty: <Source> , <XPath> ,
<Namespaces> , <Namespace> .
|
build |
TrustStoreNotConfigured |
If the <TrustStore> element is empty or not specified in the
ValidateSAMLAssertion policy, then the deployment of the API proxy fails.
A valid Trust Store is required.
|
build |
NullKeyStoreAlias |
If the child element <Alias> is empty or not specified in the <Keystore>
element of Generate SAML Assertion policy, then the deployment of the API
proxy fails. A valid Keystore alias is required.
|
build |
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.
|
build |
NullIssuer |
If the <Issuer> element is empty or not specified in the Generate SAML
Assertion policy, then the deployment of the API proxy fails. A
valid <Issuer> value is required.
|
build |
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
{ "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
Extrae variables: política de extracción de variables