> For the complete MongoDB documentation index, see www.mongodb.com/docs/llms.txt # Configure Federated Authentication from Google Workspace This guide shows you how to configure federated authentication using Google Workspace as your IdP (Identity Provider). After integrating Google Workspace and Atlas, you can use your company's credentials to log in to Atlas and other MongoDB cloud services. **Note:** Atlas now supports SSO (Single Sign-On) for database users through [Authentication and Authorization with OIDC/OAuth 2.0.](https://www.mongodb.com/docs/atlas/security-oidc.md#std-label-oidc-authentication-authorization) ## Required Access To manage federated authentication, you must have [`Organization Owner`](https://www.mongodb.com/docs/atlas/reference/user-roles.md#mongodb-authrole-Organization-Owner) access to one or more organizations that are delegating federation settings to the instance. ## Prerequisites To use Google Workspace as an IdP (Identity Provider) for Atlas, you must have: - A Google Workspace subscription. To obtain a subscription, visit the [Google Workspace portal.](https://workspace.google.com) - A Google Workspace user with administrative privileges. To grant a user administrative privileges, see [Make a user an admin](https://support.google.com/a/answer/172176?hl=en\&ref_topic=2785005). Alternatively, you may use the default administrative user created upon activation of your Google Workspace account. ## Procedures Throughout the following procedure, it is helpful to have one browser tab open to your [Atlas Federation Management Console](https://www.mongodb.com/docs/atlas/security/federated-authentication.md#std-label-atlas-federated-authentication) and one tab open to your Google Workspace admin console. ### Configure Google Workspace as an Identity Provider Use the Google Workspace admin console to configure Google Workspace as a SAML (Security Assertion Markup Language) IdP (Identity Provider). 1. 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. 2. Retrieve SSO credentials from Google Workspace. Navigate to the Option 2 section. Copy the SSO URL and Entity ID, and download the Certificate provided. These will be used by the FMC (Federation Management Console) in a subsequent step. Leave this page open. 3. In Atlas, go to the Federation Management console for your organization. If it's not already displayed, select your desired organization from the Organizations menu in the navigation bar. In the sidebar, click Federation under the Identity & Access heading. Click Open Federation Management App. The [Federation](https://cloud.mongodb.com/go?l=https%3A%2F%2Fcloud.mongodb.com%2Fv2%23%2Forg%2F%3Corganization%3E%2Ffederation) page displays. 4. Provide Google Workspace Credentials to Atlas. Click Identity Providers in the left-hand pane. If you have previously configured an IdP (Identity Provider), 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 (Identity Provider), click Setup Identity Provider. On the Create Identity Provider screen, enter the following information: | Field | Value | | --- | --- | | Configuration Name | A descriptive name that identifies the configuration. | | Issuer URI | Entity ID that you received from Google Workspace in the previous step. | | Single Sign-On URL | SSO 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 Binding | `HTTP POST` | | Response Signature Algorithm | `SHA-256` | Click the Next button. 5. Get Atlas Metadata for Google Workspace. In the FMC (Federation Management Console), copy the Assertion Consumer Service URL and Audience URI. Click the Finish button. Copy the Login URL on the IdP (Identity Provider) tile that Google Workspace creates for your application. 6. 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: | Field | Value | | --- | --- | | ACS URL | The Assertion Consumer Service URL provided by Atlas. | | Entity ID | The Audience URI provided by Atlas. | | Start URL | The Login URL provided by Atlas. | | Signed Response | Check this box. | | Name ID Format | `UNSPECIFIED` | | Name ID | `Basic Information > Primary Email` | Click the Continue button. 7. 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 attributes | App attributes | | --- | --- | | Basic Information > First name | `firstName` | | Basic Information > Last name | `lastName` | 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**. 8. (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 groups | Search 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.](https://support.google.com/a/answer/11143403?hl=en) | | --- | --- | | App attributes | `memberOf` | Click the Finish button. 9. 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](https://support.google.com/a/topic/25838?hl=en\&ref_topic=9197) and [Organizational Units.](https://support.google.com/a/answer/182537?hl=en) #### Map your Domain Mapping your domain to the IdP (Identity Provider) 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:** When you map a single domain to multiple identity providers, users who log in using the MongoDB Cloud console are automatically redirected to the IdP (Identity Provider) associated with the first SAML (Security Assertion Markup Language) IdP (Identity Provider) application that was configured for Atlas. To use an alternative identity provider, users must log in through either an SP-initiated or IdP-initiated login URL. Use the Federation Management Console to map your domain to the IdP (Identity Provider): 1. In Atlas, go to the Federation Management console for your organization. If it's not already displayed, select your desired organization from the Organizations menu in the navigation bar. In the sidebar, click Federation under the Identity & Access heading. Click Open Federation Management App. The [Federation](https://cloud.mongodb.com/go?l=https%3A%2F%2Fcloud.mongodb.com%2Fv2%23%2Forg%2F%3Corganization%3E%2Ffederation) page displays. 2. Enter domain mapping information. Click Add a Domain. On the Domains screen, click Add Domain. Enter the following information for your domain mapping: | Field | Description | | --- | --- | | Display Name | Label to easily identify the domain. | | Domain Name | [Domain name](https://en.wikipedia.org/wiki/Domain_name) to map. | Click Next. 3. 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 (Hypertext Markup Language) file or creating a DNS (Domain Name System) TXT record: ### Upload HTML File Upload an HTML (Hypertext Markup Language) 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 (Hypertext Markup Language) file to a web site on your domain. You must be able to access the file at `/mongodb-site-verification.html`. Click Finish. 4. Verify your domain. The Domains screen displays both unverified and verified domains you've mapped to your IdP (Identity Provider). 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. 5. Delete the provided record file. **Important:** To avoid a potential security vulnerability, delete the provided record file after verification completes. #### Associate Your Domain with Your Identity Provider After successfully verifying your domain, use the Federation Management Console to associate the domain with Google Workspace: 1. Click Identity Providers in the left navigation. 2. For the IdP (Identity Provider) you want to associate with your domain, click Edit next to Associated Domains. 3. Select the domain you want to associate with the IdP (Identity Provider). 4. Click Confirm. #### Test Your Domain Mapping **Important:** Before you begin testing, copy and save the [Bypass SAML Mode](https://www.mongodb.com/docs/atlas/security/federation-advanced-options.md#std-label-bypass-saml) URL (Uniform Resource Locator) for your IdP (Identity Provider). 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.](https://www.mongodb.com/docs/atlas/security/federation-advanced-options.md#std-label-bypass-saml) Use the Federation Management Console to test the integration between your domain and Google Workspace: 1. In a private browser window, navigate to the Atlas log in page. 2. 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`. 3. Click Next. If you mapped your domain correctly, you'll be redirected to your IdP (Identity Provider) 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 (Identity Provider) Login URL. ### (Optional) Map an Organization Use the Federation Management Console to assign your domain's users access to specific Atlas organizations: 1. In Atlas, go to the Federation Management console for your organization. If it's not already displayed, select your desired organization from the Organizations menu in the navigation bar. In the sidebar, click Federation under the Identity & Access heading. Click Open Federation Management App. The [Federation](https://cloud.mongodb.com/go?l=https%3A%2F%2Fcloud.mongodb.com%2Fv2%23%2Forg%2F%3Corganization%3E%2Ffederation) page displays. 2. Connect an organization to the Federation Application. Click Link Organizations. Atlas displays all organizations where you are an [`Organization Owner`.](https://www.mongodb.com/docs/atlas/reference/user-roles.md#mongodb-authrole-Organization-Owner) Organizations which are not already connected to the Federation Application have Configure Access button in the Actions column. Click the desired organization's Configure Access button. 3. Apply an Identity Provider to the organization. On the Identity Provider screen, click Connect Identity Provider. Atlas directs you to the Identity Providers screen which shows all IdPs (Identity Providers) you have linked to Atlas. For the IdP (Identity Provider) you want to apply to the organization, click Connect. In the Apply Identity Provider to Organizations modal, select the organizations to which this IdP (Identity Provider) applies. Click Confirm. 4. Connect an organization to the Federation Application. Click Linked Organizations in the left navigation. In the list of Organizations, ensure that your desired organizations now have the expected Identity Provider. ### (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: - [Bypass SAML Mode](https://www.mongodb.com/docs/atlas/security/federation-advanced-options.md#std-label-bypass-saml) **Note:** The following advanced options for federated authentication require you to [map an organization.](https://www.mongodb.com/docs/atlas/security/federated-auth-google-ws.md#std-label-google-ws-map-org) - [Assign a Default User Role for an Organization](https://www.mongodb.com/docs/atlas/security/federation-advanced-options.md#std-label-advanced-option-default-role) - [Restrict Access to an Organization by Domain](https://www.mongodb.com/docs/atlas/security/federation-advanced-options.md#std-label-restrict-org-access-by-domain) - [Restrict User Membership to the Federation](https://www.mongodb.com/docs/atlas/security/federation-advanced-options.md#std-label-restrict-fed-user-membership) ## 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 (Identity Provider). **Important:** When you map a single domain to multiple identity providers, users who log in using the MongoDB Cloud console are automatically redirected to the IdP (Identity Provider) associated with the first SAML (Security Assertion Markup Language) IdP (Identity Provider) application that was configured for Atlas. To use an alternative identity provider, users must log in through either an SP-initiated or IdP-initiated login URL. If you select a default organization role, new users who log in to Atlas using the Login URL have the role you specify