> ## Documentation Index
> Fetch the complete documentation index at: https://docs.mangrovesystems.com/llms.txt
> Use this file to discover all available pages before exploring further.

# SSO with Microsoft Entra ID

> Set up single sign-on so your team reaches Mangrove with their existing Microsoft Entra ID (Azure AD) work account.

Single sign-on (SSO) lets your team into Mangrove with the Microsoft work account they already have, so carbon accounting sits behind the same identity provider as the rest of your systems. Mangrove supports **Microsoft Entra ID** (formerly Azure AD), over OpenID Connect.

Your Mangrove account team sets it up. Here is how it goes.

## How setup works

<Steps>
  <Step title="You send us what we need">
    The **email domains** you want to claim, your **Microsoft Entra tenant ID**, and the two choices in the next section. The full list is below.
  </Step>

  <Step title="We claim and verify your domains">
    Mangrove verifies each domain you own. There is no DNS record for you to add and nothing to configure inside your tenant.
  </Step>

  <Step title="We configure the connection">
    Mangrove sets up the connection with the provisioning and password options you chose.
  </Step>

  <Step title="We tell you it is live">
    Nothing changes for your users until we confirm the connection is enabled. Sign-in switches over at that point.
  </Step>
</Steps>

## What to send your account team

To start, send them:

1. The **email domains** you want to claim, and confirmation that you own them. Mangrove verifies each one; there is no DNS record for you to add.
2. Your **Microsoft Entra tenant ID**. Find it in the Microsoft Entra admin centre under **Overview**, or at [Microsoft's instructions for locating your tenant ID](https://learn.microsoft.com/en-us/entra/fundamentals/how-to-find-tenant).
3. Whether new users should be **created automatically or by invitation only**. See below.
4. The **default role** for automatically created users, if you choose automatic. See [User roles](/account-admin/user-roles).
5. Whether the sign-in page should still offer a **password option**.

Mangrove does not need anything created inside your tenant. Depending on your consent settings, the first person to sign in may be prompted to consent, or an administrator may need to approve it once for the organization.

## The three decisions

### Which domains you claim

A connection covers the email domains your organization owns. A domain can be claimed by only one organization across Mangrove, so if a subsidiary or an acquired company has already claimed one you want, raise it with your account team rather than assuming it is free. Public mailbox domains such as `gmail.com` and `outlook.com` cannot be claimed.

### Whether accounts are created automatically

By default they are not. **An invitation is still required**, so on day one the only people who can sign in are those who already have access to your Mangrove account, plus anyone holding an invitation to it.

Ask your account team to turn on automatic creation and anyone in your directory who signs in gets an account, with the default role you chose. **That automatic role can never be Admin.** An invitation can still carry any role, including Admin, because a person decided to send it.

Turn it on where directory membership already means somebody should have access to your carbon data. Leave it off where it does not.

### Whether the sign-in page still offers a password

A connection can be **enforced**, which removes the "sign in with a password instead" option from the sign-in page.

## What changes for your users

The sign-in page asks for an email address first.

* **An address at a claimed domain** goes on to Microsoft and comes back signed in.
* **Any other address** gets the password field, with the address already filled in.

Signing in for the first time links a person's Microsoft identity to their existing Mangrove user. They keep their access and their history, and an unconfirmed email address is confirmed for them.

Three sign-ins are refused rather than linked, which is what your helpdesk will hear about:

| The user says                           | What happened                                                                                                   | What to do                                                                      |
| --------------------------------------- | --------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------- |
| "It says my access was removed"         | Their Mangrove access to your account was revoked. Signing in through your directory does not restore it.       | Re-invite them.                                                                 |
| "It says my account is deactivated"     | Their Mangrove user was deactivated. Signing in never reactivates it.                                           | Contact your account team.                                                      |
| "It says my identity is already linked" | They are signing in with a second Microsoft identity from a directory their Mangrove user is already linked to. | They add it from connected accounts while signed in, not from the sign-in page. |

## When somebody leaves

Revoke their access in Mangrove as part of offboarding. Mangrove does not sync with your directory, so removing them there does not remove them here.

## What Mangrove reads from your directory

Sign-in requests the `openid`, `profile` and `email` scopes only, so Mangrove sees the signed-in person's name and email address and nothing else.