> For the complete MongoDB documentation index, see www.mongodb.com/docs/llms.txt # Configure Federated Authentication from Okta This guide shows you how to configure federated authentication using Okta as your IdP (Identity Provider). After integrating Okta 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) If you are using Okta's built-in MongoDB Cloud app, you can use [Okta's documentation.](https://saml-doc.okta.com/SAML_Docs/How-to-Configure-SAML-2.0-for-MongoDB-Cloud.html) If you are creating your own SAML app, use the procedures described here. ## 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 Okta as an IdP (Identity Provider) for Atlas, you must have: - An [Okta account.](https://www.okta.com/) - A custom, routable domain name. ## 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 Okta account. ### Configure Okta as an Identity Provider Use your Okta account to configure Okta as a SAML (Security Assertion Markup Language) IdP (Identity Provider). 1. Download your Okta origination certificate. In your Okta account, click Admin in the upper right corner to access the Administrator environment. In the left-hand pane, navigate to Applications -> Applications. Click Create App Integration. Select SAML 2.0 for the Sign-in method and click Next. Fill in the App name text field with your desired application name. Optionally, add a logo image and set app visibility. Click Next. On the Configure SAML screen, enter the following information: | Field | Value | | --- | --- | | Single sign-on URL | `http://localhost` | | Audience URI | `urn:idp:default` | **Important:** These are placeholder values and are **not** intended for use in production. You will replace them in a later step. Leave the other fields empty or set to their default values and click Next at the bottom of the page. On the Feedback screen, select I'm an Okta customer adding an internal app and click Finish. At the bottom of the page under the heading SAML Signing Certificates, locate the newest certificate with a Status of `Active`--this is the certificate you just created. Click Actions and select Download certificate from the drop-down menu. The generated certificate is a `.cert` file. You must convert it to a `.pem` certificate for use later in this procedure. To do this, open a terminal of your choosing and run the following: ```sh openssl x509 -in path/to/mycert.crt -out path/to/mycert.pem -outform PEM ``` 2. 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. 3. Provide Okta 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 Configure Identity Provider screen, enter the following information: | Field | Value | | --- | --- | | Configuration Name | Descriptive label that identifies the configuration | | Issuer URI | Fill with Placeholder Values | | Single Sign-On URL | Fill with Placeholder Values | | Identity Provider Signature Certificate | Certificate you received from Okta in a prior step | | Request Binding | `HTTP POST` | | Response Signature Algorithm | `SHA-256` | Click the Next button to see the values for the Okta configuration. Click Finish. 4. Configure your SAML integration. In your Okta account, return to the page for your SAML application and ensure the General tab is selected. In the SAML Settings pane, click Edit. On the General Settings page, click Next. On the Configure SAML screen, enter the following information: | Okta Data Field | Value | | --- | --- | | Single sign on URL | Assertion Consumer Service URL from the Atlas FMC. Checkboxes: Check Use this for Recipient URL and Destination URL.; Clear Allow this app to request other SSO URLs. | | Audience URI (SP Entity ID) | Audience URI from the Atlas FMC. | | Default RelayState | Optionally, add a RelayState URL to your IdP (Identity Provider) to send users to a URL you choose and avoid unnecessary redirects after login. You can use: DestinationRelayState URLMongoDB AtlasLogin URL generated for your identity provider configuration in the Atlas [Federation Management App.](https://www.mongodb.com/docs/atlas/security/federated-authentication.md#std-label-federation-management-access)MongoDB Support Portal`https://auth.mongodb.com/app/salesforce/exk1rw00vux0h1iFz297/sso/saml`MongoDB University`https://auth.mongodb.com/home/mongodb_thoughtindustriesstaging_1/0oadne22vtcdV5riC297/alndnea8d6SkOGXbS297`MongoDB Community Forums`https://auth.mongodb.com/home/mongodbexternal_communityforums_3/0oa3bqf5mlIQvkbmF297/aln3bqgadajdHoymn297`MongoDB Feedback Engine`https://auth.mongodb.com/home/mongodbexternal_uservoice_1/0oa27cs0zouYPwgj0297/aln27cvudlhBT7grX297`MongoDB JIRA`https://auth.mongodb.com/app/mongodbexternal_mongodbjira_1/exk1s832qkFO3Rqox297/sso/saml` | | Name ID format | Unspecified | | Application username | Email | | Update application username on | Create and update | Click the Click Show Advanced Settings link in the Okta configuration page and ensure that the following values are set: | Okta Data Field | Value | | --- | --- | | Response | `Signed` | | Assertion Signature | `Signed` | | Signature Algorithm | `RSA-SHA256` | | Digest Algorithm | `SHA256` | | Assertion Encryption | `Unencrypted` | Leave the remaining Advanced Settings fields in their default state. Scroll down to the Attribute Statements (optional) section and create four attributes with the following values: | Name | Name Format | Value | | --- | --- | --- | | firstName | Unspecified | `user.firstName` | | lastName | Unspecified | `user.lastName` | **Important:** The values in the **Name** column are case-sensitive. Enter them exactly as shown. **Note:** These values may be different if Okta is connected to an Active Directory. For the appropriate values, use the Active Directory fields that contain a user's first name, last name, and full email address. (Optional) If you plan to use [role mapping](https://www.mongodb.com/docs/atlas/security/manage-role-mapping.md#std-label-atlas-manage-fed-auth-roles), scroll down to the Group Attribute Statements (optional) section and create an attribute with the following values: | Name | Name Format | Filter | Value | | --- | --- | --- | --- | | memberOf | Unspecified | Matches regex | `.*` | This filter matches all group names associated with the user. To filter the group names sent to Atlas further, adjust the Filter and Value fields. Click Next at the bottom of the page. On the Feedback screen, click Finish. 5. Replace placeholder values in the Atlas FMC (Federation Management Console). On the Okta application page, click View Setup Instructions in the middle of the page. In the Atlas FMC (Federation Management Console), navigate to the Identity Providers page. Locate your Okta and click Edit. Replace the placeholder values in the following fields: | FMC Data Field | Value | | --- | --- | | Issuer URI | Identity Provider Issuer value from the Okta Setup Instructions page. | | Single Sign-on URL | Identity Provider Single Sign-On URL value from the Okta Setup Instructions page. | | Identity Provider Signature Certificate | Copy the X.509 Certificate from the Okta Setup Instructions page and paste the contents directly. | Click Next. Click Finish. 6. Assign users to your Okta application. On the Okta application page, click the Assignments tab. Ensure that all your Atlas organization users who will use Okta are enrolled. #### 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 Okta: 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 Okta: 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-okta.md#std-label-okta-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 Okta application can log in to Atlas using their Okta 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