Table of Contents

Configure Google Workspace Federation Through Microsoft Entra ID

This guide configures a Google Workspace domain as a SAML identity provider for Microsoft Entra B2B guest identities that access FoundationaLLM.

The resulting authentication flow is:

Google Workspace account
  -> Google SAML authentication
  -> Microsoft Entra B2B guest
  -> Entra-issued FoundationaLLM access token
  -> FoundationaLLM portal and API

Microsoft Entra ID remains the token issuer for FoundationaLLM. The existing portal app registrations, API scopes, Microsoft Graph group lookup, and FoundationaLLM role-based access control remain unchanged.

Important: This guide uses External Identities SAML direct federation with B2B guests. The Workspace domain must remain unverified in the FoundationaLLM Entra tenant. For personal @gmail.com accounts, use Configure Consumer Gmail Federation Through Microsoft Entra ID instead.

Choose the correct federation model

Use the direct-federation model in this guide when:

  • Users belong to an external Google Workspace domain.
  • Users should be B2B guests in the FoundationaLLM Entra tenant.
  • You do not need the Workspace domain to become a verified domain in that tenant.

Do not use this model when the Workspace domain must be a verified Entra domain and its users must be full member accounts. That scenario requires domain federation, user provisioning, and immutable identity mapping.

The built-in Google OAuth identity provider in Entra is intended for consumer Gmail accounts and does not federate Google Workspace custom domains.

Example values

Replace these examples with values from your environment:

Item Example value
Google Workspace domain fabrikam.io
Entra tenant ID 11111111-2222-3333-4444-555555555555
Entra initial domain contoso.onmicrosoft.com
FoundationaLLM portal https://agent.contoso.com

Prerequisites

Before starting, collect:

  • The Google Workspace domain.
  • The Microsoft Entra tenant ID.
  • The tenant's initial *.onmicrosoft.com domain.
  • The User Portal, Agent Portal, or Management Portal URL.
  • A Google Workspace super administrator account.
  • An Entra account with at least the External Identity Provider Administrator role.
  • An Entra account with permission to invite guest users and manage the FLLM-Users and FLLM-Admins groups.
  • A Workspace account for testing.

Create and test an emergency Global Administrator account that uses the tenant's *.onmicrosoft.com domain before changing external identity or Conditional Access settings.

Confirm the Workspace domain is not registered in Entra

SAML direct federation requires the Workspace domain to be external to the FoundationaLLM tenant. It must not be verified or present as an unverified pending domain.

An unverified domain entry can cause Entra home-realm discovery to treat the domain as managed and route users to email one-time passcode instead of Google.

Check in the Entra admin center

  1. Sign in to the Microsoft Entra admin center.
  2. Open Entra ID > Domain names > Custom domain names.
  3. Locate the Workspace domain.
  4. If it appears as Unverified, select it and delete the pending domain entry.
  5. If it is verified, stop. Do not continue with direct federation until the identity architecture and the consequences of removing the verified domain have been reviewed.

Azure CLI alternative

List the tenant domains:

az rest --method GET `
  --url "https://graph.microsoft.com/v1.0/domains"

Delete only an unverified pending domain entry:

az rest --method DELETE `
  --url "https://graph.microsoft.com/v1.0/domains/fabrikam.io"

Do not verify the Workspace domain while this direct federation is in use.

Create the SAML application in Google Workspace

Add a custom SAML application

  1. Sign in to the Google Admin console as a super administrator.
  2. Open Apps > Web and mobile apps.
  3. Select Add app > Add custom SAML app.
  4. Enter a recognizable name, such as FoundationaLLM through Microsoft Entra.
  5. On Google Identity Provider details, select Download metadata.
  6. Securely save GoogleIDPMetadata.xml. It contains the Google entity ID, SSO URL, and signing certificate.

Configure the Microsoft Entra service provider

Enter:

  • ACS URL: https://login.microsoftonline.com/login.srf
  • Entity ID: https://login.microsoftonline.com/<TENANT-ID>/
  • Signed response: Enabled.
  • Name ID format: PERSISTENT.
  • Name ID: Basic Information > Primary email.

The Entity ID must use the Entra tenant ID and include the trailing slash. For example:

https://login.microsoftonline.com/11111111-2222-3333-4444-555555555555/

Do not use the legacy urn:federation:MicrosoftOnline audience. Entra sends a tenant-specific issuer in new SAML direct-federation requests. An audience mismatch can cause Google to return 403 app_not_configured_for_user during service-provider-initiated sign-in even when Google's Test SAML login appears to work.

Configure attribute mapping

Map the Google user's primary email to the complete Entra email claim URI:

Google Directory attribute App attribute
Basic Information > Primary email http://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddress

Finish creating the application.

Enable access to the Google application

  1. Open the application's User access panel.
  2. Set access to On for everyone, or enable it for the organizational unit or access group containing the FoundationaLLM users.
  3. Save.

If access is disabled, Google returns 403 app_not_configured_for_user.

Google Workspace access changes can take several minutes and, in some environments, longer to propagate. Do not interpret an immediate access error as a configuration failure without allowing time for propagation.

