SCIM provisioning for Workforce Identity Federation
If your identity provider (IdP) supportsSystem for Cross-domain Identity Management (SCIM),you can configure your IdP to provision and manage groups in Google Cloud.
Important: This feature applies only to Gemini Enterprise.Capabilities
Workforce Identity Federation SCIM support provides the following capabilities:
Identity synchronization: Sync read-only copies of user data from your IdPto get a holistic view of user properties and memberships in Google Cloud.
Group flattening: SCIM processes groups from your IdP so that all directand indirect (nested) memberships for a user are flattened and synced to theGoogle Cloud Group Membership Service (GMS). IAM then usesthese flattened groups for policy checks, overcoming the size constraints oftenfound in IdP tokens.
Gemini Enterprise integration: SCIM tenants support sharing inGemini Enterprise. Users can share NotebookLM notebooks with agroup using the group's name instead of its object ID (UUID). To learn more,seeShare a notebook with a group.
Considerations
When you use Workforce Identity Federation SCIM support, the followingconsiderations apply:
- You must set up a workforce identity pool and provider before configuring aSCIM tenant.
- Each workforce identity pool supports only one SCIM tenant. To configure anew SCIM tenant in the same workforce identity pool, you must first deletethe existing one. When deleting a SCIM tenant, you have two options:
- Soft delete (Default): Deleting a SCIM tenant initiates a 30-daysoft-delete period. During this time, the tenant is hidden and cannot beused, and you cannot create a new SCIM tenant in the same workforceidentity pool.
- Hard delete: To permanently and immediately delete a SCIM tenant,use the
--hard-deleteflag with the delete command. This action isirreversible and lets you create a new SCIM tenant in the same workforceidentity pool immediately after the deletion completes. Alternatively,you can create a new workforce identity pool and a new SCIM tenant oruse a workforce identity pool that hasn't previously been configuredwith a SCIM tenant.
- When you use SCIM, you map attributes in both the workforce identity poolprovider and the SCIM tenant. The
google.subjectattribute must uniquelyrefer to the same identities. You specify thegoogle.subjectin theworkforce identity pool provider by using the--attribute-mappingflag andin the SCIM tenant using the--claim-mappingflag. Mapping non-uniqueidentity values can cause Google Cloud to treat different IdP identitiesas the same identity. As a result, access that's granted to one user or groupidentity can extend to others but revoking access from one might not remove itfrom all. - To use SCIM to map groups, set
--scim-usage=enabled-for-groups. When youmap groups using SCIM, any group mapping that's defined in the workforceidentity pool provider is ignored. When referring to SCIM-managed groups,the mapped attribute isgoogle.group, notgoogle.groups.google.groupsonly refers to token-mapped groups. - When using SCIM, token-based attributes that are mapped with
--attribute-mappingcan still be used for authentication and in principalidentifiers. - For Microsoft Entra ID configuration, you shouldn't use
--extended-attributesflags when you create the workforce identity poolprovider.
Mapping OIDC and SAML providers to SCIM configuration
There must be consistency between the attribute mapping in the workforce identitypool provider configuration (--attribute-mapping) and the claimmappings in the SCIM tenant (--claim-mapping). The underlying IdPattribute used to populategoogle.subject (for users) must be the same,whether it's being read from a token claim or a SCIM attribute.
If these mappings are inconsistent, users might be able to sign in but won't berecognized as members of their SCIM-provisioned groups. For example, if theprovider usesassertion.email forgoogle.subject, theSCIM tenant must also use the equivalent SCIM attribute(for example,user.emails[0].value) forgoogle.subject.
The following table provides reference examples for mapping common IdP tokenclaims to SCIM attributes:
| Google attribute | Workforce identity pool provider mapping (Token) | SCIM tenant mapping (SCIM) |
|---|---|---|
google.subject | assertion.oid | user.externalId |
google.subject | assertion.email | user.emails[0].value |
google.subject | assertion.email.lowerAscii() | user.emails[0].value.lowerAscii() |
google.subject | assertion.preferred_username | user.userName |
google.subject | assertion.sub | Incompatible |
google.group | N/A (Mapped using SCIM) | group.externalId |
--scim-usage=enabled-for-groups. Thegoogle.groups attribute in the provider mapping is ignored for group-based authorization; instead, usegoogle.group.Supported and unsupported endpoints
The following standard SCIM protocol endpoints are supported:
/Users: manage user resources. Supported operations:Create,Get,Update,Delete,Patch, andPut./Groups: manage group resources. Supported operations:Create,Get,Update,Delete, andPatch. ThePUTmethod isn't supported for groups./Schemas: retrieve schema information./ServiceProviderConfig: retrieve the service provider configuration.
Import Users andImport Groupsfeatures from Google Cloud to Okta.The following SCIM protocol endpoints aren't supported:
/Me/Bulk/Search/ResourceTypes
Limitations
The following sections describe the limitations and deviations of the Workforce Identity Federation SCIM implementation from the SCIM specifications (RFC 7643 and 7644).
Protocol feature limitations
Filter support: When you list users or groups using the
/Usersor/Groupsendpoints, filter expressions only support theeq(equals) operator. You cancombine multipleeqfilters withand. Other SCIM filter operators, such asco(contains) orsw(starts with), aren't supported.Pagination: The IAM SCIM API does not support standard paginationfor listing users or groups.
startIndex: this parameter is always1. The API returns up to 100 resultsregardless of the value that you provide forstartIndex.itemsPerPage: the maximum number of resources that are returned in a singleresponse is 100.totalResults: the API does not return the actual total count of matchingresources. ThetotalResultsfield in the response is always equal to thenumber of items that are returned in that response, with a maximum of 100.
Get Group and list Groups without filter:
GetGroupandListGroupsAPIsreturn an empty member list. To retrieve members for a specific group, use theListGroupsAPI with a member filter.Non-compliant JSON response with invalid tokens: APIs that contain invalidAPI token result in a
401 HTTP errorfrom Google Cloud. The response isnot a JSON structure as required by the specifications.
SCIM behavior limitations
Immutable identifiers: The values of SCIM attributes that are mapped to
google.subjectorgoogle.groupare treated asimmutable identifiers within Google Cloud. If you need to change thesevalues, you must permanently delete the user or group from your IdP and thenrecreate it with the new value.Single email requirement: For successful SCIM synchronization, each usermust have exactly one email address of type
work. Provisioning or updateswill fail if your IdP sends multiple emails or if the single email provided isnot typed aswork.Case-insensitive transformations: Limited Common Expression Language(CEL) transformations are supported for SCIM claim mappings.Only
.lowerAscii()is supported for case-insensitive comparisons foruser.userNameanduser.emails[0].value.
Attribute limitations
The following sections describe the attribute support for users, groups, andthe enterprise user schema extension.
User attributes
The following table details the support for user attributes:
| Attribute | Sub-attributes | Supported | Limitations |
|---|---|---|---|
userName | N/A | Yes | N/A |
name | formatted,familyName,givenName,middleName,honorificPrefix,honorificSuffix | Yes | N/A |
displayName | N/A | Yes | N/A |
nickName | N/A | Yes | N/A |
profileUrl | N/A | Yes | N/A |
title | N/A | Yes | N/A |
userType | N/A | Yes | N/A |
preferredLanguage | N/A | Yes | N/A |
locale | N/A | Yes | N/A |
timezone | N/A | Yes | N/A |
active | N/A | Yes | N/A |
password | N/A | No | N/A |
emails | display,type,value,primary | Yes | Only thework email type is supported. |
phoneNumbers | display,type,value,primary | Yes | N/A |
ims | display,type,value | Yes | N/A |
photos | display,type,value | Yes | N/A |
addresses | formatted,streetAddress,locality,region,postalCode,country | Yes | N/A |
groups | N/A | No | N/A |
entitlements | display,type,value | Yes | N/A |
roles | type,value | Yes | display isn't supported. |
x509Certificates | type,value | Yes | display isn't supported. |
Group attributes
The following table details the support for group attributes:
| Attribute | Supported sub-attributes |
|---|---|
displayName | N/A |
externalId | N/A |
members | value,type,$ref,display |
Enterprise user schema extension attributes
The following table details the support for the enterprise user schema extension:
| Attribute | Supported sub-attributes |
|---|---|
employeeNumber | N/A |
costCenter | N/A |
organization | N/A |
division | N/A |
department | N/A |
manager | value,$ref,displayName |
What's next
Except as otherwise noted, the content of this page is licensed under theCreative Commons Attribution 4.0 License, and code samples are licensed under theApache 2.0 License. For details, see theGoogle Developers Site Policies. Java is a registered trademark of Oracle and/or its affiliates.
Last updated 2026-02-18 UTC.