# Research: 063 — Entra Sign-in

## 1. Required OAuth Scopes for Entra ID Sign-in

**Decision**: Use the standard OpenID Connect scopes: `openid`, `email`, `profile`.

**Rationale**:
- `openid`: Required for OIDC compliance, returns the `sub` (subject) claim which can be used for the user identifier.
- `email`: Requests the `email` claim.
- `profile`: Requests claims like `name`, `family_name`, `given_name`.
The `tid` and `oid` claims are standard in Microsoft's implementation and do not require special scopes.

**Alternatives considered**:
- Requesting more specific scopes (e.g., `User.Read` from Microsoft Graph). This is not necessary for basic sign-in and would require the Graph API, which is out of scope for the login flow itself.

## 2. User Provisioning Strategy

**Decision**: Just-In-Time (JIT) provisioning using `updateOrCreate`.

**Rationale**:
- The `spec.md` requires upserting the user based on `(entra_tenant_id, entra_object_id)`.
- Laravel's `updateOrCreate` is the idiomatic way to handle this. It will find a user with the matching `entra_tenant_id` and `entra_object_id` or create a new one if none exists.
- The `User` model will be updated with information from the Entra ID claims (name, email).

**Alternatives considered**:
- Pre-provisioning users. This would require an admin to manually create users before they can sign in, which is not a good user experience.

## 3. Interaction with Tenant RBAC

**Decision**: The sign-in flow will only *read* tenant memberships after the user is authenticated.

**Rationale**:
- The `spec.md` is clear: "063 MUST NOT refactor tenant RBAC data model or enforcement. It may only **read** memberships to decide where to redirect after login."
- After the user is upserted and logged in, a service class will be used to check their tenant memberships (e.g., `Auth::user()->tenants()->count()`).
- The result of this check (0, 1, or N) will determine the redirect path as per the spec.

**Alternatives considered**:
- Modifying RBAC during login. This is explicitly out of scope.

## 4. User Experience for Unmapped/New Users

**Decision**: The user experience is defined by the post-login routing based on tenant memberships.

**Rationale**:
- If a new user signs in via Entra, they will be created in the `users` table.
- At this point, they will have 0 tenant memberships.
- According to the spec (`FR-003`), they will be redirected to `/admin/no-access`.
- This page will instruct them to "Ask an admin to add you." This is the desired flow.

**Alternatives considered**:
- Displaying an error on the login page. This is less user-friendly than guiding them to a page that explains the next steps.