Home Explore Help
Sign In
yunoadmin
/
bambuddy
mirror of https://github.com/maziggy/bambuddy
1
0
Fork 0
Files Issues 0 Wiki
Tree: 09feeb3cf7
Branches Tags
bambuddy
/
docs
/
authentication
/
entra-id.md

entra-id.md 3.8 KB
History Raw

Azure Entra ID (Azure AD) OIDC Setup

This guide shows how to configure BamBuddy's OIDC integration with Microsoft Azure Entra ID (formerly Azure Active Directory).

Prerequisites

  • An Azure account with permission to register applications in Entra ID.
  • BamBuddy ≥ 1.0 with OIDC enabled (Settings → Authentication → OIDC Providers).

1. Register an Application in Azure

  1. Open the Azure Portal and navigate to Entra ID → App registrations → New registration.
  2. Set a display name (e.g. BamBuddy).
  3. Under Supported account types, select the option that matches your organisation.

  4. Add a Redirect URI of type Web:

    https://<your-bambuddy-host>/api/v1/auth/oidc/callback

  5. Click Register.

2. Create a Client Secret

  1. In your app registration, go to Certificates & secrets → Client secrets → New client secret.
  2. Choose an expiry and click Add.
  3. Copy the secret value immediately — it is only shown once.

3. Gather the Required Values

Value Where to find it
Issuer URL Overview → Endpoints — copy the OpenID Connect metadata document URL and strip /.well-known/openid-configuration from the end. It looks like https://login.microsoftonline.com/<tenant-id>/v2.0.
Client ID Overview → Application (client) ID
Client Secret The secret value you copied above

4. Add the Provider in BamBuddy

Go to Settings → Authentication → OIDC Providers → Add Provider and fill in:

Field Value
Name Azure Entra ID (or any label you prefer)
Issuer URL https://login.microsoftonline.com/<tenant-id>/v2.0
Client ID Your Application (client) ID
Client Secret The secret you created
Scopes openid email profile
Email Claim preferred_username ← important for Entra ID
Require Email Verified Off ← Entra ID never sends email_verified
Auto-link existing accounts Keep Off unless you fully trust the IdP and have verified all existing user emails

Why preferred_username?

Azure Entra ID does not include an email_verified claim in its ID tokens. Using the standard email claim with Require Email Verified enabled would block every login. Two safe alternatives exist:

  • preferred_username (recommended) — Entra ID always populates this with the UPN (e.g. user@contoso.com). BamBuddy treats it as an email-shaped identifier and skips the email_verified check entirely.
  • email with Require Email Verified disabled — works but accepts the claim unconditionally; only appropriate when the Entra ID tenant is fully under your control.

5. (Optional) Token Lifetime

Azure Entra ID issues access tokens that expire after 1 hour by default. BamBuddy exchanges the OIDC code for its own JWT at callback time, so the Entra token lifetime does not affect the BamBuddy session length. You can adjust BamBuddy's JWT_ACCESS_TOKEN_EXPIRE_MINUTES env var independently.

6. Troubleshooting

Symptom Likely cause
Login redirects to Entra but returns "OIDC login failed" Redirect URI mismatch — check the URI registered in Azure exactly matches BamBuddy's callback URL, including scheme and trailing path.
User created but email is empty The preferred_username claim was not populated by Entra. Try the email claim with Require Email Verified off.
"Invalid client" error from Azure Client secret has expired or was copied incorrectly. Rotate the secret in Azure and update the provider in BamBuddy.
Login works but wrong user is linked auto_link_existing_accounts should remain Off until all local user emails are verified to match the Entra UPNs.