Configure Consumer Gmail Federation Through Microsoft Entra ID

This guide configures consumer Gmail accounts as Microsoft Entra B2B guest identities for FoundationaLLM.

The resulting authentication flow is:

Consumer Gmail account
  -> Google 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: The built-in Google federation provider described here is intended for consumer Gmail accounts. Use SAML/WS-Fed federation for Google Workspace domains.

Prerequisites

Before starting, collect:

The Microsoft Entra tenant ID.
The tenant's initial domain, such as contoso.onmicrosoft.com.
The User Portal or Agent Portal URL.
A Google account that can own or administer a Google Cloud project.
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 group.
A consumer Gmail account for testing.

For production, create the Google Cloud project under an organization-controlled Google Workspace or Cloud Identity account. A personal Gmail account can be used for a proof of concept, but enable multifactor authentication and add another trusted project owner.

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

Locate the Entra tenant values

Tenant ID

In the Microsoft Entra admin center, open Entra ID > Overview and record the Tenant ID.

Initial domain

Open Entra ID > Domain names > Custom domain names and locate the domain marked Initial. It ends in .onmicrosoft.com.

The custom primary domain is not a substitute for the initial domain when configuring the Google redirect URI.

You can also retrieve the initial domain from Azure Cloud Shell:

az rest --method GET `
  --url "https://graph.microsoft.com/v1.0/domains?`$select=id,isInitial" `
  --query "value[?isInitial].id" -o tsv

Use the canonical lowercase form of the initial domain in redirect URIs. Google performs strict redirect URI matching, and the tenant domain is part of the URI path.

Create the Google Cloud OAuth application

Create or select a project

Sign in to the Google Cloud console.
Create or select the project that will contain the federation OAuth client.
Open Google Auth Platform > Overview.
Select Get started if Google Auth Platform has not been configured.

Configure Google Auth Platform

Enter:

App name: A recognizable value such as FoundationaLLM Entra Federation.
User support email: An actively monitored address.
Audience: External.
Contact email: An actively monitored address.

Accept the Google API Services policy and create the configuration.

Create the OAuth client

Open Google Auth Platform > Clients.
Select Create client.
Set Application type to Web application.
Enter a name such as Microsoft Entra B2B.
Add these authorized redirect URIs:

https://login.microsoftonline.com
https://login.microsoftonline.com/te/<TENANT-ID>/oauth2/authresp
https://login.microsoftonline.com/te/<INITIAL-DOMAIN>/oauth2/authresp

For example:

https://login.microsoftonline.com
https://login.microsoftonline.com/te/11111111-2222-3333-4444-555555555555/oauth2/authresp
https://login.microsoftonline.com/te/contoso.onmicrosoft.com/oauth2/authresp

Create the client.
Securely record the client ID and client secret.

Do not place the Google client secret in FoundationaLLM App Configuration, source control, portal environment files, or support messages.

Configure Google federation in Entra

Sign in to the Microsoft Entra admin center.
Confirm that the active directory is the tenant hosting FoundationaLLM.
Open Entra ID > External Identities > All identity providers.
On the Built-in tab, locate Google and select Configure.
Enter the Google OAuth client ID and client secret.
Save the identity provider.

The Google credentials belong only in this identity provider configuration. Do not add them to a FoundationaLLM app registration.

Prepare a Gmail test user

Allow the test account in Google

In Google Auth Platform > Audience, check the publishing status:

If the application is in Testing, add the exact Gmail test address under Test users.
If the application is in production, a separate test-user entry is not required.

Keep the application in Testing until the initial end-to-end validation succeeds.

Invite the user into Entra

In Entra, open Entra ID > Users.
Select New user > Invite external user.
Enter the exact Gmail address configured as the Google test user.
Send the invitation.
Add the resulting guest user to the FLLM-Users Entra security group.
Have the user open the invitation in an Incognito or InPrivate browser window.
The user must redeem the invitation with the same Google account that was invited.

After redemption, verify:

User type is Guest.
B2B invitation state is Accepted.
The guest has an Entra object ID.
Google is associated with the external identity.

The guest's Entra user principal name can appear in an externalized form such as:

gmail-name_gmail.com#EXT#@contoso.onmicrosoft.com

This is expected. FoundationaLLM authorization uses the stable Entra object ID and group memberships.

Grant FoundationaLLM access

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

User Portal

In the Management Portal:

Open Security > Role Assignments.
Select Portal Access.
Select User Portal.
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

Only add administrative users to FLLM-Admins. Ensure that group 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.

Complete multifactor authentication registration

Conditional Access or Entra security defaults can display Let's keep your account secure after the guest authenticates with Google.

This is expected. Google federation supplies the primary authentication, while Entra can still require an additional authentication method. Select Next and complete the available method, typically Microsoft Authenticator.

After registration, Entra should return the user to the requested portal. If it does not, close the Incognito session and start a new portal sign-in.

Allow time for propagation

Several independent systems update during first-time setup:

Google OAuth client and audience configuration.
Entra external identity provider configuration.
B2B invitation redemption.
Entra group membership.
FoundationaLLM's Microsoft Graph group lookup.
MFA and security-information registration.
Browser and token caches.

Allow approximately 5-10 minutes after creating the identity provider or redeeming the first invitation before treating a failure as persistent. Group membership and newly registered authentication methods can also require several minutes to become consistently visible.

During this window:

Do not immediately recreate the guest, rotate the OAuth secret, or disable MFA.
Wait a few minutes.
Close the current Incognito or InPrivate session.
Start a new private session to force fresh Entra and FoundationaLLM tokens.
Navigate directly to the FoundationaLLM portal instead of reusing the invitation link.

A transient InternalServerError on the Keep your account secure page immediately after invitation redemption can be caused by this propagation window. If the B2B invitation state is Accepted, Google authentication and invitation redemption have already succeeded. Retry MFA registration after the propagation delay.

Verify the complete flow

Use a fresh Incognito or InPrivate session:

Navigate directly to the User Portal or Agent Portal.
Select Sign in.
Enter the invited Gmail address on the Microsoft sign-in page.
Confirm redirection to Google.
Authenticate with the invited Google account.
Complete Entra MFA if prompted.
Confirm return to FoundationaLLM.
Open an agent and perform an API-backed action.
Verify that a Gmail guest without the required FoundationaLLM role assignment is denied access.

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

Troubleshooting

Google access is blocked

Confirm the Google application audience is External.
If its publishing status is Testing, add the exact Gmail address as a test user.
Confirm all three redirect URIs exactly match the configured values.
Confirm that the invited account is the Google account selected during sign-in.

B2B invitation is accepted, but Keep your account secure fails

The Google federation step succeeded. Record the error code, correlation ID, and UTC timestamp.

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

The security-registration failure might not appear as a failed sign-in because primary authentication already succeeded.

Search by the guest's Entra object ID or externalized UPN instead of the original Gmail address. Clear status filters and inspect all interactive sign-ins around the UTC timestamp.

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.

Redirect URI errors

Confirm that the initial domain, not the custom primary domain, is used in the third Google redirect URI. Keep the initial domain lowercase.

Move from testing to production

After successful validation:

Review the Google Auth Platform branding and contact details.
Publish the Google application for external use.
Verify whether Google requires application verification.
Add a second trusted Google Cloud project owner.
Document ownership and recovery procedures.
Establish a client-secret rotation process.
Review Entra external collaboration and Conditional Access policies before onboarding additional users.

Table of Contents