# OpenID Connect: Entra app registration

> Connect Microsoft Entra ID to Botyard over OpenID Connect with an app registration: redirect URI, tenant and client IDs, a client secret, and secret rotation.

Canonical URL: https://docs.botyard.io/docs/sso/entra-oidc

This guide connects Entra ID to a Botyard organization over OpenID Connect, using an Entra app
registration and a client secret. You need to be a Botyard organization owner and able to create
app registrations in your Entra tenant.

> [!NOTE]
> **Availability**
>
> Botyard must enable SSO for your organization, and your plan must include single sign-on (Pro,
> Enterprise, or a legacy Business or Early Bird plan). See [Availability](/docs/sso#availability).

## 1. Open Botyard's OpenID Connect values

1. In Botyard, open **User menu** › **Settings** › **General** › **Single sign-on**.
2. On the **Identity provider** card, under **Protocol**, select **OpenID Connect (App
   registration)**.
3. Section **1. Give Entra these values** lists:

| Botyard label    | What it is                                                                   | Path in the value                            |
| ---------------- | ---------------------------------------------------------------------------- | -------------------------------------------- |
| **Redirect URI** | Where Entra returns the user after sign-in                                   | `…/sso/callback`                             |
| **Sign on URL**  | Starts this organization's sign-in from the Botyard login page, when enabled | `…/login?method=sso&org=<organization slug>` |

## 2. Create the app registration

1. In the [Microsoft Entra admin center](https://entra.microsoft.com), go to **App registrations**
   → **New registration**.
2. Name it (for example "Botyard").
3. Under **Supported account types**, choose **Accounts in this organizational directory only**
   (single tenant).
4. Under **Redirect URI**, choose platform **Web** and paste Botyard's **Redirect URI**.
5. Register the app.

If you already registered the app, add the redirect URI under **Authentication** → **Add a
platform** → **Web**.

From the app's **Overview** page, note the **Directory (tenant) ID** and the **Application
(client) ID**.

Botyard requests the `openid`, `email` and `profile` scopes and uses the authorization code flow
with PKCE. It reads the user's tenant (`tid`) and object ID (`oid`) from the ID token. You don't
need to configure optional claims or API permissions beyond Entra's defaults.

## 3. Create a client secret

1. In the app registration, open **Certificates & secrets** → **Client secrets** → **New client
   secret**.
2. Choose an expiry and create it.
3. Copy the secret's **Value**. Entra shows it only once. You need the **Value**, not the
   **Secret ID**.

Botyard authenticates with a client secret only. Certificate credentials are not supported.

## 4. Paste Entra's values into Botyard

Under **2. Paste Entra's values here**, fill in:

| Botyard field                 | Entra value                                         |
| ----------------------------- | --------------------------------------------------- |
| **Directory (tenant) ID**     | **Directory (tenant) ID** from the app's Overview   |
| **Application (client) ID**   | **Application (client) ID** from the app's Overview |
| **Client secret value**       | The secret's **Value**                              |
| **Secret expires (optional)** | The expiry date you chose                           |

Click **Connect Entra ID**.

The client secret is stored encrypted and is never shown again, to anyone. If you enter its expiry
date, Botyard warns on the connection card from 30 days before it lapses. After it has expired,
sign-in through Entra fails until you replace it.

The tenant ID must be your organization's own directory: a GUID. Microsoft's tenants for personal
Microsoft accounts are refused, because a connection pinned to one would trust every personal
Microsoft account.

## 5. Assign users

In Entra, open **Enterprise applications**, find the application with the same name, and assign
the people or groups who should be able to sign in under **Users and groups**. To make assignment
required, set &#x2A;*Assignment required?** to **Yes** under **Properties**.

## 6. Start sign-in

Members can open the **Sign on URL** to start sign-in for this organization automatically. Alternatively, on the
Botyard login page, select **Sign in with SSO**, enter the organization's slug in
**Organization ID**, and select **Continue with SSO**. The slug is the ID in the organization's
Botyard address, for example `acme` in `/orgs/acme`; it is not an email address.

The same login entry supports SAML and OpenID Connect. See
[Existing Botyard accounts](/docs/sso#how-members-are-identified) before testing with an account
that already exists in Botyard.

## Replace the client secret

Before the secret expires:

1. In Entra, create a new client secret under **Certificates & secrets** and copy its **Value**.
2. In Botyard, on the **Identity provider** card, click **Replace client secret**.
3. Paste it into **New client secret value**, optionally set &#x2A;*Secret expires (optional)**, and
   click **Replace secret**.

Sign-ins use the new secret immediately. Delete the old secret in Entra afterwards.