Create the SAML federation in Entra

Configure the provider in the Entra admin center

  1. Sign in to the Microsoft Entra admin center.
  2. Confirm that the active directory is the tenant hosting FoundationaLLM.
  3. Open Entra ID > External Identities > All identity providers.
  4. Select the Custom tab.
  5. Select Add new > SAML/WS-Fed.
  6. Enter:
    • Display name: A value such as Fabrikam Google Workspace.
    • Identity provider protocol: SAML.
    • Domain name of federating IdP: The Workspace domain, such as fabrikam.io.
  7. Select Parse metadata file.
  8. Upload GoogleIDPMetadata.xml.
  9. Verify that Entra populated the Google issuer URI, passive authentication endpoint, and signing certificate.
  10. Save.

The provider should appear in the SAML/WS-Fed identity providers list.

Microsoft Graph alternative

Extract the entity ID, SSO URL, and base64 certificate from GoogleIDPMetadata.xml. Remove all whitespace from the certificate and save a request body such as:

{
  "@odata.type": "#microsoft.graph.samlOrWsFedExternalDomainFederation",
  "displayName": "Fabrikam Google Workspace",
  "issuerUri": "https://accounts.google.com/o/saml2?idpid=<IDPID>",
  "passiveSignInUri": "https://accounts.google.com/o/saml2/idp?idpid=<IDPID>",
  "preferredAuthenticationProtocol": "saml",
  "domains": [
    {
      "@odata.type": "microsoft.graph.externalDomainName",
      "id": "fabrikam.io"
    }
  ],
  "signingCertificate": "<BASE64-CERTIFICATE-WITHOUT-WHITESPACE>"
}

Create the federation:

az rest --method POST `
  --url "https://graph.microsoft.com/v1.0/directory/federationConfigurations" `
  --body "@federation.json" `
  --headers "Content-Type=application/json"

Allow at least 5-10 minutes before testing.

Check invitation redemption order

For B2B collaboration in a workforce tenant, SAML/WS-Fed identity providers should be ahead of social identity providers in the invitation redemption order.

In Entra, review the default inbound cross-tenant access settings and place SAML/WS-Fed identity providers first when necessary.

You can inspect the current policy with Microsoft Graph:

az rest --method GET `
  --url "https://graph.microsoft.com/beta/policies/crossTenantAccessPolicy/default?`$select=invitationRedemptionIdentityProviderConfiguration"

Invite Workspace users into Entra

Invite a user in the Entra admin center

  1. Open Entra ID > Users.
  2. Select New user > Invite external user.
  3. Enter the user's Workspace primary email and display name.
  4. Send the invitation.
  5. Open the resulting guest profile and record its Entra object ID.
  6. Add an ordinary portal user to FLLM-Users.
  7. Add an administrative user to FLLM-Admins only when Management Portal access is required.

Reinviting an existing pending guest reuses the account and creates a new redemption link.

Microsoft Graph alternative

Create invitation.json:

{
  "invitedUserEmailAddress": "user@fabrikam.io",
  "inviteRedirectUrl": "https://agent.contoso.com",
  "sendInvitationMessage": true
}

Create the invitation:

