This page shows you how to resolve common issues withWorkforce Identity Federation.

Inspect the IdP response

This section shows you how to inspect the response from your identity provider(IdP) to troubleshoot issues listed in this document.

Review logs

To determine whether Google Cloud is communicating with your IdP andreview transaction information, you can inspect the Cloud Audit Logs logs.

To see log examples, seeExample audit logs.

Workforce pool and provider management errors

This section provides suggestions to fix common errors that you might encounterwhen managing pools and providers.

General attribute mapping errors

To troubleshoot workforce identity pool provider attribute mapping issuesby doing the following:

• Inspect the attributes, otherwise known as claims, in your IdP configuration.
• Inspect tokens that are generated from your IdP. To learn how to generate atoken from your IdP, consult your IdP's documentation.
• Review Workforce Identity Federation detailed audit logging inCloud Audit Logs.

Detailed audit logging logs authentication and authorization errors alongsideclaims that were received by Workforce Identity Federation.

You can enable detailed audit logging when you create your workforce identity poolprovider. To enable detailed audit logging, add the--detailed-audit-loggingflag when you create your workforce identity pool provider.

Permission denied

This error occurs when the user attempting to configureWorkforce Identity Federation doesn't have the role IAM Workforce Pool Admin (roles/iam.workforcePoolAdmin).

INVALID_ARGUMENT: Missing OIDC web single sign-on config

The following error occurs when theweb-sso-response-type andweb-sso-assertion-claims-behavior fields are not set when creating an OIDCworkforce identity pool provider:

ERROR: (gcloud.iam.workforce-pools.providers.create-oidc) INVALID_ARGUMENT: Missing OIDC web single sign-on config.

To resolve this error, follow the steps in theCreate a providersection to set the fields appropriately when you create the OIDC workforceidentity pool provider.

Rate limit exceeded, please try again later

This error occurs when you have reached your quota limit for workforce poolresources. Contact your Google Cloud account representative to request aquota increase.

Sign-in errors

This section provides suggestions to fix common errors that aWorkforce Identity Federation user might encounter when they sign in.

Common sign-in errors

The given credential is rejected by the attribute condition

This error occurs when theattribute conditionthat is set on the workforce identity pool provider was not met.

For example, consider the following attribute condition:

'gcp-users' in assertion.attributes.groups

'gcp-users' in assertion.groups

In this case, you see the error if the list of groups sent in thegroupsattribute by your IdP doesn't containgcp-users.

To resolve this error, perform the following steps:

1. Describe the providerthat was used to sign in, and check that theattributeCondition iscorrect. For information on operations that are supported in conditions, seetheLanguage Definition.

2. Follow the steps ininspect the IdP response to seethe attributes that are returned by the IdP, and confirm if the attributecondition is well-formed and accurate.

3. Sign in to your IdP's admin console, and check if the IdP attributesreferenced in the attribute condition are set up correctly. If necessary,consult your IdP's documentation.

The mapped attribute must be of type STRING

This error occurs for a SAML workforce identity pool provider when the attributespecified in the error message is expected to be a single-valued STRING, but itis mapped to a list in theattribute mapping.

For example, consider a SAML workforce identity pool provider that has theattribute mapping,attribute.role=assertion.attributes.userRole. In a SAMLassertion, anAttribute can have multipleAttributeValue tags as shown inthe example that follows. Thus, all SAML attributes are considered lists, soassertion.attributes.userRole is a list.

<saml:Attribute Name="userRole"><saml:AttributeValue>security-admin</saml:AttributeValue><saml:AttributeValue>user</saml:AttributeValue></saml:Attribute>

In this example, you might see the following error:

The mapped attribute 'attribute.role' must be of type STRING

To resolve this issue, perform the following steps:

1. Describe the providerthat was used to sign in, and identify the IdP attribute that is set in theattributeMapping. Check the attribute against the attribute presented inthe error message. In the previous example, an IdP attribute calleduserRole is mapped to therole attribute and therole attributeappears in the error sample above.

