# SAML authentication with Microsoft Entra ID

With SAML (Security Assertion Markup Language) enabled, you can authenticate
users in Cube through Microsoft Entra ID (formerly Azure Active Directory),
allowing your team to access Cube using single sign-on.

<InfoBox>

Available on [Enterprise and above plans](https://cube.dev/pricing).

</InfoBox>

## Prerequisites

Before proceeding, ensure you have the following:

- Admin permissions in Cube.
- Sufficient permissions in Microsoft Entra to create and configure
  Enterprise Applications.

## Enable SAML in Cube

First, enable SAML authentication in Cube:

1. In Cube, navigate to <Btn>Admin → Settings</Btn>.
2. On the <Btn>Authentication & SSO</Btn> tab, enable the <Btn>SAML</Btn>
   toggle.
3. Take note of the <Btn>Single Sign-On URL</Btn> and <Btn>Audience</Btn>
   values — you'll need them when configuring the Enterprise Application
   in Entra.

## Create an Enterprise Application in Entra

1. Sign in to the [Microsoft Entra admin center](https://entra.microsoft.com).
2. Go to [Enterprise Applications](https://portal.azure.com/#view/Microsoft_AAD_IAM/StartboardApplicationsMenuBlade/~/AppAppsPreview)
   and click <Btn>New application</Btn>.
3. Select <Btn>Create your own application</Btn>.
4. Give it a name and choose a **non-gallery application**, then click
   <Btn>Create</Btn>.

## Configure SAML in Entra

1. In your new Enterprise Application, go to the <Btn>Single sign-on</Btn>
   section and select <Btn>SAML</Btn>.
2. In the <Btn>Basic SAML Configuration</Btn> section, enter the following:
   - **Entity ID** — Use the <Btn>Single Sign-On URL</Btn> value from Cube.
   - **Reply URL** — Use the <Btn>Single Sign-On URL</Btn> value from Cube.
3. Go to <Btn>Attributes & Claims → Edit → Advanced settings</Btn> and
   set the audience claim override to the <Btn>Audience</Btn> value from Cube.
4. Go to <Btn>SAML Certificates → Edit</Btn> and select <Btn>Sign SAML
   response and assertion</Btn> for the <Btn>Signing Option</Btn>.
5. Download the <Btn>Federation Metadata XML</Btn> file — you'll need it
   in the next step.

## Complete configuration in Cube

Return to the SAML configuration page in Cube and provide the identity
provider details. You can do this in one of two ways:

**Option A: Upload metadata file**

1. In the <Btn>Import IdP Metadata</Btn> section, click <Btn>Upload
   Metadata File</Btn>.
2. Select the **Federation Metadata XML** file you downloaded from Entra.
   This will automatically populate the <Btn>Entity ID / Issuer</Btn>,
   <Btn>SSO (Sign on) URL</Btn>, and <Btn>Certificate</Btn> fields.

**Option B: Enter details manually**

If you prefer to configure the fields manually, enter the following
values from the Entra <Btn>Single sign-on</Btn> page:

- **Entity ID / Issuer** — Use the <Btn>Microsoft Entra Identifier</Btn>
  value.
- **SSO (Sign on) URL** — Use the <Btn>Login URL</Btn> value.
- **Certificate** — Paste the Base64-encoded certificate from the
  <Btn>SAML Certificates</Btn> section.

## Configure attribute mappings

To map user attributes from Entra to Cube, configure the claim URIs
in the SAML settings:

- Enter the claim URI that corresponds to the user's email address in
  the <Btn>Email</Btn> attribute field. Common values:
  - `http://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddress`
  - `http://schemas.xmlsoap.org/ws/2005/05/identity/claims/name`
- To map a role attribute from Entra to an identically-named role
  defined in Cube, add the corresponding claim URI to the
  <Btn>Role</Btn> field.
- You can also map the user's display name in the same manner.

<InfoBox>

Admin status cannot be set via SSO. To grant admin permissions, update
the user's role manually in Cube under <Btn>Team & Security</Btn>.

</InfoBox>

## Assign users

Make sure the new Enterprise Application is assigned to the relevant
users or groups in Entra before testing.

## Test the integration

1. In the Entra <Btn>Single sign-on</Btn> section, click <Btn>Test</Btn>
   to verify the SAML integration works for your Cube account.
2. Alternatively, copy the <Btn>Single Sign-On URL</Btn> from Cube,
   open it in a new browser tab, and verify you are redirected to
   Entra for authentication and then back to Cube.

[ext-ms-entra-id]: https://www.microsoft.com/en-us/security/business/identity-access/microsoft-entra-id
