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

# Entra ID Setup

Ask the user only through the **AskUserQuestion** pop-up, never as chat text
waiting for a typed reply, and never with a single `Continue`-style option —
that is a wait, not a question. Ask only when there is a real choice, always
with at least two concrete options; enable free text only for open-ended
values (client ID, user count), not for yes/no decisions.

To wait for something the user does in the browser — signing in, filling a
field, clicking Submit — poll in a tool loop: wait ~5 s, re-read the page,
repeat until the expected state appears or ~5 minutes pass, then carry
straight on. Never end your turn while waiting; announcing "I'll continue
once you have signed in" and stopping ends the session, and nothing resumes
it. A page that renders blank is usually still loading or still on the
sign-in gate — keep polling instead of reporting it as a problem.

---

## Part A — Application Creation

Ask via **AskUserQuestion**: **"Is the Entra ID application already created for this project?"** — options `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 via **AskUserQuestion** for the expected user count, and separately: **"Who can reach the app?"** — options `Internal network only (OA)` / `Also from the public internet`. Do not choose either value on their behalf. In the ITSR form, `Internal network only` is the OA-restricted choice.
      - Ask via **AskUserQuestion** for the application manager's employee ID, alongside the questions above, with free text enabled. Then use the form's search control to resolve and select that person.
  4.  Once every field is filled, click Submit yourself to add the applicant. The applicant appears in the page's summary table and enables the page-level final Submit.
  5.  On the summary page, ask via **AskUserQuestion**: **"Submit the ITSR request?"** — options `Submit` / `Add another application`.
      - `Add another application` → click **+ Add Applicant** above the summary table, fill the dialog exactly as in step 3, submit the dialog so the new row joins the table, then return to this question. Ask again for the new application's name, its expected user count, and its access scope — these are unique per application, so never carry them over from an existing row. Write its reason yourself.
      - `Submit` → click the page-level final Submit and confirm the portal accepted the request.

      Repeat until the user answers `Submit`. Only that answer may trigger the final Submit — the request goes to approvers.

  When the portal needs sign-in, poll until the ITSR request form is visible and continue — do not end the turn.

Once the request is submitted, close the ITSR browser session, **skip Part B**, and continue to the next step — the applications do not exist until the request is approved.

---

## Part B — Application Configuration

Ask via **AskUserQuestion**: **"Have you configured the Entra ID application settings?"** — options `Yes` / `No`.

- **Yes** → skip to **Credentials** below.
- **No** → Open `https://entra.microsoft.com/` and complete every Part B step in one uninterrupted run. Reuse this signed-in tab and the portal's own navigation; for slow controls, poll and re-read the current blade instead of reloading or opening another tab. Derive every value from the app name and the fixed values below. Do not ask for owners; the owner list is fixed. Ask only before an explicitly user-approved irreversible action.

Gradually write all the data to `.env.local` with exactly these keys — keep any values already set by earlier steps (if this file does not exist, create it). If empty - fill `SESSION_SECRET` with a freshly generated value, and leave the rest empty until you know the values:

```dotenv
ENTRA_CLIENT_ID=
ENTRA_TENANT_ID=
ENTRA_CLIENT_SECRET=
SESSION_SECRET=<generated-64-char-hex>
```

**Left navigation: App Registrations:**

1.  Use the application's display name already present in chat context. Ask via **AskUserQuestion** only if it is genuinely absent; otherwise open **App registrations**, filter by the exact name, and click the matching row. Its **Overview** page shows **Application (client) ID** and **Directory (tenant) ID** — read both and write them to `.env.local` as `ENTRA_CLIENT_ID` and `ENTRA_TENANT_ID` straight away, before configuring anything else. Never ask the user for these two values. Leave `ENTRA_CLIENT_SECRET` empty only until the client secret is created in step 3.
2.  **Authentication (Preview)** — the left-nav item is named that, and it opens on the **Redirect URI configuration** tab. Three URIs are needed, where `<app-name>` is the `name` from `package.json`:
    - `http://localhost:3000/auth/callback`
    - `https://<app-name>.wcz-sat-qas-01.k8s.wistron.com/auth/callback`
    - `https://<app-name>.wcz-sat-prd-01.k8s.wistron.com/auth/callback`

    The portal only accepts them one panel at a time:

    a. **+ Add Redirect URI** → platform picker → **Web** → **Select**. The login flow is server-side (confidential client), so never pick **Single-page application**.
    b. The panel takes a single URI. Enter the localhost one and click **Configure**. A success toast appears and the platform picker reopens — click **Cancel** to return to the list.
    c. The list now shows a **Web** group row with an **Edit** link. Click **Edit**: the panel lists the saved URIs plus one empty row, and filling a row spawns another empty row below it. Add the `qas` and `prd` URIs, then click **Configure**.
    d. Verify all three appear as Web rows in the list.

