Set up BYO Entra for a Brand

This recipe walks through configuring a Brand to authenticate end-users against the Brand's own Microsoft Entra tenant. Same shape works for Google Workspace, Okta, and Auth0 — the provider-specific bits are called out at each step.

Who runs this. Platform-superadmin creates the Brand row; the Brand-Owner registers the Entra app and pastes the credentials. The platform never holds the Brand's app secret in plaintext — values go straight into the AES-256-GCM vault.

1. Register the app in the Brand's Entra tenant

In the Brand's Azure Portal, open Entra ID → App registrations → New registration. Use:

  • Name: Aroovo — <Brand name>
  • Supported account types: Accounts in this organizational directory only (single tenant).
  • Redirect URI: Single-page application (SPA). Value: https://agents.aroovo.tech/b/<brandSlug>/auth/callback. If the Brand has a verified primaryDomain too, add that domain's callback URL as a second SPA redirect.

Note the Application (client) ID and Directory (tenant) ID from the overview page.

2. Grant API permissions

Open API permissions → Add a permission → Microsoft Graph → Delegated permissions and add:

  • openid
  • profile
  • email

Grant admin consent. No client secret is needed for the SPA flow.

3. Configure the Brand in Aroovo

As Brand-Owner, open https://agents.aroovo.tech/admin/brands/<brandSlug> and select the Auth provider tab. Pick Microsoft Entra and paste:

  • entraTenantId — the Directory (tenant) ID from step 1.
  • entraClientId — the Application (client) ID from step 1.

The equivalent over the API:

POST /api/admin/brands/<brandId>/auth-provider
{
  "provider": "entra",
  "config": {
    "tenantId": "<directory-tenant-id>",
    "clientId": "<application-client-id>"
  }
}

4. Verify with a test sign-in

Open an incognito window to https://agents.aroovo.tech/b/<brandSlug>/sign-in and sign in with a user from the Brand's Entra tenant. The flow should redirect to Microsoft, then back to /b/<brandSlug>/auth/callback, then to the Brand's admin console.

If the sign-in fails, the most common causes are:

  • Redirect URI mismatch. The redirect URI in Entra must exactly match the one Aroovo dispatches to (case sensitive).
  • Admin consent not granted. Even delegated permissions need a tenant admin to click consent before first-time users can sign in.
  • Token rejected by Aroovo. Check the platform audit log (audit API) for a signin.rejected row — the detail field names the failing claim (iss / aud / signature).

5. Invite the Brand-Owner

Once sign-in works, invite the first Brand-Owner so they can take over from the platform-superadmin:

POST /api/admin/brands/<brandId>/owner-invite
{ "email": "owner@<brand-domain>" }

The Brand-Owner's email must be in the Entra tenant; sign-ins from outside the directory will reject post-validate.

For Google / Okta / Auth0

Same step shape; the differences:

  • Google Workspace. Create an OAuth 2.0 client in Google Cloud Console; configure hostedDomain on the Aroovo side to lock sign-ins to one domain.
  • Okta. Create an OIDC SPA in the Okta admin console; paste the issuer URL (https://<okta-org>.okta.com/oauth2/default) plus the client id.
  • Auth0. Create a Single Page App in Auth0; paste the tenant URL, client id, and audience. Audience is enforced post-validate.

Full provider matrix: ADR-004 — Alternative auth providers.