Se usó la API de Cloud Translation para traducir esta página.

Configura 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). Puedes usar esta función para propagar atributos de SAML desde un proveedor de identidad a las aplicaciones protegidas por Identity-Aware Proxy (IAP). Cuando propagas atributos de SAML, puedes especificar qué atributos propagar y cómo entregarlos.

Antes de comenzar

Debes tener conocimientos sobre la especificación de Aserciones y Protocolos de SAML V2.0 (PDF).

Cómo se manejan los datos

Antes de habilitar la propagación de atributos SAML, asegúrate de comprender cómoGoogle Cloud administra los datos y qué tipo de información debes y no debes pasar por este canal.

Puedes configurar IAP para que incluya uno o más atributos en la información que proporciona a tus aplicaciones protegidas. Si configuras el SSO a través de un proveedor de identidad externo y tu proveedor de identidad incluye un <AttributeStatement> en la aserción de SAML,Google Cloud almacena temporalmente los atributos asociados con la sesión de la Cuenta de Google de un usuario. Cuando vence una sesión de la Cuenta de Google, un proceso asíncrono quita la información de forma permanente en el plazo de una semana. Puedes configurar la fecha de vencimiento.

No uses la propagación de atributos SAML para la información de identificación personal (PII) sensible, como las credenciales de la cuenta, los números de identificación gubernamentales, los datos de titulares de tarjetas, los datos de cuentas financieras, la información de atención médica o la información sensible de antecedentes.

Habilita la propagación de atributos de SAML

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

Console

En la consola de Google Cloud , ve a la página de IAP.
Ir a IAP
Abre la configuración de un recurso y, luego, desplázate hasta Propagación de atributos.
Selecciona Habilitar la propagación de atributos y, luego, haz clic en Guardar.
En la pestaña SAML Attributes, ingresa los atributos que deseas propagar con el siguiente formato: attribute1, attribute2, attribute3

También puedes ingresar los atributos con una expresión personalizada.Los atributos de tu expresión personalizada se muestran en la pestaña Atributos de SAML. Debes usar el siguiente formato de expresión para que tus atributos se muestren en la pestaña SAML Attributes:
attributes.saml_attributes.filter(attribute, attribute.name in ['attribute', 'attribute2', 'attribute1'])
En Credential types to pass, selecciona al menos un formato de atributo proveniente del IdP para pasarlo a las aplicaciones.

gcloud

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

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

Reemplaza lo siguiente:

FOLDER: Es la carpeta en la que reside tu aplicación.
ORGANIZATION: Es la organización en la que reside tu aplicación.
PROJECT: Es el proyecto en el que reside tu aplicación.
RESOURCE_TYPE: El tipo de recurso
SERVICE: El servicio.
VERSION: Es el 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 de REST

Puedes configurar los atributos SAML para que se propaguen con el objeto ApplicationSettings en IapSettings, 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
}

Cómo configurar las credenciales de salida

Cuando usas la propagación de atributos de SAML, puedes enviar atributos a través de varios medios, incluidos los tokens web JSON (JWT) y los encabezados, configurando credenciales de salida. Para establecer 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"]

Cómo filtrar atributos de SAML con Common Expression Language

Puedes usar funciones de Common Expression Language (CEL) para filtrar atributos de 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 1,000 caracteres.

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

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

Función	Ejemplo	Descripción
Selección de campos	`a.b`	Selecciona el campo `b` del archivo .proto `a`. El carácter `b` puede ser otro .proto, una lista o un tipo de valor simple, como una cadena.
Cómo filtrar listas	`list.Filter(iter_var, condition)`	Devuelve un subconjunto de `list` en el que los elementos cumplen con `condition`.
Membresía de la lista	`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"`.
append	`list.append(attribute)`	Agrega el atributo determinado a la lista determinada.
estrictas	`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 determinado con el nombre `"new_name"` para todas las credenciales de salida seleccionadas.

Ejemplo de expresión CEL

Supongamos una aserción de 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 en 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 del atributo

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

Ejemplo: Supón una aserción de 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 de 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 se modifican con respecto a las aserciones de SAML proporcionadas.

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

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

Encabezados en una aserción de SAML

En los encabezados, los valores de los atributos, las claves y los nombres se escapan según la 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 los encabezados de IAP, cada encabezado contiene el prefijo de IAP x-goog-iap-attr-. Por motivos de seguridad, el balanceador de cargas quita los encabezados de solicitud que tengan el prefijo x-goog-iap-attr. Esto garantiza que los encabezados que recibe la app se generen a partir de la IAP.

En el ejemplo de aserción de SAML, el encabezado se ve de la siguiente manera:

"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 cuando propaga 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 de encabezado con caracteres de escape:

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

Personaliza 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 del encabezado para algunos atributos y seleccionar atributos nuevos proporcionados por las IAP.

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

IAP proporciona los siguientes atributos: user_email, device_id y timestamp.

Ejemplos

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

Supongamos la aserción de 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 agregar un atributo a una lista de atributos. Debes seleccionar este atributo de una de las listas de atributos de IAP admitidas. Por ejemplo, para agregar my_saml_attr_2 a una lista que contiene 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 agregar "my_saml_attr_2" a la lista de filtros. También puedes agregar varios atributos y encadenarlos a una lista, 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"))

Agregar 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 modo que IAP no anteponga el prefijo x-goog-iap-attr- al nombre. Esto es útil cuando el nombre de un atributo debe ser exacto para la aplicación de backend. Ejemplo:

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

emitAs

Usa la función emitAs para especificar un nombre nuevo para el atributo. El nombre que especifiques se generará en 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")

Puedes usar las distintas funciones para personalizar atributos para casos de uso específicos. Por ejemplo, puedes usar la siguiente expresión para propagar el correo electrónico de un usuario desde los atributos de IAP como "SM_USER" junto con otros atributos de 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 se verán de la siguiente manera:

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

Restricciones cuando se usa la propagación de atributos SAML

Al acceder, los atributos entrantes del proveedor de identidad 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 fallará el acceso.

La mayoría de los servidores web tienen un límite de tamaño de solicitud de 8 KB. Esto limita el tamaño de los atributos personalizados salientes, lo que incluye la duplicación de atributos en los encabezados. Si el tamaño de los atributos (nombre más valores) supera los 5,000 bytes cuando se duplica y codifica, IAP rechaza la solicitud y devuelve el código de error 401 de IAP.

Caracteres Unicode en la propagación de atributos de SAML

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