wcz-layout/skills/start/steps/06-entra-setup.md

# Entra ID Setup

Execute parts A → B → C sequentially. Pause for user input at each part.

---

## Part A — Application Creation

Ask: **"Is the Entra ID application already created for this project? (yes/no)"**

- **Yes** → proceed to Part B.
- **No** → Open `https://itsr.wistron.com/homepage/apply` in the browser and perform the request with the user:

  1.  Select Service Type → Azure AD - Application Management - Add or Modify → Submit.
  2.  Select Add Application → Add Applicant.
  3.  Fill in the required application details:
      - Set the English application name from the chat context. Do not ask the user for it. If it is absent from the context, read the `name` property in `package.json`, convert it to spaced Pascal Case, and prefix it with `WCZ` (for example, `my-project` becomes `WCZ My Project`).
      - Write a concise, single-sentence reason for creating the application based on its name and purpose. Do not ask the user for this.
      - Ask the user for the expected user count and whether access is restricted to OA; do not choose either value on their behalf.
      - Set the application manager to `C1107048`, then use the form's search control to resolve and select that person.
  4.  After the user fills in the expected user count and OA access choice, they manually click Submit to add the applicant. The completed applicant appears in the page's summary table and enables the page-level final Submit. The user manually clicks that final Submit to send the request; do not activate either submission control on their behalf.

  Pause when authentication, required request details, or final submission requires user input or approval.

After the user confirms submission, **skip Parts B and C** and continue to the next step.

---

## Part B — Application Configuration

Ask: **"Have you configured the Entra ID application settings? (yes/no)"**

- **Yes** → proceed to Part C.
- **No** → Open `https://entra.microsoft.com/` in the browser and configure the application with the user. Pause when authentication, required application values, or a potentially irreversible action requires user input or approval.

  **Left navigation: App Registrations:**

  1.  Search for the application and open it.
  2.  **Authentication:** Add a 'Web' platform and configure Redirect URIs (`https://<host>/auth/callback`, plus `http://localhost:3000/auth/callback` for local development). The login flow is server-side (confidential client), so do NOT register the URIs under 'Single-page application'.
  3.  **Token Configuration:** Add groups claims → Security groups. Ensure ID, Access, and SAML token properties have checked `sAMAccountName`.
  4.  **Expose an API:** Set the Application ID URI. Add a scope named `access_as_user` (Admins and users) with appropriate display names/descriptions.
  5.  **Owners:** Add other developers as owners.
  6.  **Manifest:** Update the `api` object: `"acceptMappedClaims": true` and `"requestedAccessTokenVersion": 2`.

  **Left navigation: Enterprise Applications:**

  1.  Search for the application and open it.
  2.  **Single Sign-on:** Add custom claims for `employeeId` (Source: `user.extensionattribute5`) and `department` (Source: `user.department`). Optionally add `employeeCategory` (Source: `user.extensionattribute13`) and `companyName` (Source: `user.companyname`).
  3.  **Owners:** Add other developers as owners.

After the user confirms the configuration is complete, proceed to Part C.

---

## Part C — Credentials

Ask: **"Please provide the CLIENT_ID for your Entra ID application."**

Once received:

1. Update `.env.local` → set `ENTRA_CLIENT_ID=<CLIENT_ID>`. (If the project uses Vault, this value moves into the Vault `default` secret during the Vault Setup step.)
2. **CRITICAL**: Never ask for, print, or save the `CLIENT_SECRET`. The user enters it themselves in the Vault Setup step — into the Vault `default` secret, or directly into `.env.local` when not using Vault.