# Microsoft Entra ID

> Connect By Dawn to Microsoft Entra ID (formerly Azure AD) with OIDC (recommended) or SAML, so your people sign in with their Microsoft work account.

This page helps you connect By Dawn to Microsoft Entra ID, which used to be called Azure Active
Directory. At the end, people at your company sign in to By Dawn with their Microsoft work account.

You'll work in two places at once: the Microsoft Entra admin center, and
**Settings › Organization › Single sign-on** in By Dawn. [Single sign-on](https://docs.bydawn.com/sso/#add-a-connection)
explains the By Dawn side once, so this page only says which value goes where.

## Before you start

- [Verify your email domain](https://docs.bydawn.com/sso-domains/) in By Dawn.
- You need to be the organization's owner in By Dawn, and in Entra at least a Cloud Application
  Administrator, or someone who can grant admin consent.
- Check that your people have an **Email** set in Entra. By Dawn signs people in by their email, and
  Entra only sends one when the user's **Email** (`mail`) field has a value. Accounts synced from
  Active Directory usually have it, but cloud-only accounts sometimes don't. A user's sign-in name
  (UPN) isn't always their email, so By Dawn doesn't use it.

## Set up OIDC (recommended)

1. In By Dawn, under **How does your identity provider connect?**, pick **OpenID Connect (OIDC)**, name the
   connection `Entra ID` and choose **Create draft**. Keep the page open, because you'll need its **Redirect URI
   (sign-in redirect / callback URL)**.

2. In the Entra admin center, go to **Entra ID › App registrations** and choose **New
   registration**:
   - **Name**: `SAW`.
   - **Supported account types**: **Accounts in this organizational directory only (single
     tenant)**. This keeps sign-ins to your own company's accounts.
   - **Redirect URI**: pick **Web** and paste By Dawn's **Redirect URI**.

   Choose **Register**.

3. On the app's **Overview**, copy the **Application (client) ID** into By Dawn's **Client ID**.

4. For By Dawn's **Issuer URL**, use your **Directory (tenant) ID** from the same page:

   ```text
   https://login.microsoftonline.com/<Directory (tenant) ID>/v2.0
   ```

   Use the address with your own tenant ID, not `common` or `organizations`. Those accept
   accounts from any company, and the ID tokens Entra sends name your tenant as their issuer, so
   they wouldn't match the connection. Choose **Save changes**.

5. Under **Certificates & secrets**, choose **New client secret**, give it a description and an
   expiry, and choose **Add**. Copy its **Value** (not the **Secret ID**) into By Dawn's client secret box
   straight away, because Entra only shows it once, and choose **Save secret**.

6. Under **Token configuration**, choose **Add optional claim**, pick **ID**, tick `email` and
   choose **Add**. If Entra asks to turn on the Microsoft Graph email permission, agree.

7. Under **API permissions**, check that Microsoft Graph has the delegated permissions `openid`,
   `email` and `profile` (add any that are missing), then choose **Grant admin consent**. This
   stops each person being asked to consent the first time they sign in.

8. In By Dawn, choose **Test connection**, then **Activate**.

### Choose who can sign in

By default, everyone in your tenant can sign in to an app registration. To keep By Dawn to certain
people, go to **Entra ID › Enterprise apps**, open `SAW`, and under **Properties** set
**Assignment required?** to **Yes**. Then add the people or groups who may sign in under **Users
and groups**.

### Before the client secret expires

Entra client secrets expire, after at most two years. When a secret expires, sign-in through the
connection stops working, so put a reminder in your calendar. To rotate without a gap, add a new
secret in Entra, paste its value into By Dawn and choose **Replace secret**, and then delete the old one in Entra.
By Dawn shows when the secret was last updated (**Set · updated** and a date), which helps you work out when it's due.

## Set up SAML

1. In By Dawn, pick **SAML 2.0**, name the connection and choose **Create draft**. Keep the page open, because
   you'll need its **SP entity ID (audience)** and **ACS URL (single sign-on URL)**.

2. In the Entra admin center, go to **Entra ID › Enterprise apps**, choose **New application**,
   then **Create your own application**. Name it `SAW`, pick **Integrate any other application you
   don't find in the gallery (Non-gallery)**, and choose **Create**.

3. Open **Single sign-on** and pick **SAML**. Edit **Basic SAML Configuration**:

   | Entra field | Value |
   | --- | --- |
   | Identifier (Entity ID) | By Dawn's **SP entity ID**, ticked as **Default** |
   | Reply URL (Assertion Consumer Service URL) | By Dawn's **ACS URL** |
   | Sign on URL | your organization's SSO address (see [How your people sign in](https://docs.bydawn.com/sso/#how-your-people-sign-in)) |

   The **Sign on URL** makes the By Dawn tile in My Apps start the sign-in from By Dawn, which is the only
   way By Dawn accepts (see [How your people sign in](https://docs.bydawn.com/sso/#how-your-people-sign-in)). Choose
   **Save**.

4. Under **Attributes & Claims**, check the **Unique User Identifier (Name ID)**. Entra sends
   `user.userprincipalname` by default. If your people's sign-in names aren't their emails, edit it
   to `user.mail`, with the **Email address** name identifier format. Otherwise By Dawn reads the email from the
   `emailaddress` claim Entra sends as well, which is `user.mail`.

5. Under **SAML Certificates**, download the **Federation Metadata XML**. In By Dawn, paste its contents into
   **Paste your IdP's metadata XML (optional)** and choose **Fill in from metadata**, then check the fields and
   choose **Save changes**. Entra signs the assertion by default (**Sign SAML assertion**), and By Dawn requires
   that, so leave the signing option as it is.

6. Under **Users and groups**, add the people or groups who may sign in to By Dawn.

7. In By Dawn, choose **Test connection**, then **Activate**.

### When Entra's certificate changes

Entra's SAML signing certificate lasts three years by default, and Entra emails the notification
address on the app before it expires. To replace it, add a new certificate under **SAML
Certificates**. In By Dawn, choose **Add a second certificate**, paste the new one and choose **Save changes**. By Dawn
then trusts both, so nobody is turned away when you make the new certificate active in Entra. Once it is, remove
the old one in By Dawn.

## If something goes wrong

| What happens | What to check |
| --- | --- |
| Entra says `AADSTS50105`, the user isn't assigned a role | **Assignment required?** is on and the person isn't assigned. Add them under **Users and groups**. |
| Entra says `AADSTS50011`, the redirect URI doesn't match | The redirect URI (OIDC) or Reply URL (SAML) must match By Dawn's value exactly. Copy it again. |
| Entra says `AADSTS7000222`, the client secret has expired | Make a new client secret and paste its value into By Dawn. |
| By Dawn says Entra "signed you in with an email address outside this organization's verified domains" | The email Entra sent isn't at one of your verified domains, or there's no email at all. Check the person's **Email** field in Entra, or [verify that domain](https://docs.bydawn.com/sso-domains/). |
| By Dawn "couldn't accept the identity provider's response" for a SAML app | By Dawn has an old certificate. Paste the app's metadata again, or add the new certificate. |

> **Tip:** **Test connection** in By Dawn signs you in through the connection without affecting anyone else, so
> a missing or unexpected email shows up there first.

## Where to go next

- [SCIM provisioning](https://docs.bydawn.com/scim/): let Entra ID add and remove your people in By Dawn, and map Entra groups to By Dawn
  roles.

Source: https://docs.bydawn.com/sso-entra-id/