2. Follow guidance below to update the attribute mapping:

   Note: Onlygoogle.groups accepts a list.

   • If the attribute that causes the error is list valued, identify analternative, stable, string-valued attribute. Then, update the attributemapping to use it by referencing its first item. For the previous example,ifmyRole was identified as the alternative single-valued IdP attribute,then, the attribute mapping would be:

     attribute.role=assertion.attributes.myRole[0]

   • Alternatively, if the attribute is known to be single-valued, update theattribute mapping to use the first item from the list.For the previous example, ifuserRole contains only one role, you canuse the following mapping:

     attribute.role=assertion.attributes.userRole[0]

   • To derive a single-valued, stable identifier from the list, seeLanguage Definitionand update your attribute mapping accordingly.

See theinspect the IdP response section to see theresponse that is returned by the IdP.

Could not obtain a value for google.subject from the given credential

This error occurs when the required claimgoogle.subject couldn't be mappedusing theattribute mappingthat you set in your workforce identity pool provider configuration.

To resolve this error, perform the following steps:

1. Describe the provider,and inspect theattributeMapping. Identify the mapping that is configuredforgoogle.subject. If the mapping is not correct, update the workforceidentity pool provider.

2. See theinspect the IdP response section to see theresponse returned by the IdP. Inspect the value of the attribute from IdPresponse that is mapped togoogle.subject in your attribute mappings.

   If the value is empty or incorrect, login to your IdP's admin console, andinspect the configured attributes. For the attributes, check if youraffected user has corresponding data in your IdP. Update your IdPconfiguration to correct the attributes or user information accordingly.

3. Retry sign-in.

Size of mapped attributes exceeds the limit

The following error occurred when a federated user attempts to sign in:

The size of the entire mapped attributes exceeds the 16 KB limit.

To resolve this issue, ask your IdP administrator to reduce the number ofattributes that your IdP emits. Your IdP only needs to emit attributesthat are needed to federate users to Google Cloud. To learn more aboutattribute mapping limits, seeattribute mappings.

For example, if your IdP emits a large number ofgoogle.groups that are mappedattributes in your workforce identity pool provider, a sign-in attempt can fail.Ask your administrator to restrict the number of groups that your IdP emits.

Count of groups exceeds the limit

The following error occurred when a federated user attempts to sign in:

The current count ofGROUPS_COUNT mapped attribute google.groups exceeds theGROUPS_COUNT_LIMIT count limit. Either modify your attribute mapping or the incoming assertion to produce a mapped attribute that has fewer thanGROUPS_COUNT_LIMIT groups.

This error includes the following values:

• GROUPS_COUNT: the count of groups that the IdP emits

• GROUPS_COUNT_LIMIT: Google Cloud's count limitfor groups

This error occurred when the number of groups emitted by the IdP exceedsGoogle Cloud's limit. Groups are mapped to Google Cloud usingthe attributegoogle.groups.

To resolve this issue, ask your administrator to reduce the number of groupsthat your IdP emits. Your IdP only needs to emit groups that are used tofederate users to Google Cloud. Learn more about groups-related limits inattribute mappings.

SCIM tenant couldn't be found

This error occurs when a user tries to sign in using a workforce identity poolprovider that's configured to use SCIM, but no SCIM tenant is configuredfor that provider.

When this occurs, users get the following error when they try to sign in:

There was an issue signing in with your identity provider.

To resolve this error, do the following:

1. Configure a SCIM tenant and token on Google Cloud.
2. Link the provider to a SCIM tenant.

400. That's an error

This error occurs when either the request wasn't received as expected or it wasmalformed.

To resolve this error, perform the following steps:

1. Follow the steps inInform your users how to sign insection to verify if you are following the correct steps to sign in.

2. Compare your workforce identity pool provider configuration with your IdPconfiguration.

OIDC sign-in errors

This section provides suggestions to fix OIDC specific errors that aWorkforce Identity Federation user might encounter when they sign in.

Error connecting to the given credential's issuer

This error occurs when an OIDC workforce identity pool provider is unable toreach the OIDC discovery document or JWKS URI.

To resolve this error, perform the following steps:

1. Describe the provider,and inspect the configuredissuerUri. Construct the discovery documentURL by appending/.well-known/openid-configuration to your issuer URI. Forexample, if yourissuerUri ishttps://example.com, the discoverydocument URL would behttps://example.com/.well-known/openid-configuration.

