Navigation

Manage Domain Mapping for Federated Authentication

You can map domains to your IdP to streamline the login experience for users from specified domains by authenticating them through an IdP. Domain mapping ensures that all users with a particular domain in their email address have the same login experience.

Important

You can map a single domain to multiple identity providers. If you do, users who log in using that domain must authenticate using the Login URL associated with the desired IdP. If users attempt to use that domain on the Atlas login screen, Atlas returns an error.

To map a domain to your IdP, you must verify that you own the domain. You can either:

  • Upload an HTML file containing a verification key to a host in your domain or
  • Create a DNS TXT record that contains a verification key.

Prerequisites

To complete this tutorial, you must have already linked an IdP to Atlas. To learn how to link an IdP to Atlas, see Manage Identity Providers.

Federation Management Access

You can manage federated authentication from the Federation Management Console. You can access the console as long as you are an Organization Owner in one or more organizations that are delegating federation settings to the instance.

Map a Domain to Your Identity Provider

Open the Federation Management Console

  1. Log in to Atlas.
  2. From the Context dropdown in the left navigation, select the organization for which you want to manage federation settings.
  3. Click Settings in the left navigation.
  4. In Manage Federation Settings, click Visit Federation Management App.

Enter Domain Mapping Information

  1. Click Add a Domain.

  2. On the Domains screen, click Add Domain.

  3. Enter the following information for your domain mapping:

    Field Description
    Display Name Name to easily identify the domain.
    Domain Name Domain name to map.
  4. Click Next.

Choose How to Verify Your Domain

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.

  1. Click HTML File Upload.
  2. Click Next.
  3. Download the mongodb-site-verification.html file that Atlas provides.
  4. 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.
  5. 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.

  1. Click DNS Record.

  2. Click Next.

  3. Copy the provided TXT record. The TXT record has the following form:

    mongodb-site-verification=<32-character string>
    
  4. Log in to your domain name provider (such as GoDaddy.com or networksolutions.com).

  5. Add the TXT record that Atlas provides to your domain.

  6. 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, associate the domain with your IdP:

  1. Click Identity Providers in the left navigation.
  2. For the IdP you want to associate with your domain, click pencil icon next to Associated Domains.
  3. Select the domain you want to associate with the IdP.
  4. Click Confirm.

Test Your Domain Mapping

Important

While testing, keep your session logged in to the Federation Management Console. If you log out while your federation is not properly configured, you may get locked out of your account.

To test the integration between your domain and your IdP:

  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, enter alice@mongodb.com.

  3. Click Next.

If you mapped your domain correctly, you’re redirected to your IdP to authenticate. If authenticating with your IdP succeeds, you’re redirected back to Atlas.

Note

You can bypass the Atlas log in page by navigating directly to your IdP’s Login URL. The Login URL takes you directly to your IdP to authenticate.

Delete a Domain Mapping

Open the Federation Management Console

  1. Log in to Atlas.
  2. From the Context dropdown in the left navigation, select the organization for which you want to manage federation settings.
  3. Click Settings in the left navigation.
  4. In Manage Federation Settings, click Visit Federation Management App.

Delete the Domain

Important

You cannot delete a domain mapping if it is associated with an IdP. To disassociate a domain from an IdP:

  1. From the management console, click Identity Providers in the left navigation.
  2. For the IdP you want to disassociate from your domain, click pencil icon next to Associated Domains.
  3. Deselect the domain desired domain.
  4. Click Confirm.

To delete a domain from the Federation Management instance:

  1. Click Add a Domain.
  2. Open the Actions menu for the domain you want to delete.
  3. Click Delete.
  4. Click Confirm.