Configure Federated Authentication from Google Workspace
On this page
This guide shows you how to configure federated authentication using Google Workspace as your IdP.
After integrating Google Workspace and Atlas, you can use your company's credentials to log in to Atlas and other MongoDB cloud services.
Limitations
Atlas doesn't support single sign-on integration for database users. If you implement Google Workspace as your IdP, you cannot use the Log In with Google social login option.
Required Access
To manage federated authentication, you must have
Organization Owner
access to one or more organizations that are
delegating federation settings to the instance.
Prerequisites
To use Google Workspace as an IdP for Atlas, you must have:
A Google Workspace subscription. To obtain a subscription, visit the Google Workspace portal.
A Google Workspace user with administrative privileges. To grant a user administrative privileges, see Make a user an admin. Alternatively, you may use the default administrative user created upon activation of your Google Workspace account.
Procedures
Configure Google Workspace as an Identity Provider
Use the Google Workspace admin console to configure Google Workspace as a SAML IdP.
Add a new application to your Google Workspace account.
In your Google Workspace administrator account, open the Apps dropdown menu and click Web and mobile apps.
Open the Add App dropdown menu and click Add custom SAML app.
Enter a name to identify the app , such as "MongoDB Cloud," in the App name field.
Select an App icon if desired.
Click the Continue button.
In Atlas, go to the Organization Settings page.
If it's not already displayed, select your desired organization from the Organizations menu in the navigation bar.
Click the Organization Settings icon next to the Organizations menu.
The Organization Settings page displays.
Provide Google Workspace Credentials to Atlas.
Click Identity Providers in the left-hand pane. If you have previously configured an IdP, click Add Identity Provider in the upper-right corner of the page, then click Setup Identity Provider. If you have not previously configured an IdP, click Setup Identity Provider.
On the Create Identity Provider screen, enter the following information:
FieldValueConfiguration NameA descriptive name that identifies the configuration.Issuer URIEntity ID that you received from Google Workspace in the previous step.Single Sign-On URLSSO URL that you received from Google Workspace in the previous step.Identity Provider Signature Certificate.cer
file that you received from Google Workspace in the previous step.You can either:
Upload the certificate from your computer
Paste the contents of the certificate into a text box
Request BindingHTTP POST
Response Signature AlgorithmSHA-256
Click the Next button.
Provide Atlas Metadata to Google Workspace.
Return to the Google Workspace configuration page and click the Continue button.
Fill in the data fields with the following values:
FieldValueACS URLThe Assertion Consumer Service URL provided by Atlas.Entity IDThe Audience URI provided by Atlas.Start URLThe Login URL provided by Atlas.Signed ResponseCheck this box.Name ID FormatUNSPECIFIED
Name IDBasic Information > Primary Email
Click the Continue button.
Configure Google Workspace Attributes.
In Google Workspace, add each of the following value pairs as distinct mappings by clicking the Add Mapping button for each pair. App attribute values are case-sensitive.
Google Directory attributesApp attributesBasic Information > First namefirstName
Basic Information > Last namelastName
If you are configuring role mapping, proceed to the next step. Otherwise, click the Finish button and proceed to Enable User Access via Google Workspace.
(Optional) Configure role mapping.
To configure role mapping in Google Workspace, create a single group attribute in the Group membership (optional) section as follows:
Google groupsSearch for and select all Google groups which you intend to map to Atlas roles, ensuring that they are all included in a single row. For more information on this attribute, consult About group membership mapping.App attributesmemberOf
Click the Finish button.
Enable User Access via Google Workspace.
Click the arrow in the top-right corner of the User Access panel to expand it.
Enable user access. You can either:
Click ON for everyone in the Service status pane to enable federated authentication for all users in your Google Workspace.
Select specific Groups or Organizational Units from the collapsible menus on the left for which you wish to enable federated authentication. The Google Workspace help pages provide more information on managing Groups and Organizational Units.
Map your Domain
Mapping your domain to the IdP lets Atlas know that users from your domain should be directed to the Login URL for your identity provider configuration.
When users visit the Atlas login page, they enter their email address. If the email domain is associated with an IdP, they are sent to the Login URL for that IdP.
Important
You can map a single domain to multiple identity providers. If you do, users who log in using the MongoDB Cloud console are automatically redirected to the first matching IdP mapped to the domain.
To log in using an alternative identity provider, users must either:
Initiate the MongoDB Cloud login through the desired IdP, or
Log in using the Login URL associated with the desired IdP.
Use the Federation Management Console to map your domain to the IdP:
Open the FMC.
In Atlas, go to the Organization Settings page.
If it's not already displayed, select your desired organization from the Organizations menu in the navigation bar.
Click the Organization Settings icon next to the Organizations menu.
The Organization Settings page displays.
In Manage Federation Settings, click Open Federation Management App.
Enter domain mapping information.
Click Add a Domain.
On the Domains screen, click Add Domain.
Enter the following information for your domain mapping:
FieldDescriptionDisplay NameLabel to easily identify the domain.Domain NameDomain name to map.Click Next.
Choose your domain verification method.
Note
You can choose the verification method once. It cannot be modified. To select a different verification method, delete and recreate the domain mapping.
Select the appropriate tab based on whether you are verifying your domain by uploading an HTML file or creating a DNS TXT record:
Upload an HTML file containing a verification key to verify that you own your domain.
Click HTML File Upload.
Click Next.
Download the
mongodb-site-verification.html
file that Atlas provides.Upload the HTML file to a web site on your domain. You must be able to access the file at
<https://host.domain>/mongodb-site-verification.html
.Click Finish.
Create a DNS TXT record with your domain provider to verify that you own your domain. Each DNS record associates a specific Atlas organization with a specific domain.
Click DNS Record.
Click Next.
Copy the provided TXT record. The TXT record has the following form:
mongodb-site-verification=<32-character string> Log in to your domain name provider (such as GoDaddy.com or networksolutions.com).
Add the TXT record that Atlas provides to your domain.
Return to Atlas and click Finish.
Verify your domain.
The Domains screen displays both unverified and verified domains you've mapped to your IdP. To verify your domain, click the target domain's Verify button. Atlas shows whether the verification succeeded in a banner at the top of the screen.
Associate Your Domain with Your Identity Provider
After successfully verifying your domain, use the Federation Management Console to associate the domain with Google Workspace:
Click Identity Providers in the left navigation.
For the IdP you want to associate with your domain, click Edit next to Associated Domains.
Select the domain you want to associate with the IdP.
Click Confirm.
Test Your Domain Mapping
Important
Before you begin testing, copy and save the Bypass SAML Mode URL for your IdP. Use this URL to bypass federated authentication in the event that you are locked out of your Atlas organization.
While testing, keep your session logged in to the Federation Management Console to further ensure against lockouts.
To learn more about Bypass SAML Mode, see Bypass SAML Mode.
Use the Federation Management Console to test the integration between your domain and Google Workspace:
In a private browser window, navigate to the Atlas log in page.
Enter a username (usually an email address) with your verified domain.
Example
If your verified domain is mongodb.com
, use an email
address of the form username@mongodb.com
.
Click Next. If you mapped your domain correctly, you'll be redirected to your IdP to authenticate. Upon successful authentication, you'll be redirected back to Atlas.
Note
You can bypass the Atlas log in page by navigating directly to your IdP Login URL.
(Optional) Map an Organization
Use the Federation Management Console to assign your domain's users access to specific Atlas organizations:
In Atlas, go to the Organization Settings page.
If it's not already displayed, select your desired organization from the Organizations menu in the navigation bar.
Click the Organization Settings icon next to the Organizations menu.
The Organization Settings page displays.
Connect an organization to the Federation Application.
Click View Organizations.
Atlas displays all organizations where you are an
Organization Owner
.Organizations which are not already connected to the Federation Application have Connect button in the Actions column.
Click the desired organization's Connect button.
Apply an Identity Provider to the organization.
From the Organizations screen in the management console:
Click the Name of the organization you want to map to an IdP.
On the Identity Provider screen, click Apply Identity Provider.
Atlas directs you to the Identity Providers screen which shows all IdPs you have linked to Atlas.
For the IdP you want to apply to the organization, click Add Organizations.
In the Apply Identity Provider to Organizations modal, select the organizations to which this IdP applies.
Click Confirm.
(Optional) Configure Advanced Federated Authentication Options
You can configure the following advanced options for federated authentication for greater control over your federated users and authentication flow:
Note
The following advanced options for federated authentication require you to map an organization.
Sign in to Atlas Using Your Login URL
All users that you assign to the Google Workspace application can log in to Atlas using their Google Workspace credentials on the Login URL. Users have access to the organizations you mapped to your IdP.
Important
You can map a single domain to multiple identity providers. If you do, users who log in using the MongoDB Cloud console are automatically redirected to the first matching IdP mapped to the domain.
To log in using an alternative identity provider, users must either:
Initiate the MongoDB Cloud login through the desired IdP, or
Log in using the Login URL associated with the desired IdP.
If you select a default organization role, new users who log in to Atlas using the Login URL have the role you specify