Configure SAML attribute propagation

This page describes how to enable and use Security Assertion Markup Language (SAML) attribute propagation. You can use this feature to propagate SAML attributes from an identity provider to applications protected by Identity-Aware Proxy (IAP). When you propagate SAML attributes, you can specify which attributes to propagate, and how to deliver the attributes.

Before you begin

You should be knowledgeable about the SAML V2.0 Assertions and Protocols specification (PDF).

Understanding how the data is handled

Before you enable SAML attribute propagation, ensure that you understand how Google Cloud manages the data, and what type of information you should and shouldn't pass over this channel.

You can configure IAP to include one or more attributes in the information it provides to your protected applications. If you set up SSO via a third party Identity provider and your identity provider includes an <AttributeStatement> in the SAML assertion, Google Cloud temporarily stores the attributes associated with a user's Google account session. When a Google account session expires, an asynchronous process permanently removes the information within a week. You can configure the expiration date.

Don't use SAML attribute propagation for sensitive personally identifiable information (PII), such as account credentials, government ID numbers, card holder data, financial account data, healthcare information, or sensitive background information.

Enabling SAML attribute propagation

Enable SAML attribute propagation by creating an SSO profile in Google Workspace, and then update the IAP settings by using the Google Cloud CLI or the REST API.

Console

  1. In the Google Cloud console, go to the IAP page.
    Go to IAP
  2. Open the settings for a resource, and then scroll to Attribute propagation.
  3. Select Enable attribute propagation, and then click Save.

  4. In the SAML Attributes tab, enter the attributes that you want to propagate using the following format: attribute1, attribute2, attribute3

    You can also enter the attributes by using a custom expression.The attributes for your custom expression are displayed in the SAML Attributes tab. You must use the following expression format for your attributes to be displayed in the SAML Attributes tab:
    attributes.saml_attributes.filter(attribute, attribute.name in ['attribute', 'attribute2', 'attribute1'])

  5. For Credential types to pass, select at least one attribute format coming from the IdP to pass to applications.

gcloud

Run the following IAP gcloud CLI commands to update the SAML attribute propagation settings:

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

Replace the following:

  • FOLDER: The folder in which your application resides.
  • ORGANIZATION: The organization in which your application resides.
  • PROJECT: The project in which your application resides.
  • RESOURCE_TYPE: The resource type.
  • SERVICE: The service.
  • VERSION: The version number.

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
      }
   }
}

REST API

You can configure the SAML attributes to propagate by using the ApplicationSettings object in IapSettings, as shown in the following examples:

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

AttributePropagationSettings

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

Setting the output credentials

When using SAML attribute propagation, you can send attributes across multiple mediums, including JSON Web Token (JWT) and headers, by setting output credentials. To set the credentials in the API, you can specify a list of comma-separated strings, as shown in the following example:

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

Filtering SAML attributes using Common Expression Language

You can use Common Expression Language (CEL) functions to filter SAML attributes.

Using CEL expressions with SAML attribute propagation has the following limitations:

  • An expression must return a list of attributes.
  • An expression can select a maximum of 45 attributes.
  • An expression string cannot exceed 1000 characters.

Following are the CEL functions that are supported when using the IAP SAML attribute propagation feature.

Note that the functions are case sensitive and must be used exactly as written. The ordering of the strict and emitAs functions does not matter when chaining function calls.

Function Example Description
Field Selection a.b Select field b from the proto a. The character b can be another proto, a list, or a simple value type such as string.
Filtering Lists list.Filter(iter_var, condition) Returns a subset of list where items meet condition.
List Membership a in b Returns true if the value a is a member of list b.
selectByName list.selectByName("name") From the list, select the attribute where name = "name".
append list.append(attribute) Appends the given attribute to the given list.
strict attribute.strict() Emits the attribute without the x-goog-iap-attr- prefix when using HEADERS as an output credential.
emitAs attribute.emitAs("new_name") Outputs the given attribute with the name "new_name" to all of the selected output credentials.

Example CEL expression

Assume a SAML assertion: 

<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