az rest --method POST `
  --url "https://graph.microsoft.com/v1.0/invitations" `
  --body "@invitation.json" `
  --headers "Content-Type=application/json"

The response contains the guest object ID and invitation redemption URL.

Grant FoundationaLLM access

Entra group membership and FoundationaLLM role assignments are separate authorization layers.

User Portal

In the Management Portal:

  1. Open Security > Role Assignments.
  2. Select Portal Access.
  3. Select User Portal.
  4. Ensure FLLM-Users has the Reader role.

The effective scope is:

providers/FoundationaLLM.Configuration/appConfigurationSets/UserPortal

See Configure Chat User Portal Access.

Agent Portal

For deployments that include the separate Agent Portal, ensure FLLM-Users has the Reader role on:

providers/FoundationaLLM.Configuration/appConfigurationSets/AgentPortal

Management Portal

Ensure FLLM-Admins has the Reader role on:

providers/FoundationaLLM.Configuration/appConfigurationSets/ManagementPortal

See Configure Management Portal Access.

If an Entra enterprise application has Assignment required? enabled, also assign the appropriate group to the corresponding portal enterprise application.

Redeem the invitation

Have the user open the invitation redemption URL in an Incognito or InPrivate browser window that is signed in to Google only with the invited Workspace account.

The expected first-time flow is:

  1. Entra routes the Workspace domain to Google.
  2. Google authenticates the user.
  3. Microsoft displays Permissions requested for the one-time B2B redemption.
  4. The user accepts.
  5. Entra can display Let's keep your account secure and require MFA registration.
  6. The user completes Microsoft Authenticator or another permitted method.
  7. Entra redirects the user to FoundationaLLM.

Do not assume that Google MFA satisfies the FoundationaLLM tenant's Conditional Access or security-default requirements. Plan for one-time Entra authentication-method registration unless the tenant's security policy explicitly provides otherwise.

After redemption, verify:

  • User type is Guest.
  • B2B invitation state is Accepted.
  • The guest has an Entra object ID.
  • The user is a member of the appropriate FoundationaLLM Entra group.

Allow time for propagation

Several independent systems update during first-time setup:

  • Google custom SAML application configuration.
  • Google application user access.
  • Entra SAML/WS-Fed federation configuration.
  • Invitation redemption order.
  • B2B invitation redemption.
  • Entra group membership.
  • FoundationaLLM's Microsoft Graph group lookup.
  • MFA and security-information registration.
  • Browser and token caches.

Allow at least 5-10 minutes after creating the federation before testing. Google organizational-unit and application-access changes can take longer.

During this window:

  1. Do not immediately recreate the federation or guest.
  2. Do not verify the Workspace domain to try to fix routing.
  3. Wait several minutes.
  4. Close the current Incognito or InPrivate session.
  5. Start a new private session to force fresh Google, Entra, and FoundationaLLM tokens.
  6. Navigate directly to the FoundationaLLM portal instead of reusing a stale redirect.

If the B2B invitation state is Accepted, SAML authentication and invitation redemption have succeeded. A subsequent Keep your account secure error is an Entra MFA or security-information registration issue, not a Google SAML federation failure.

Verify the complete FoundationaLLM flow

Use a fresh Incognito or InPrivate session:

  1. Navigate directly to the User Portal, Agent Portal, or Management Portal.
  2. Select Sign in.
  3. Enter the invited Workspace email on the Microsoft sign-in page.
  4. Confirm redirection to Google.
  5. Authenticate with the invited Workspace account.
  6. Complete Entra MFA if prompted.
  7. Confirm return to FoundationaLLM.
  8. Open an agent or perform another API-backed action.
  9. Verify that a Workspace guest without the required FoundationaLLM role assignment is denied access.

FoundationaLLM portal authentication already uses a tenant-specific Entra authority. A separate tenant-qualified Azure Portal URL is not required for the FoundationaLLM portal flow.

The access token presented to FoundationaLLM should be issued by the FoundationaLLM Entra tenant and contain the guest's Entra object ID and the appropriate Core or Management API scope.

Troubleshooting

Entra offers email one-time passcode instead of redirecting to Google

The Workspace domain may exist as an unverified pending domain in the Entra tenant. Delete only the unverified domain entry, allow time for propagation, and retry in a new private session.

Also confirm that SAML/WS-Fed providers have appropriate precedence in the invitation redemption order.

Google returns 403 app_not_configured_for_user

Check:

  • The Google SAML application's user access is enabled for the user's organizational unit or access group.
  • The browser is signed in with the invited Workspace account.
  • The Entity ID is https://login.microsoftonline.com/<TENANT-ID>/ with a trailing slash.
  • The configuration has had time to propagate.

If Google's Test SAML login works but service-provider-initiated sign-in fails, check the Entity ID first. Do not use urn:federation:MicrosoftOnline.

Google Test SAML login returns AADSTS50107

Direct federation is service-provider initiated. Google's test button starts an identity-provider-initiated flow and can return AADSTS50107: requested federation realm object does not exist.

Test with the Entra invitation redemption URL or the FoundationaLLM portal instead.

A preexisting guest still uses email one-time passcode

The guest might have redeemed the invitation before SAML federation was configured. Reset the guest's redemption status from its Entra profile, then have the user redeem again through Google.

Keep your account secure fails

Record the error code, correlation ID, and UTC timestamp.

  1. Wait 5-10 minutes and retry in a new private browser session.
  2. Open Entra ID > Diagnose & solve problems > Sign-in diagnostic.
  3. Review Conditional Access, authentication methods, and security-information registration policies.

If error 500121 occurs after Google authentication, inspect the guest's registered authentication methods. Remove an orphaned method when appropriate, revoke sessions, and have the user register again.

FoundationaLLM returns access denied

  • Confirm the guest is a member of FLLM-Users or FLLM-Admins.
  • Confirm the group has the required FoundationaLLM Reader role on the relevant portal configuration scope.
  • If enterprise application assignment is required, confirm that assignment.
  • Wait for membership propagation and sign in again to obtain fresh tokens.

Maintenance

Keep the Workspace domain external

Do not verify the Workspace domain in the FoundationaLLM Entra tenant while direct federation is in use. Domain verification changes home-realm discovery and is incompatible with this B2B direct-federation model.

Rotate the Google SAML signing certificate

Track the signing certificate's expiration from the Google metadata.

Before expiration:

  1. Generate a new certificate from the Google SAML application's Manage certificates page.
  2. Download updated metadata.
  3. In Entra, open External Identities > All identity providers > Custom.
  4. Edit the Workspace provider and update its configuration and signing certificate.
  5. Test with a pilot guest before the previous certificate expires.

If the Entra federation does not have a metadata URL configured, certificate renewal is manual.

Onboard and remove users

  • Invite new Workspace users and add them to the appropriate FoundationaLLM Entra group.
  • Remove group membership to revoke FoundationaLLM authorization.
  • Delete the B2B guest when access is no longer required.
  • Revoke active sessions when immediate termination is required.