OpenID Connect: Entra app registration

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.

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:

2. Create the app registration

1. In the Microsoft Entra admin center, 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:

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 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 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 Secret expires (optional), and click Replace secret.

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