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

Configurar la propagación de atributos de SAML

En esta página se describe cómo habilitar y usar la propagación de atributos del lenguaje de marcado para confirmaciones de seguridad (SAML). Puede usar esta función para propagar atributos SAML desde un proveedor de identidades a aplicaciones protegidas por Identity-Aware Proxy (IAP). Cuando propagas atributos SAML, puedes especificar qué atributos quieres propagar y cómo quieres enviarlos.

Antes de empezar

Debes conocer la especificación de aserciones y protocolos de SAML V2.0 (PDF).

Cómo se tratan los datos

Antes de habilitar la propagación de atributos SAML, asegúrate de que entiendes cómo gestiona los datosGoogle Cloud y qué tipo de información debes y no debes enviar a través de este canal.

Puedes configurar las compras en la aplicación para que incluyan uno o varios atributos en la información que proporciona a tus aplicaciones protegidas. Si configuras el SSO a través de un proveedor de identidades externo y tu proveedor de identidades incluye un <AttributeStatement> en la aserción de SAML,Google Cloud almacenará temporalmente los atributos asociados a la sesión de la cuenta de Google de un usuario. Cuando caduca la sesión de una cuenta de Google, un proceso asíncrono elimina la información de forma permanente en el plazo de una semana. Puedes configurar la fecha de vencimiento.

No utilices la propagación de atributos SAML para la información personal identificable sensible, como credenciales de cuentas, números de identificación oficiales, datos de titulares de tarjetas, datos de cuentas financieras, información sanitaria o datos sensibles.

Habilitar la propagación de atributos de SAML

Para habilitar la propagación de atributos SAML, crea un perfil de SSO en Google Workspace y, a continuación, actualiza la configuración de IAP con la CLI de Google Cloud o la API REST.

Consola

En la consola de Google Cloud , ve a la página IAP.
Ir a IAP
Abre la configuración de un recurso y, a continuación, desplázate hasta Propagación de atributos.
Seleccione Habilitar propagación de atributos y, a continuación, haga clic en Guardar.
En la pestaña Atributos SAML, introduce los atributos que quieras propagar con el siguiente formato: attribute1, attribute2, attribute3

También puedes introducir los atributos mediante una expresión personalizada.Los atributos de tu expresión personalizada se muestran en la pestaña Atributos SAML. Debes usar el siguiente formato de expresión para que tus atributos se muestren en la pestaña Atributos SAML:
attributes.saml_attributes.filter(attribute, attribute.name in ['attribute', 'attribute2', 'attribute1'])
En Tipos de credenciales que se van a transferir, selecciona al menos un formato de atributo del proveedor de identidades que se va a transferir a las aplicaciones.

gcloud

Ejecuta los siguientes comandos de la CLI de gcloud de IAP para actualizar la configuración de propagación de atributos SAML:

gcloud iap settings set SETTING_FILE [--folder=FOLDER --organization=ORGANIZATION --project=PROJECT> --resource-type=RESOURCE_TYPE --service=SERVICE --version=VERSION] [GCLOUD_WIDE_FLAG …]

Haz los cambios siguientes:

FOLDER: la carpeta en la que se encuentra tu aplicación.
ORGANIZATION: la organización en la que reside tu aplicación.
PROJECT: el proyecto en el que reside tu aplicación.
RESOURCE_TYPE: el tipo de recurso.
SERVICE: el servicio.
VERSION: número de versión.

YAML:

applicationSettings:
 attributePropagationSettings:
  expression: CEL_EXPRESSION
  outputCredentials: ARRAY[OUTPUT_CREDENTIALS]
  enable: BOOLEAN

JSON:

{
   "application_settings":{
      "attribute_propagation_settings": {
        "expression": CEL_EXPRESSION,
        "output_credentials": ARRAY[OUTPUT_CREDENTIALS]
        "enable": BOOLEAN
      }
   }
}

API REST

Puede configurar los atributos SAML para que se propaguen mediante el objeto ApplicationSettings en IapSettings, tal como se muestra en los siguientes ejemplos:

{
 "csmSettings": {
    object (CsmSettings)
  },
  "accessDeniedPageSettings": {
    object (AccessDeniedPageSettings)
  },
 "attributePropagationSettings": {
    object (AttributePropagationSettings)
  },
  "cookieDomain": string,
}

AttributePropagationSettings

{
 "expression": string,
 "output_credentials": array
 "enable": boolean
}

Configurar las credenciales de salida

Cuando se usa la propagación de atributos SAML, se pueden enviar atributos a través de varios medios, como tokens web JSON (JWT) y encabezados, configurando las credenciales de salida. Para definir las credenciales en la API, puedes especificar una lista de cadenas separadas por comas, como se muestra en el siguiente ejemplo:

"output_credentials": ["HEADER", "JWT", "RCTOKEN"]