3.  **Certificates & secrets:** open the **Client secrets** tab → **+ New client secret**. Leave **Description** empty and set **Expires** to `730 days (24 months)` — always these values, never ask the user — then click **Add**. Read the new row's **Secret ID** and write it into `ENTRA_CLIENT_SECRET` in `.env.local` before navigating anywhere else. Never print the secret ID in chat or in a commit.
4.  **Token configuration:** click **Add groups claim**. In the panel tick **Security groups** only, then expand each of **ID**, **Access**, and **SAML** in "Customize token properties by type" and switch the radio from `Group ID` to `sAMAccountName`. Click **Add**. The list should then show a `groups` claim with token type `ID, Access, SAML`.
5.  **Expose an API:** next to **Application ID URI** click **Add** (or **Edit** if one exists). The portal prefills `api://<client-id>` — replace it with `api://wistron.com/<app-name>` (for `wh-fg-preparation`: `api://wistron.com/wh-fg-preparation`) and **Save**. Then **+ Add a scope** named `access_as_user`, set **Who can consent?** to `Admins and users`, and fill only the two required fields — **Admin consent display name** and **Admin consent description**. Leave the user consent fields empty (optional) and **State** on `Enabled`, then click **Add scope**. Do not navigate away or report progress as complete until the saved `api://wistron.com/<app-name>` URI and enabled `access_as_user` scope are both visible in the portal.
6.  **Owners:** first read the current table once. Add only missing people from this fixed list: Radim Staworowski, Martin Husar, Dalibor Homola, Patrik Lorenc, Tien Thanh Tran, Sebastian Ondruska. In the picker, search each missing full name, wait for the exact name and Wistron UPN match, select it, then replace the search text with the next name without closing the picker. Submit the batch once and verify all six names in the refreshed table.
7.  **Manifest:** the page opens the **Microsoft Graph App Manifest (New)** JSON in a code editor. Inside the `api` object change `"acceptMappedClaims": null` to `true` and `"requestedAccessTokenVersion": null` to `2`, then click **Save**.

**Left navigation: Enterprise Applications:**

1.  Open **Enterprise apps → All applications** and search with the exact display name already resolved in App Registrations; do not ask for it again.
2.  **Owners:** repeat the batched owner process from App Registrations. Inspect the table once, keep the picker open while searching and selecting every missing exact Wistron record, and confirm the selected-user count increments after each selection. Click **Select** once, wait for `Owner assignment succeeded`, then verify all six names in the refreshed table. The toolbar and table may load after the heading; keep polling until both appear.
3.  **Single sign-on** opens as **OIDC-based Sign-on**; there is no SAML wizard. Wait for the embedded OIDC content, then click the visible **Edit** pencil under **② Attributes & Claims**. If its reference is stale, re-read this page and click the new reference. Ignore background `400`/`403` console messages while the requested controls remain usable. Confirm the claims list already holds `groups → user.groups`, then add each missing row with **+ Add new claim**:

    | Claim Name         | Source Attribute            |
    | ------------------ | --------------------------- |
    | `department`       | `user.department`           |
    | `employeeId`       | `user.extensionattribute5`  |
    | `employeeCategory` | `user.extensionattribute13` |
    | `companyName`      | `user.companyname`          |

    For each one: type the claim name in **Name** and leave **Source** on `Attribute`. **Source attribute** is a dropdown, not a text field: click it, use its filter input when needed, and select the plain unquoted attribute option (never the quoted constant). Click **Save**, then wait for the editor to close and verify the exact name/value row in **Additional claims** before adding the next claim. During the close transition the old form may briefly mark every field invalid even though the save succeeded; the refreshed claims row or `Successfully saved SSO user claims` notification is authoritative. Leave **Claim conditions** and **Advanced SAML claims options** untouched. Finish by verifying all four rows plus the existing `groups → user.groups` row in one claims-table read.

4.  After all owners and claims are verified, close the Entra browser session and report Part B complete.