2. Open the discovery document URL in an incognito browsing window.

   1. If the URL doesn't open or the browser displays a404 error, consultyour IdP's documentation to identify the correct issuer URI. Ifnecessary, update theissuerUri in your workforce identity poolprovider.

      If your IdP is running on premises, consult your IdP's documentation toprovision it for access over the internet.

   2. If the URL opens, check for the following conditions:

      1. Check that the URL doesn't redirect too many times before serving thediscovery document. If it does, consult with your IdP's administratorto remedy the issue.
      2. Check the IdP response time. Consult with your IdP administrator toreduce the response latency.
      3. The opened discovery document should be in theJSON format.

      4. Look for ajwks_uri field in the JSON.

         1. Verify that the associated URL value also opens.
         2. Verify that the URL satisfies the conditions as described earlierin this guide.

   3. Retry sign-in.

SAML sign-in errors

This section provides suggestions to fix SAML specific errors that aWorkforce Identity Federation user might encounter when they sign in.

Failed to verify the signature in SAMLResponse

This error occurs for a SAML workforce identity pool provider when the signatureon the IdP response cannot be verified using any of the X.509 certificatesprovided in the IdP metadata XML that you configured in your workforce identitypool provider. A common cause of this error is that the verification certificateon your IdP was rotated, but you did not update the workforce identity poolprovider configuration with the latest IdP metadata XML file.

To resolve this error, perform the following steps:

1. Optional: follow the steps ininspect the IdP responseto see the response returned by the IdP and locate theX509Certificatefield in it.Describe the providerthat you used to sign in, and inspect theX509Certificate field present intheidpMetadataXml value that is set on workforce identity pool provider. Compare the certificate with the one seen in the response returnedby your IdP. The certificates must match.

2. Login to your IdP's admin console, and download the latest metadata XML.

3. Update the workforce identity pool provider with the downloaded IdP metadataXML.

4. Retry sign-in.

Recipient in SAML assertion is not set to the correct ACS URL

This error occurs for a SAML workforce identity pool provider when the IdPresponse contains an incorrect value for theRecipient field on theSubjectConfirmationData tag.

To resolve this error, update theRecipient URL /Redirect URL or theequivalent field in your IdP's configuration to use the redirect URL describedin theSet up redirect URLs in your IdP,and retry sign-in.

Follow the steps ininspect the IdP response to see theresponse returned by the IdP, and confirm that theRecipient field iscorrect.

For example, for the workforce identity pool providerlocations/global/workforcePools/example-pool/providers/example-provider,theRecipient containing the redirect URL appears in the IdP's SAML responseas follows:

<SubjectConfirmationData Recipient="https://auth.cloud.google/signin-callback/locations/global/workforcePools/example-pool/providers/example-provider"

SAMLResponse destination does not match RP callback URL

This error occurs for a SAML workforce identity pool provider when the IdPresponse contains an incorrect value for theDestination field on theResponse tag.

To resolve this error, update theDestination URL /Redirect URL or theequivalent field in your IdP's configuration to use the redirect URL describedinSet up redirect URLs in your IdP.

Follow the steps ininspect the IdP response to see theresponse returned by the IdP and confirm that theDestination field iscorrect.

For example, for a workforce identity pool providerlocations/global/workforcePools/example-pool/providers/example-provider, theDestination containing redirect URL would appear in the IdP's SAML response asfollows:

<Response Destination="https://auth.cloud.google/signin-callback/locations/global/workforcePools/example-pool/providers/example-provider"

Invalid assertion: missing or empty NameID

This error occurs when the SAML response received from your IdP doesn't containtheNameId field or it has an empty value.

To resolve this error, consult your IdP documentation to configure it to sendtheNameID which is the subject of a SAML assertion, typically the user whois being authenticated.

Follow the steps ininspect the IdP response to see theresponse returned by the IdP and theNameID that is set on it.

All<AudienceRestriction>s should contain the SAML RP entity ID

This error occurs when theAudienceRestriction tags in the SAML response fromyour IdP doesn't set anAudience tag with value that represented the entityID of the workforce identity pool provider.

To resolve this error, perform the following steps:

1. Consult your IdP documentation on how to configure the audience in theAudienceRestriction tags that it sends in the SAML response. Typically,the audience is configured by setting upEntity ID orAudience field inyour IdP configuration. SeeCreate a workforce identity pool provider'sSAML section to see the valueSP Entity ID that should be set.

2. After updating your IdP configuration, retry sign-in.

Follow the steps ininspect the IdP response to see theresponse returned by the IdP and theAudienceRestrictions that are set on it.