Manage Domain Mapping for Federated Authentication
On this page
- OAuth 2.0 authentication for programmatic access to Cloud Manager is available as a Preview feature.
- The feature and the corresponding documentation might change at any time during the Preview period. To use OAuth 2.0 authentication, create a service account to use in your requests to the Cloud Manager Public API.
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 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.
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 Cloud Manager. To learn how to link an IdP to Cloud Manager, 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
In MongoDB Cloud Manager, 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.
Enter domain mapping information.
Click Add a Domain.
On the Domains screen, click Add Domain.
Enter the following information for your domain mapping:
FieldDescriptionDisplay NameName to easily identify the domain.Domain NameDomain name to map.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.
Click HTML File Upload.
Click Next.
Download the
mongodb-site-verification.html
file that Cloud Manager 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 Cloud Manager 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 Cloud Manager provides to your domain.
Return to Cloud Manager and click Finish.
Associate Your Domain with Your Identity Provider
After successfully verifying your domain, associate the domain with your IdP:
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 Cloud Manager 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.
To test the integration between your domain and your IdP:
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 Cloud Manager.
Note
You can bypass the Cloud Manager 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
In MongoDB Cloud Manager, 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.
Delete the Domain
In MongoDB Cloud Manager, 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.
Delete the domain.
Important
You cannot delete a domain mapping if it is associated with an IdP. To disassociate a domain from an IdP:
From the management console, click Identity Providers in the left navigation.
For the IdP you want to disassociate from your domain, click next to Associated Domains.
Deselect the domain desired domain.
Click Confirm.
To delete a domain from the Federation Management instance:
Click Add a Domain.
Open the Actions menu for the domain you want to delete.
Click Delete.
Click Confirm.