Please use the form below to provide your feedback. Because your feedback is valuable to us, the information you submit in this form is recorded in our issue tracking system (JIRA), which is publicly available. You can track the status of your feedback using the ticket number displayed in the dialog once you submit the form.

Add Federated and SSO Authentication

  • Capella Operational
  • how-to
March 23, 2025
+ 12
Add federated authentication with single sign-on (SSO) to your Couchbase Capella organization.

To add federated and SSO authentication, you must create a realm in Capella. A realm manages the configuration of the link between Capella and your IdP. Each organization supports one realm.

This page walks you through the process of creating a realm and configuring your IdP to add federated and SSO authentication to your organization.

Access and Enable SSO Settings

You can manage federated and SSO authentication from the SSO page in your organization’s settings.

You are only able to see the SSO page if you have the Organization Owner role in your organization.

  1. Navigate to the SSO page in Organization Settings:

    1. In the Capella UI, on the navigation bar, click the Settings tab.

    2. In the navigation menu, click SSO.

  2. Enable SSO:

    If not already enabled, enable federated and SSO authentication options by contacting Couchbase. You can do this automatically through the SSO page.

    1. On the SSO page, click Enable SSO.

    2. In the Enable SSO dialog box, click Create Support Ticket.

      The SSO page remains unchanged until support enables SSO for your organization.

Configure Federated and SSO Authentication

While you can configure Capella with other SAML identity providers, Couchbase provides instructions and support for Microsoft Entra ID, Okta, Ping Identity, CyberArk, Google Workspace, and OneLogin.

Choose the tab corresponding to your IdP.

Prerequisites

To configure Entra ID as an IdP, you need:

Procedures

To configure federated and SSO authentication using Entra ID as your identity provider (IdP), you must complete three procedures in the following order:

  1. In Entra ID, register an Entra ID application

  2. In Capella, create a realm

  3. In Entra ID, complete the configuration

Register an Entra ID Application

Start by registering an application with Entra ID. Information generated by this step is required to create a realm in Capella.

  1. From the Entra portal, open the Entra ID service.

  2. From the navigation pane, click App registrations.

  3. Click New registration.

  4. Configure options on the Register an application page:

    1. Name: Enter the display name you want for this application.

  5. Click Register.

    The Overview page of the app appears once it’s registered.

Create a Realm in Capella

With an Entra ID app registered, you need to create a realm in Capella that requires some information from Entra ID.

  1. In Capella, Navigate to the SSO page in Organization Settings:

    1. In the Capella UI, on the navigation bar, click the Settings tab.

    2. In the navigation menu, click SSO.

  2. Click Create Realm.

  3. Complete the Create Realm page:

    1. In Entra ID, on the Overview page of the app you registered, click Endpoints to open the Endpoints flyout.

    2. Copy and paste the X.509 certificate from Entra ID to Capella:

      1. In the Endpoints flyout, copy the contents of the Federation metadata document field.

      2. Paste this URL into a new browser tab to view this XML document.

      3. From the XML document, copy the certificate within the <X509Certificate>…​</X509Certificate> tag.

      4. In Capella, paste the certificate contents into the SAML Signing Certificate text box.

    3. Copy SAML - P sign-on endpoint from Entra ID to Capella.

      1. In Entra ID, with the Endpoints flyout open, copy the contents of the SAML -P sign-on endpoint field.

      2. In Capella, paste the SAML -P sign-on endpoint into the Sign-in Endpoint URL field.

    4. Verify that the remaining SAML protocol settings are as follows:

      Field Value

      Signature Algorithm

      RSA-SHA256

      Digest Algorithm

      SHA256

      SAML Protocol Binding

      HTTP-POST

    5. Choose a default team.

      Capella automatically assigns users to the chosen default team when they don’t match any team based on their SSO groups. All users assigned to the default team have its chosen permission set.

      See Manage Capella Role Mapping for information about Teams and how to configure their permissions.

    6. Choose to enable or disable group mapping.

      Capella enables group mapping by default. Group mapping allows you to assign roles to SSO users based on which teams map to their SSO group. If you disable group mapping, Capella uses the default team to give SSO users their roles when they first sign in. After SSO users sign in, you manage them like other Capella users through the People tab and each project’s Collaborators tab.

  4. Click Create Realm.

    Capella creates the new realm with an auto-generated name.

    Users need to know the realm name to sign in with SSO. You can change the a realm name after you create the realm.
Complete the Entra ID Configuration

Now that you have created the realm, you need to finish configuring Entra to include the Application ID, Redirect URI, and optional claim information.

  1. In Capella, open the information page for the realm that you created if it isn’t already.

    1. Open the Settings  SSO page.

    2. Click the listed realm to open its information page.

  2. Add the Application ID URL:

    1. In Capella, on the realm information page, copy the Entity ID field.

    2. In Entra ID, on the Overview page of the app you registered, click the Add an Application ID URI link.

    3. Click Set.

    4. In the Set the App ID URI dialog box, paste the Entity ID field you just copied from Capella.

    5. Click Save.

  3. Add the Redirect URI:

    1. In Capella, on the realm information page, copy the Callback URL field.

    2. In Entra ID, on the Overview page of the app you registered, click the Add a Redirect URI link.

    3. Click Add a platform.

    4. In the Configure platforms flyout, click the Single-page application tile.

    5. In the Configure single-page application flyout, paste Callback URL into the Redirect URIs field.

    6. Check the ID tokens (used for implicit and hybrid flows) checkbox.

    7. Click Configure.

  4. Add optional claims:

    1. In Entra ID, in the navigation, click Token configuration.

    2. Click Add groups claim.

    3. In the Edit groups claim flyout, select all the group types.

    4. Click Add.

    5. On the Optional claims page, click Add optional claim.

    6. In the Add optional claim flyout, choose the SAML option.

    7. Check the checkbox for the email claim.

    8. Click Add.

    9. In the dialog box, select the Turn on the Microsoft Graph email permission box.

    10. Click Add.

Next Steps