TL;DR:
Unlocking the full potential of AI hinges on one critical capability: breaking data silos without breaking security. This imperative has made Workforce Identity Federation (WIF) one of the core trends of the year, accelerated by emergence of specialised AI SaaS products like Gemini Enterprise and NotebookLM Enterprise.
However, there is nothing quite as frustrating as watching a high-priority AI initiative stall because of a SAML assertion error. This article provides technical guidance on Workforce Identity Federation setup in a scenario where I see the majority of user questions arise: Microsoft Entra ID with SAML, covering two critical topics:
- Mastering attribute mapping.
- Correctly referencing WIF principals for IAM permissions.
I have seen engineers spending hours on this… so now you don’t have to 😉
1. Introduction
1.1 Why is Workforce Identity Federation important?
Decades of adopting SaaS applications have created a fragmented digital workplace, scattering both employee’s identity and data across dozens of systems.
Workforce Identity Federation (WIF) solves this by enabling organisations to use their existing identity providers (IdPs) — like Entra ID, Okta, or Ping — to grant access to Google Cloud resources. It streamlines management by providing a true single sign-on (SSO) experience without needing to create new identities in Google Cloud or synchronise them from external IdPs.
Workforce Identity Federation is ideal when:
✅ You want to use a single, centralised identity provider for your employees across your applications, including Google Cloud and SaaS products.
✅ You need to provide third parties with access to Google Cloud resources using their existing IdP credentials.
✅ Your security policies or regulations prohibit identity synchronization between IdPs.
💡 More than just authentication, for Gemini Enterprise WIF functions as a critical security bridge that allows Gemini Enterprise to unify data across fragmented third-party systems (like SharePoint or Salesforce) while strictly adhering to your organisation’s existing Access Control Lists (ACLs).
❗A Critical Distinction: Workforce vs. workload federation
Do not confuse Workforce Identity Federation with Workload Identity Federation. While both methods enable external identities to access Google Cloud, they serve distinct purposes:
- Workforce Identity Federation: Authenticates and authorizes human users like employees, partners, and contractors.
- Workload Identity Federation: Authenticates and authorizes software workloads or applications, such as GitHub pipelines.
1.2 What this article covers
This guide focuses on the two most common and challenging “tripping points” encountered during the WIF setup process (see Diagram 2): Step 6 (Attribute Mapping) and Step 7 (Configure IAM) when integrating Entra ID & SAML protocol.
These steps are critical because WIF relies on attributes and IAM to enforce granular, precise access controls. Drawing on my experience, this guide provides the expert tips and examples to master this specific Entra ID & SAML scenario and get it right the first time.
1.3 Recommended prerequisites
- Be familiar with WIF and the setup steps.
- Be familiar with the structure of a sample SAML token.
2. Attribute Mapping 🗺️
At its core, WIF configuration relies on attributes (sometimes referred to as claims), which are pieces of information about your users — name, email address, department, or group membership. With the Entra ID/SAML scenario, attributes (claims) are sent from Entra ID to Google Cloud in a SAML token after successful user authentication. Google Cloud relies on these attributes from the SAML token to determine a user’s roles, grant permissions, and personalize their experience. However, Entra ID SAML and Google use different attribute formats:
- Entra ID SAML attributes (claims) — is the source of information. SAML Attributes coming from Entra ID are listed here. They are identified by long, formal names (URIs):
– http://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddress (email address)
– http://schemas.microsoft.com/ws/2008/06/identity/claims/groups (groups)
– etc.
You can find the name (and others for email, name, etc.) by inspecting the token configuration. - Google Cloud attributes — destination that you are assigning the source value to. Standard Google Cloud attributes are listed here. Predefined attribute names include:
– google.subject(user’s unique ID)
– google.email
– google.groups
– and others.
To be able to use data provided with SAML response you need to map attributes. It’s like translating between two languages: Entra ID attributes (claims) and the corresponding Google Cloud attributes. This is done with Common Expression Language (CEL): it allows one to read a SAML attribute and assign its value to a google attribute. If we take the example of the email attribute, mapping is essentially the instruction you write using CEL that says: “Take the value from the http://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddress source and put it into the google.email destination.”
Mapping would look like this: google.email=assertion.attributes['http://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddress'][0]
What’s the catch? Incorrect attribute mapping is a very common misconfiguration. Typically I see errors related to using the wrong attribute names from the SAML assertion. Let’s walk through the exact configuration and the common pitfalls to avoid.
2.1 How to configure attribute mapping: tips and common pitfalls
Attribute mapping is configured on the Google Cloud side. It is set up as part of either creating a SAML workforce identity pool provider or editing an existing one. If you are following the official guide, it’s the “Create a SAML 2.0 workforce identity pool provider” step of the guide.
Important points to get it right:
💡1) Mapping format
With SAML & Entra ID for the majority of the attributes the CEL expression is assertion.attributes.['ATTRIBUTE_NAME’], where ATTRIBUTE_NAME is a value of Name in each <Attribute> element in the SAML assertion. Let’s take this sample SAML token assertion section:
Let’s say I would like to map a ‘groups’ attribute to be able to assign IAM permissions to groups of users. In the token search for <Attribute Name=ATTRIBUTE_NAME>.
- For ‘Groups’ the attribute name from the example SAML token is http://schemas.microsoft.com/ws/2008/06/identity/claims/groups
- For Google a pre-defined attribute for groups is google.groups.
So the attribute mapping CEL expression for ‘Groups’ that would be ➡️ google.groups=assertion.attributes['http://schemas.microsoft.com/ws/2008/06/identity/claims/groups']
💡 2) Data types
In a SAML assertion, an Attribute can have multiple AttributeValue tags. Thus, all SAML attributes are considered lists. ❗Only google.groups accepts a list and the rest of the google attributes are expected to be a string. So even if you are using a single valued attribute, you might need to reference the first item from the list like so assertion.attributes.ATTRIBUTE_NAME[0] for the mapping to work correctly.
Examples for the display name, depending on what attributes are passed with your SAML token:
- google.display_name=assertion.attributes['http://schemas.xmlsoap.org/ws/2005/05/identity/claims/givenname'][0]
- google.display_name=assertion.attributes['http://schemas.microsoft.com/identity/claims/displayname'][0]
I recommend inspecting your actual SAML response to ensure the values are correct. You can do this by downloading the HAR file in your browser and analysing it with a tool of your choice. Alternatively, you can always refer to Microsoft documentation for SAML templates. You can also refer to this troubleshooting guide.
💡 3) Special attribute ‘Subject’
google.subject is a special google attribute. It must always map to a field that uniquely identifies end-users in Entra ID. Typically it maps to user’s primary identifier that is usually stored in a specific tag called <NameID>, which lives inside the <Subject> block, separate from the other attributes, using this clause:
- google.subject=assertion.subject
❗When setting up Gemini Enterprise, subject must map to user email address (as of time of writing this article). This is the example we will be using moving forwards:
- google.subject=assertion.attributes['http://schemas.xmlsoap.org/ws/2005/05/identity/claims/name'][0]
You can see more details about mapping attributes for Gemini Enterprise here, including a scenario when an organisation has more than one unique identifier.
2.2 Example attribute mapping configuration
To bring these recommendations together, let’s map the following attributes for WIF:
- google.subject: compulsory and also allows IAM permissions to be assigned using user emails.
- google.groups: to be able to assign IAM permissions to groups of users. Can accept a list.
- google.display_name: to personalise the Google Cloud UI and set the name of the signed-in user in the console. Accepts only a string as value.
Given all the above considerations, the attribute mapping in Google Cloud would be as follows:
attributeMapping=
' google.subject=assertion.attributes['http://schemas.xmlsoap.org/ws/2005/05/identity/claims/name'][0]
google.groups=assertion.attributes['http://schemas.microsoft.com/ws/2008/06/identity/claims/groups']
google.display_name=assertion.attributes['http://schemas.microsoft.com/identity/claims/displayname'][0]'
The screenshot below is for visual reference. Use the code block above as the source of truth.
3. Assigning IAM Permissions to Federated Identities 🔐
Once your WIF pool and provider has been created, you can use it to grant IAM permissions. If you are following the official guide, it’s the “Manage access to Google Cloud resources” step of the guide.
You can grant IAM access to an entire workforce identity pool or a subset thereof (based on attributes that you mapped in the previous section). For example, a specific group of users.
IAM binding for WIF principals is configured the same way as native Google Cloud principals. The only difference is in the format of the principal identifiers. So rather than using email addresses for native principals, (like user@domain.com for a user or my_group@domain.com for a group) you’d need to use WIF-specific identifier format — please read on to see:
- How to reference WIF principals in Google Cloud
- How to reference WIF principals in IAM
❗The majority of misconfigurations here are typically related to using a wrong identifier format.
3.1 Correct WIF principals format in Google Cloud
Let’s have a look at some WIF principal identifiers (full list can be found here) and actual examples of what they would look like when configuring WIF with Entra ID:
-> All identities in a workforce identity pool:
- principalSet://iam.googleapis.com/locations/global/workforcePools/POOL_ID/*
- Example:principalSet://iam.googleapis.com/locations/global/workforcePools/entra-id-pool/* — represents all users authenticated as part of the entra-id-pool WIF pool
-> All workforce identities in a group
- principalSet://iam.googleapis.com/locations/global/workforcePools/POOL_ID/group/GROUP_ID
- Example:principalSet://iam.googleapis.com/locations/global/workforcePools/entra-id-pool/group/aaaabbbb-0000-cccc-1111-dddd2222eeee
- ❗Important: Make sure to use the group ID rather than group name. You can find this ID in Entra ID by following these steps:
1. Go to your Enterprise application in Entra ID.
2. Navigate to “All groups.”
3. Locate the “Infrastructure” group in the list.
4. The Object ID will be displayed in the table.
-> Individual user
- principal://iam.googleapis.com/locations/global/workforcePools/POOL_ID/subject/SUBJECT_ATTRIBUTE_VALUE
- Example: principal://iam.googleapis.com/locations/global/workforcePools/POOL_ID/subject/user@domain.com
3.2 How to grant IAM roles to WIF principals in Google Cloud
To grant the IAM roles, run the gcloud projects add-iam-policy-bindingcommand, with a WIF principal as a member. For example, to grant a Discovery Engine User role (roles/discoveryengine.user) to all identities within the group aaaabbbb-0000-cccc-1111-dddd2222eeee for project my_project, you would need to run the following command:
gcloud projects add-iam-policy-binding my-project \
--role="roles/discoveryengine.user" \
--member="principalSet://iam.googleapis.com/locations/global/workforcePools/entra-id-pool/group/aaaabbbb-0000-cccc-1111-dddd2222eeee”
The same for an individual user:
gcloud projects add-iam-policy-binding my-project \
--role="roles/discoveryengine.user" \
--member="principal://iam.googleapis.com/locations/global/workforcePools/entra-id-pool/subject/user@domain.com”
Alternatively, this can be done via Google Cloud console by navigating to IAM -> Grant access and referencing the correct WIF principal and selecting the required roles. Please see the examples below:
- Assigning permissions for a group using group ID:
- Assigning roles for an individual user:
Conclusion
And there you have it! By following these tips and paying close attention to attribute mapping and IAM configuration, you can avoid common pitfalls when using Workforce Identity Federation with Entra ID and SAML. Remember to double-check your mappings, ensure claim names and data types are correct (list vs string), and test your configuration thoroughly. With a correct WIF setup, you’re now ready to securely connect your enterprise identity provider to powerful Google Cloud tools!
Feel free to leave a comment below if you have any questions.
Happy building! 🚀
Workforce Identity Federation Made Easy: Attribute Mapping and Permissions for Entra ID & SAML was originally published in Google Cloud – Community on Medium, where people are continuing the conversation by highlighting and responding to this story.
Source Credit: https://medium.com/google-cloud/workforce-identity-federation-made-easy-attribute-mapping-and-permissions-for-entra-id-saml-1e4092fdc6ad?source=rss—-e52cf94d98af—4
About the Author
