Update to Microsoft Dataverse

{
  "description": "Security-role assignment, user access, application users, business units, and admin self-elevation in Dataverse environments. Use when the user wants to give someone access, grant a role, become an admin, or add a service principal.",
  "included_files": [],
  "name": "dv-security",
  "skill_md_contents": "---\r\nname: dv-security\r\ndescription: Security-role assignment, user access, application users, business units, and admin self-elevation in Dataverse environments. Use when the user wants to give someone access, grant a role, become an admin, or add a service principal.\r\n---\r\n\r\n# Skill: Security — Role Assignment and Self-Elevation\r\n\r\n**This skill uses first-party CLIs — PAC CLI for role changes, Dataverse CLI to verify.** Do NOT write Python scripts for role operations.\r\n\r\n## Preview Before Running\r\n\r\nRole grants and self-elevate are destructive (they change security posture and are logged to Purview). Before running, preview the action in plain prose — target user, role, environment(s) — using placeholders (`<ENV_URL>`, `<USER_EMAIL>`) for anything unknown, and ask for confirmation and missing values in the same turn. Skip the raw `pac admin` block; the user shouldn't have to read CLI syntax to approve a security change.\r\n\r\n**Key principle:** the user should be able to evaluate what's about to happen from your first response. A bare *\"which environment?\"* fails that test; a one-line prose preview passes it.\r\n\r\n### Examples\r\n\r\n**Assign role (user given, env missing):**\r\n- ❌ \"Which environment should I target?\"\r\n- ✅ \"I'll assign **System Administrator** to `user@contoso.com` on `<ENV_URL>`. Confirm to proceed and provide the target environment URL (or 'all' to list and batch).\"\r\n\r\n**Admin access across all environments:**\r\n- ❌ \"Please provide your email address.\"\r\n- ✅ \"I'll list your environments, then assign **System Administrator** in parallel on each one for `<YOUR_UPN>`. If `assign-user` fails on any environment, I'll fall back to self-elevate (logged to Purview) for that one. Confirm to proceed and provide your UPN.\"\r\n\r\n## Skill boundaries\r\n\r\n| Need | Use instead |\r\n|---|---|\r\n| Create or modify tables, columns, relationships | **dv-metadata** |\r\n| Manage org settings, audit, bulk delete, retention | **dv-admin** |\r\n| Query or read records | **dv-query** |\r\n| Write, update, or delete records | **dv-data** |\r\n| Tenant-level governance (DLP, env lifecycle) | `pac admin --help` |\r\n\r\n## Prerequisites\r\n\r\n- PAC CLI installed and authenticated (`pac auth create`)\r\n- System Administrator role in target environment (or Global/PP/D365 Admin for self-elevate)\r\n- Active auth profile: `pac auth list`\r\n- **Headless / restricted-egress hosts**: SDK handles role / user / business-unit ops; service principal for PAC-only ops; verify egress with `python scripts/auth.py --check`. See `dv-connect/references/headless-hosts.md`.\r\n\r\n---\r\n\r\n## Assign a Security Role to a User\r\n\r\n```bash\r\npac admin assign-user --user <email-or-object-id> --role \"System Administrator\" --environment <url>\r\n```\r\n\r\n### Arguments\r\n\r\n| Argument | Alias | Required | Description |\r\n|----------|-------|----------|-------------|\r\n| `--user` | `-u` | Yes | User email (UPN) or Azure AD object ID |\r\n| `--role` | `-r` | Yes | Security role name (e.g., `System Administrator`, `Basic User`) |\r\n| `--environment` | `-env` | Yes | Target environment URL or ID |\r\n| `--application-user` | `-au` | No | Treat user as an application user (service principal) |\r\n| `--business-unit` | `-bu` | No | Business unit ID. Defaults to the caller's business unit |\r\n\r\n---\r\n\r\n## Verify the assignment — exit code 0 is not proof\r\n\r\n`pac admin assign-user` **exits 0 even when it fails** (unresolved environment, wrong role name, unknown user). Never treat a clean exit as success.\r\n\r\n1. **Read the output, not just the exit code.** A failed run still exits 0 but prints an error (`environment ... not found`, `role ... does not exist`). Stop if the output contains an error.\r\n2. **Confirm against the exact `--environment` you used** — do not re-resolve or shorten it; a different id silently \"succeeds\" on the wrong org. Query the user's roles with a Dataverse CLI read:\r\n\r\n```bash\r\n# Resolve the user's systemuserid, then list their assigned roles.\r\n# --context carries plugin/skill/agent attribution on the managed CLI call.\r\ndataverse api request --target dataverse --method GET \\\r\n  --path \"/api/data/v9.2/systemusers?%24select=systemuserid&%24filter=internalemailaddress eq 'user@contoso.com'\" \\\r\n  --environment <same-url-as-assign> \\\r\n  --context \"app=dataverse-skills/<ver>;skill=dv-security;agent=<agent>\"\r\ndataverse api request --target dataverse --method GET \\\r\n  --path \"/api/data/v9.2/systemusers(<systemuserid>)/systemuserroles_association?%24select=name\" \\\r\n  --environment <same-url-as-assign> \\\r\n  --context \"app=dataverse-skills/<ver>;skill=dv-security;agent=<agent>\"\r\n```\r\n\r\nIf the first query returns no row, the sign-in identity may live on `domainname` (the AAD UPN) rather than `internalemailaddress` (Primary Email) — retry with `%24filter=domainname eq '<upn>'`, or `azureactivedirectoryobjectid eq '<objectid>'` when you assigned by object id. A missing row is not proof the grant failed.\r\n\r\nIf the target role is absent, the assignment did not take — re-run, read the output, or fall back to self-elevate.\r\n\r\n---\r\n\r\n## Batch Workflow: Assign Role Across Multiple Environments\r\n\r\nRun in parallel — never sequentially:\r\n\r\n```\r\nStep 1: pac admin list                                              -> Get all environments\r\nStep 2: Filter by type if needed (e.g., Developer, Sandbox)        -> Identify targets\r\nStep 3: Confirm with user — show list of target environments\r\nStep 4: Run ALL assignments in a single bash call:\r\n```\r\n\r\n```bash\r\npac admin assign-user --user user@contoso.com --role \"System Administrator\" --environment https://dev1.crm.dynamics.com &\r\npac admin assign-user --user user@contoso.com --role \"System Administrator\" --environment https://dev2.crm.dynamics.com &\r\npac admin assign-user --user user@contoso.com --role \"System Administrator\" --environment https://dev3.crm.dynamics.com &\r\nwait\r\n```\r\n\r\n```\r\nStep 5: Verify each landed (exit 0 is not proof — see above), then report (\"Assigned + verified on 3/3 environments\")\r\n```\r\n\r\n**Important**: Always confirm which environments will be affected before assigning roles, and verify each assignment landed — a clean exit code does not prove success.\r\n\r\n---\r\n\r\n## Tenant Admin Self-Elevation (Fallback)\r\n\r\n**Self-elevation is materially different from assigning a role to another user.** `pac admin assign-user <other>` grants privilege *to someone else*; `pac admin self-elevate` grants privilege *to the caller*. The risk profile and audit posture are different, so the confirmation protocol is stricter.\r\n\r\nIf `pac admin assign-user` fails with \"user has not been assigned any roles\", use:\r\n\r\n```bash\r\npac admin self-elevate --environment https://myorg.crm.dynamics.com\r\n```\r\n\r\n- Requires Global Admin, Power Platform Admin, or Dynamics 365 Admin\r\n- All elevations are logged to Microsoft Purview\r\n- Uses the active auth profile if `--environment` is omitted\r\n\r\n### Self-elevation confirmation protocol (stricter than assign-user)\r\n\r\nBefore running `pac admin self-elevate`, the agent MUST:\r\n\r\n1. **State the risk explicitly.** Include this wording (or equivalent) in the pre-run summary:\r\n   > \"This grants YOU System Administrator on `<env>`. The action is logged to Microsoft Purview with your identity and timestamp.\"\r\n2. **Capture a reason.** Ask for a one-line reason — ticket ID, incident number, or a free-form note such as `\"dev sandbox access — no ticket\"`. Echo the reason back in the pre-run summary so the user sees what will be on the record.\r\n3. **Wait for an explicit confirmation AFTER the user has seen both (1) and (2).** Do NOT accept a bare \"yes\" given before the risk statement and reason are on screen.\r\n4. **Do NOT silently fall back.** If `pac admin assign-user` fails, surface the failure first, then offer `self-elevate` with this protocol — never chain them automatically.\r\n\r\n**Flow**: Always try `pac admin assign-user` first. `admin self-elevate` is the documented fallback, gated by the protocol above.\r\n\r\n**CLI fallback**: If `pac admin self-elevate` errors out, self-elevate manually via **Power Platform Admin Center** → select the environment → **Access** → **System Administrator role**. All elevations are still logged to Purview. (In PAC CLI 2.6.4 the command fails with `bolt.authentication.http.AuthenticatedClientException` / `ApiVersionInvalid` because the CLI sends an empty `api-version=` to the backend.)\r\n\r\n---\r\n\r\n## Safety Rules\r\n\r\n- **Always confirm** before assigning System Administrator role\r\n- Show the list of target environments before batch operations\r\n- Self-elevation is logged and auditable — warn the user\r\n"
}