Configurer la propagation des attributs SAML

Cette page explique comment activer et utiliser le langage Security Assertion Markup Language. (SAML). Vous pouvez utiliser cette fonctionnalité pour propager le protocole SAML d'un fournisseur d'identité aux applications protégées Identity-Aware Proxy (IAP). Lorsque vous propagez des attributs SAML, vous pouvez spécifier les attributs à propager et le mode d'envoi.

Avant de commencer

Pour utiliser la fonctionnalité de propagation des attributs SAML, vous devez disposer d'une licence Chrome Enterprise Premium.

Vous devez connaître la spécification des assertions et des protocoles SAML V2.0.

Comprendre comment les données sont traitées

Avant d'activer la propagation des attributs SAML, assurez-vous de bien comprendre Google Cloud gère les données et le type d'informations à utiliser et ne doivent pas passer par ce canal.

Vous pouvez configurer IAP pour inclure un ou plusieurs attributs les informations qu'il fournit à vos applications protégées. Si vous configurez Authentification unique via une identité tierce fournisseur et votre fournisseur d'identité inclut un <AttributeStatement> dans l'assertion SAML, Google Cloud stocke temporairement les attributs associés aux comptes utilisateur session avec un compte Google. À l'expiration d'une session de compte Google, une commande supprime définitivement ces informations dans un délai d'une semaine. Vous pouvez configurer date d'expiration.

Ne pas utiliser la propagation d'attributs SAML pour les données personnelles sensibles Informations permettant d'identifier l'utilisateur, telles que ses identifiants de compte ou sa pièce d'identité les numéros, les données relatives au titulaire d'une carte, les données de comptes financiers, les informations de santé ou des informations de référence sensibles.

Activer la propagation des attributs SAML

Activez la propagation des attributs SAML en créant un profil SSO dans Google Workspace, puis mettez à jour les paramètres IAP à l'aide de Google Cloud CLI ou de l'API REST.

Console

  1. Dans la console Google Cloud, accédez à la page "IAP".
    Accéder à IAP
  2. Ouvrez les paramètres d'une ressource, puis faites défiler la page jusqu'à Propagation des attributs.
  3. Sélectionnez Activer la propagation des attributs, puis cliquez sur Enregistrer.

  4. Dans l'onglet SAML Attributes (Attributs SAML), saisissez les attributs pour lesquels vous souhaitez se propagent à l'aide du format suivant: attribute1, attribute2, attribute3

    Vous pouvez également saisir les attributs à l'aide d'une expression personnalisée. de votre expression personnalisée sont affichés dans la balise SAML Attributs. Vous devez utiliser le format d'expression suivant pour votre à afficher dans l'onglet SAML Attributes (Attributs SAML) :
    attributes.saml_attributes.filter(attribute, attribute.name in ['attribute', 'attribute2', 'attribute1'])

  5. Pour Types d'identifiants à transmettre, sélectionnez au moins un format d'attribut. provenant du fournisseur d'identité pour les transmettre aux applications.

gcloud

Exécutez les commandes IAP gcloud CLI suivantes pour mettre à jour les paramètres de propagation des attributs SAML:

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

Remplacez les éléments suivants :

  • FOLDER: dossier dans lequel se trouve votre application.
  • ORGANIZATION: organisation dans laquelle réside votre application.
  • PROJECT: projet dans lequel réside votre application.
  • RESOURCE_TYPE: type de ressource.
  • SERVICE: service.
  • VERSION: numéro de version

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

Vous pouvez configurer la propagation des attributs SAML à l'aide de l'objet ApplicationSettings dans IapSettings, comme illustré dans les exemples suivants:

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

AttributePropagationSettings

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

Définir les identifiants de sortie

Lorsque vous utilisez la propagation des attributs SAML, vous pouvez envoyer des attributs sur plusieurs supports, y compris le jeton Web JSON (JWT) et les en-têtes, en définissant des identifiants de sortie. Pour définir les identifiants dans l'API, vous pouvez spécifier une liste de chaînes séparées par une virgule, comme illustré dans l'exemple suivant:

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

Filtrer les attributs SAML à l'aide de Common Expression Language

Vous pouvez filtrer les attributs SAML à l'aide des fonctions CEL (Common Expression Language).

L'utilisation d'expressions CEL avec la propagation d'attributs SAML présente les limites suivantes:

  • Une expression doit renvoyer une liste d'attributs.
  • Une expression peut sélectionner jusqu'à 45 attributs.
  • Une chaîne d'expression ne peut pas dépasser 1 000 caractères.

Vous trouverez ci-dessous les fonctions CEL compatibles avec la fonctionnalité de propagation d'attributs SAML IAP.

Notez que les fonctions sont sensibles à la casse et doivent être utilisées exactement telles qu'elles sont écrites. L'ordre des fonctions strict et emitAs n'a pas d'importance lors du chaînage d'appels de fonction.

Fonction Exemple Description
Sélection des champs a.b Sélectionnez le champ b dans le proto a. Le caractère b peut être un autre proto, une liste ou un type de valeur simple tel que string.
Listes de filtrage list.Filter(iter_var, condition) Renvoie un sous-ensemble de list où les éléments correspondent à condition.
Appartenance à une liste a dans b Renvoie true si la valeur a est membre de la liste b.
selectByName list.selectByName("name") Dans la liste, sélectionnez l'attribut où name = "name".
append list.append(attribute) Ajoute l'attribut donné à la liste donnée.
stricte attribute.strict() Émet l'attribut sans le préfixe x-goog-iap-attr- lorsque HEADERS est utilisé comme identifiant de sortie.
emitAs attribute.emitAs("new_name") Génère l'attribut donné nommé "new_name" pour tous les identifiants de sortie sélectionnés.