Filtrar atributos SAML con el lenguaje de expresión común

Puedes usar funciones del lenguaje de expresión común (CEL) para filtrar atributos SAML.

El uso de expresiones CEL con la propagación de atributos SAML tiene las siguientes limitaciones:

Una expresión debe devolver una lista de atributos.
Una expresión puede seleccionar un máximo de 45 atributos.
Una cadena de expresión no puede superar los 1000 caracteres.

A continuación, se indican las funciones de CEL que se admiten al usar la función de propagación de atributos SAML de IAP.

Ten en cuenta que las funciones distinguen entre mayúsculas y minúsculas, y deben usarse exactamente como se escriben. El orden de las funciones strict y emitAs no importa al encadenar llamadas a funciones.

Función	Ejemplo	Descripción
Selección de campos	`a.b`	Selecciona el campo `b` del proto `a`. El carácter `b` puede ser otro proto, una lista o un tipo de valor simple, como una cadena.
Filtrar listas	`list.Filter(iter_var, condition)`	Devuelve un subconjunto de `list` en el que los elementos cumplen `condition`.
Mostrar suscripción	`a` en `b`	Devuelve `true` si el valor `a` es miembro de la lista `b`.
selectByName	`list.selectByName("name")`	En la lista, selecciona el atributo en el que `name = "name"`.
añadir	`list.append(attribute)`	Añade el atributo especificado a la lista indicada.
strict	`attribute.strict()`	Emite el atributo sin el prefijo `x-goog-iap-attr-` cuando se usa `HEADERS` como credencial de salida.
emitAs	`attribute.emitAs("new_name")`	Genera el atributo indicado con el nombre `"new_name"` en todas las credenciales de salida seleccionadas.

Ejemplo de expresión CEL

Supongamos una aserción SAML:

<saml2:AttributeStatement xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
  <saml2:Attribute Name="my_saml_attr_1">
    <saml2:AttributeValue xsi:type="xsd:string">value_1</saml2:AttributeValue>
    <saml2:AttributeValue xsi:type="xsd:string">value_2</saml2:AttributeValue>
  </saml2:Attribute>
 <saml2:Attribute Name="my_saml_attr_2">
    <saml2:AttributeValue xsi:type="xsd:string">value_3</saml2:AttributeValue>
    <saml2:AttributeValue xsi:type="xsd:string">value_4</saml2:AttributeValue>
  </saml2:Attribute>
 <saml2:Attribute Name="my_saml_attr_3">
    <saml2:AttributeValue xsi:type="xsd:string">value_5</saml2:AttributeValue>
    <saml2:AttributeValue xsi:type="xsd:string">value_6</saml2:AttributeValue>
  </saml2:Attribute>
</saml2:AttributeStatement>

Para seleccionar my_saml_attr_1, usa la siguiente expresión CEL:

attributes.saml_attributes.filter(attribute, attribute.name in ["my_saml_attr_1"])

Para seleccionar my_saml_attr_1 y my_saml_attr_2, usa la siguiente expresión CEL:

attributes.saml_attributes.filter(attribute, attribute.name in ["my_saml_attr_1", "my_saml_attr_2"])

Formato de atributo

Todos los atributos seleccionados se duplican por completo en todas las credenciales de salida seleccionadas.

Ejemplo: Supongamos una aserción SAML

<saml2:AttributeStatement xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
  <saml2:Attribute Name="my_saml_attr_1">
    <saml2:AttributeValue xsi:type="xsd:string">value_1</saml2:AttributeValue>
    <saml2:AttributeValue xsi:type="xsd:string">value_2</saml2:AttributeValue>
  </saml2:Attribute>
</saml2:AttributeStatement>

Token JWT y RC

El token JWT proporciona los atributos a través del campo additional_claims. El campo es un objeto y contiene una asignación de los nombres de los atributos a una lista de los valores de los atributos. Los nombres de los atributos no han cambiado con respecto a las aserciones SAML proporcionadas.

En el ejemplo de aserción SAML, el JWT de IAP contiene lo siguiente:

{
  "additional_claims": {
    "my_saml_attr_1": ["value_1", "value_2"]
  }
}

Encabezados de una aserción SAML

En los encabezados, los valores de los atributos, las claves y los nombres se escapan mediante URL de acuerdo con RFC 3986 y se unen con comas. Por ejemplo, header&name: header$value se convierte en x-goog-iap-attr-header%26name: header%24value.

Para identificar de forma única las cabeceras de IAP, cada cabecera contiene el prefijo IAP x-goog-iap-attr-. Por motivos de seguridad, el balanceador de carga elimina los encabezados de solicitud que tengan el prefijo x-goog-iap-attr. De esta forma, se asegura de que los encabezados que recibe la aplicación se generen mediante IAP.

En la aserción SAML de ejemplo, el encabezado tiene el siguiente aspecto:

"x-goog-iap-attr-my_saml_attr_1": "value_1,value_2"

En el siguiente ejemplo se muestra cómo IAP escapa los caracteres especiales al propagar atributos en encabezados, como value&1, value$2 y value,3:

"x-goog-iap-attr-my_saml_attr_1": "value%261,value%242,value%2C3"

A continuación se muestra un ejemplo de cómo se escapa un nombre de encabezado.

Nombre del encabezado:

"iap,test,3": "iap_test3_value1,iap_test3_value2"

Nombre del encabezado con caracteres de escape:

"X-Goog-IAP-Attr-iap%2Ctest%2C3": "iap_test3_value1,iap_test3_value2"

Personalizar atributos

Puedes usar las funciones selectByName, append, strict y emitas para modificar los nombres de los atributos propagados, especificar si se debe usar el prefijo de encabezado en algunos atributos y seleccionar nuevos atributos proporcionados por las compras en la aplicación.

Si no necesitas la propagación de atributos SAML, pero sí la dirección de correo electrónico, el ID de dispositivo o la marca de tiempo en un campo SM_USER, puedes seleccionar esos atributos en iap_attributes list: attributes.iap_attributes…

Compras en la aplicación proporciona los siguientes atributos: user_email, device_id y timestamp.

Ejemplos

En los siguientes ejemplos se muestra cómo personalizar atributos mediante las funciones selectByName, append, strict y emitas.

Supongamos la aserción SAML de ejemplo.

selectByName

Usa la función selectByName para seleccionar un solo atributo de una lista determinada por su nombre. Por ejemplo, para seleccionar my_saml_attr_1, usa la siguiente expresión:

attributes.saml_attributes.selectByName("my_saml_attr_1")

append

Usa la función append para añadir un atributo a una lista de atributos. Debe seleccionar este atributo de una de las listas de atributos de compras en la aplicación admitidas. Por ejemplo, para añadir my_saml_attr_2 a una lista que contenga my_saml_attr_1, usa la siguiente expresión:

attributes.saml_attributes.filter(x, x.name in ["my_saml_attr_1"]).append(attributes.saml_attributes.selectByName("my_saml_attr_2"))

Puedes añadir "my_saml_attr_2" a la lista de filtros. También puedes añadir varios atributos y añadirlos a una lista encadenando las adiciones, como en el siguiente ejemplo:

attributes.saml_attributes.filter(x, x.name in ["my_saml_attr_1"]).append(
attributes.saml_attributes.selectByName("my_saml_attr_2")).append(
attributes.saml_attributes.selectByName("my_saml_attr_3"))

Añadir atributos individuales es más útil cuando se combina con las funciones strict y emitAs.

strict

Usa la función strict para marcar un atributo de forma que la compra en la aplicación no añada el prefijo x-goog-iap-attr- al nombre. Esto resulta útil cuando el nombre de un atributo debe ser exacto para la aplicación backend. Ejemplo:

attributes.saml_attributes.selectByName("my_saml_attr_1").strict()

emitAs

Usa la función emitAs para especificar un nuevo nombre para el atributo. El nombre que especifiques se asignará a todas las credenciales. Por ejemplo, para cambiar el nombre de my_saml_attr_1 a custom_name, usa la siguiente expresión:

attributes.saml_attributes.selectByName("my_saml_attr_1").emitAs("custom_name")

Puede usar las distintas funciones para personalizar los atributos en casos prácticos específicos. Por ejemplo, puedes usar la siguiente expresión para propagar el correo de un usuario desde los atributos de IAP como "SM_USER" junto con otros atributos SAML:

attributes.saml_attributes.filter(x, x.name in ["my_saml_attr_1"]).append(
attributes.iap_attributes.selectByName("user_email").emitAs("SM_USER").strict())

Los encabezados de salida tienen el siguiente aspecto:

"x-goog-iap-attr-my_saml_attr_1": "value_1,value_2"
"SM_USER": "email@domain.com"

Restricciones al usar la propagación de atributos SAML

Al iniciar sesión, los atributos entrantes del proveedor de identidades tienen un límite de 2 KB de datos de atributos SAML. Las aserciones que superen el máximo de 2 KB se rechazarán y el inicio de sesión fallará.

La mayoría de los servidores web tienen un límite de tamaño de solicitud de 8 KB. De esta forma, se limita el tamaño de los atributos personalizados salientes, incluidos los atributos duplicados en los encabezados. Si el tamaño de los atributos (nombre más valores) supera los 5000 bytes cuando se duplican y se codifican, IAP rechaza la solicitud y devuelve el código de error 401 de IAP.

Caracteres Unicode en la propagación de atributos SAML

Esta función no admite caracteres Unicode ni UTF-8, por lo que los valores de los atributos deben ser cadenas de ASCII bajo. Si una aserción no es baja de ASCII, el inicio de sesión falla.