Cette page explique comment activer et utiliser la propagation des attributs SAML (Security Assertion Markup Language). Vous pouvez utiliser cette fonctionnalité pour propager les attributs SAML d'un fournisseur d'identité aux applications protégées par Identity-Aware Proxy (IAP). Lorsque vous propagent des attributs SAML, vous pouvez spécifier ceux à propager et leur mode de diffusion.
Avant de commencer
Pour utiliser la fonctionnalité de propagation des attributs SAML, vous devez disposer d'une licence BeyondCorp Enterprise.
Vous devez connaître la spécification SAML V2.0 Assertions and Protocols.
Comprendre comment les données sont traitées
Avant d'activer la propagation des attributs SAML, assurez-vous de bien comprendre comment Google Cloud gère les données, et le type d'informations que vous devez et ne devez pas transmettre via ce canal.
Vous pouvez configurer IAP pour inclure un ou plusieurs attributs dans les informations qu'il fournit à vos applications protégées. Si vous configurez l'authentification unique via un fournisseur d'identité tiers et que votre fournisseur d'identité inclut un <AttributeStatement> dans l'assertion SAML, Google Cloud stocke temporairement les attributs associés à la session du compte Google d'un utilisateur. Lorsqu'une session de compte Google expire, un processus asynchrone supprime définitivement les informations au bout d'une semaine. Vous pouvez configurer la date d'expiration.
N'utilisez pas la propagation des attributs SAML pour les informations personnelles sensibles, telles que les identifiants de compte, les numéros de carte d'identité, les données concernant les titulaires de cartes, les données comptables, les informations médicales ou les informations relatives à des parcours personnels.
Activation de 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
- Dans la console Google Cloud, accédez à la page "IAP".
Accéder à IAP - Ouvrez les paramètres d'une ressource, puis faites défiler la page jusqu'à Propagation des attributs.
- Sélectionnez Activer la propagation des attributs, puis cliquez sur Enregistrer.
Dans l'onglet SAML Attributes (Attributs SAML), saisissez les attributs que vous souhaitez propager au format suivant :
attribute1, attribute2, attribute3Vous pouvez également saisir les attributs à l'aide d'une expression personnalisée.Les attributs de votre expression personnalisée sont affichés dans l'onglet Attributs SAML. Pour que vos attributs s'affichent dans l'onglet Attributs SAML, vous devez utiliser le format d'expression suivant:
attributes.saml_attributes.filter(attribute, attribute.name in ['attribute', 'attribute2', 'attribute1'])Pour Types d'identifiants à transmettre, sélectionnez au moins un format d'attribut provenant du fournisseur d'identité à transmettre aux applications.
gcloud
Exécutez les commandes gcloud CLI'IAP 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 indiqué 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 un jeton Web JSON (JWT) et des 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 utiliser les fonctions CEL (Common Expression Language) pour filtrer les attributs SAML.
L'utilisation d'expressions CEL avec la propagation des 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 des attributs SAML IAP.
Notez que les fonctions sont sensibles à la casse et doivent être utilisées telles quelles. 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 fichier proto a. Le caractère b peut être un autre proto, une liste ou un type de valeur simple tel qu'une chaîne. |
| Filtrer des listes | list.Filter(iter_var, condition) |
Renvoie un sous-ensemble de list où les éléments correspondent à condition. |
| Membres des listes | a dans b |
Renvoie true si la valeur a fait partie 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 vous utilisez HEADERS 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
Supposons 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 d'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 restent inchangés par rapport aux assertions SAML fournies.
Pour l'exemple d'assertion SAML, le jeton JWT IAP contient les éléments suivants:
{
"additional_claims": {
"my_saml_attr_1": ["value_1", "value_2"]
}
}
En-têtes d'une assertion SAML
Dans les en-têtes, les valeurs des attributs, des clés et des noms sont échappées conformément à la norme RFC 3986 et sont jointes par des 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 le préfixe IAP x-goog-iap-attr-. Pour des raisons de sécurité, l'équilibreur de charge supprime tous les en-têtes de requête comportant le préfixe x-goog-iap-attr. Cela 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 se présente comme suit:
"x-goog-iap-attr-my_saml_attr_1": "value_1,value_2"
L'exemple suivant montre comment IAP protège les caractères spéciaux lors de la propagation des 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"
Vous trouverez ci-dessous un exemple d'échappement dans un nom d'en-tête.
Nom de l'en-tête:
"iap,test,3": "iap_test3_value1,iap_test3_value2"
Nom de l'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, spécifier s'il faut utiliser ou non le préfixe d'en-tête pour certains attributs, et sélectionner de nouveaux attributs fournis par IAP.
Si vous n'avez pas besoin de diffuser les attributs SAML, mais que vous avez besoin de l'adresse e-mail, de l'ID d'appareil ou de l'horodatage dans un champ SM_USER, vous pouvez sélectionner ces attributs dans le champ iap_attributes list: attributes.iap_attributes...
IAP fournit les attributs suivants: user_email, device_id et timestamp.
Examples
Les exemples suivants montrent comment personnaliser les attributs à l'aide des fonctions selectByName, append, strict et emitas.
Prenons l'exemple d'assertion SAML.
selectByName
Utilisez la fonction selectByName pour sélectionner un seul attribut dans une liste donnée en fonction de son 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 filtres. Vous pouvez également ajouter plusieurs attributs et les ajouter à une liste en les enchaînant, comme suit:
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 associé aux fonctionnalités strict et emitAs.
strict
Utilisez la fonction strict pour signaler un attribut afin qu'IAP ne ajoute pas x-goog-iap-attr- au nom. Cela est utile lorsque le nom d'un attribut 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 spécifiez sera généré par tous les identifiants. Par exemple, pour renommer my_saml_attr_1 en 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 d'attributs IAP en tant que "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 des 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 taille des requêtes est limitée à 8 Ko pour la plupart des serveurs Web. Cela limite la taille des attributs personnalisés sortants, y compris la duplication des attributs dans les en-têtes. Si la taille des attributs (nom plus valeurs) dépasse 5 000 octets lorsqu'ils sont dupliqués et encodés, IAP rejette la requête et renvoie le code d'erreur 401 d'IAP.
Caractères Unicode dans la propagation des attributs SAML
Cette fonctionnalité n'est pas compatible avec les caractères Unicode et UTF-8. Les valeurs d'attribut doivent donc être des chaînes au format ASCII faible. Si une assertion n'est pas au format ASCII faible, la connexion échoue.