Exemple d'expression CEL

Prenons une assertion 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>

Pour sélectionner my_saml_attr_1, utilisez l'expression CEL suivante:

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

Pour sélectionner my_saml_attr_1 et my_saml_attr_2, utilisez l'expression CEL suivante:

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

Format de l'attribut

Tous les attributs sélectionnés sont entièrement dupliqués dans tous les identifiants de sortie sélectionnés.

Exemple: Supposer une assertion 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>

Jeton JWT et jeton RC

Le jeton JWT fournit les attributs via le champ additional_claims. Le champ est un objet et contient une mise en correspondance des noms d'attributs avec une liste de valeurs d'attributs. Les noms d'attributs sont identiques à ceux des assertions SAML fournies.

Pour l'exemple d'assertion SAML, le JWT IAP contient le suivantes:

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

En-têtes dans une assertion SAML

Dans les en-têtes, les valeurs des attributs, des clés et des noms sont échappées au format URL. conformément à la norme RFC 3986 et virgules. Par exemple, header&name: header$value devient x-goog-iap-attr-header%26name: header%24value.

Pour identifier de manière unique les en-têtes IAP, chaque en-tête contient Préfixe IAP x-goog-iap-attr-. Pour des raisons de sécurité, la charge équilibreur de charge supprime tous les en-têtes de requête comportant le préfixe x-goog-iap-attr. Ce garantit que les en-têtes reçus par l'application sont générés par IAP.

Pour l'exemple d'assertion SAML, l'en-tête ressemble à ceci:

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

L'exemple suivant montre comment IAP échappe les règles caractères lors de la propagation d'attributs dans les en-têtes, tels que value&1, value$2, et value,3:

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

Voici un exemple de la façon dont un nom d'en-tête est échappé.

Nom de l'en-tête:

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

Nom d'en-tête avec échappement:

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

Personnaliser les attributs

Vous pouvez utiliser les fonctions selectByName, append, strict et emitas pour : modifier les noms des attributs propagés, indiquer si l'en-tête doit être utilisé ou non pour certains attributs et sélectionner de nouveaux attributs .

Si vous avez besoin de l'adresse e-mail, mais pas de la propagation des attributs SAML, l'identifiant de l'appareil ou le code temporel dans un champ SM_USER, vous pouvez sélectionner ces attributs à partir de iap_attributes list: attributes.iap_attributes...

IAP fournit les attributs suivants: user_email, device_id et timestamp.

Examples

Les exemples suivants montrent comment personnaliser des attributs à l'aide des Fonctions selectByName, append, strict et emitas.

Prenons l'exemple d'exemple d'assertion SAML.

selectByName

Utilisez la fonction selectByName pour sélectionner un seul attribut dans une liste donnée par nom. Par exemple, pour sélectionner my_saml_attr_1, utilisez l'expression suivante:

attributes.saml_attributes.selectByName("my_saml_attr_1")

append

Utilisez la fonction append pour ajouter un attribut à une liste d'attributs. Vous devez sélectionner cet attribut dans l'une des listes d'attributs IAP compatibles. Par exemple, pour ajouter my_saml_attr_2 à une liste contenant my_saml_attr_1, utilisez l'expression suivante:

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

Vous pouvez ajouter "my_saml_attr_2" à la liste de filtrage. Vous pouvez aussi ajouter plusieurs attributs et les ajouter à une liste en enchaînant les ajouts, comme le suivantes:

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"))

L'ajout d'attributs uniques est particulièrement utile lorsqu'il est combiné avec strict et emitAs.

strict

Utilisez la fonction strict pour signaler un attribut afin qu'IAP n'ajoute pas le préfixe x-goog-iap-attr- au nom. Cela s'avère utile lorsqu'un doit être exact pour l'application backend. Exemple :

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

emitAs

Utilisez la fonction emitAs pour spécifier un nouveau nom pour l'attribut. Le nom que vous que vous spécifiez sera généré pour tous les identifiants. Par exemple, pour renommer De my_saml_attr_1 à custom_name, utilisez l'expression suivante:

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

Vous pouvez utiliser les différentes fonctions afin de personnaliser les attributs pour des cas d'utilisation spécifiques. Par exemple, vous pouvez utiliser l'expression suivante pour propager l'adresse e-mail d'un utilisateur à partir des attributs IAP sous forme de "SM_USER" avec d'autres attributs SAML:

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

Les en-têtes de sortie se présentent comme suit:

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

Contraintes lors de l'utilisation de la propagation d'attributs SAML

Lors de la connexion, les attributs entrants provenant du fournisseur d'identité sont limités à 2 Ko de données d'attribut SAML. Les assertions qui dépassent la limite de 2 Ko sont refusées et la connexion échoue.

La plupart des serveurs Web ont une limite de taille de requête de 8 Ko. Cela limite la taille les attributs personnalisés sortants, y compris les attributs dupliqués dans les en-têtes. Si le la taille des attributs (nom et valeurs) dépasse 5 000 octets lorsqu'ils sont dupliqués et codé, IAP rejette la requête et renvoie Code d'erreur IAP 401.

Caractères Unicode dans la propagation des attributs SAML

Cette fonctionnalité n'accepte pas les caractères Unicode et UTF-8. Les valeurs des attributs doivent donc être en caractères ASCII. Si une assertion n'est pas en caractères ASCII, la connexion échoue.