dv-security

✓ Official★ 163

by microsoft · part of microsoft/dataverse-skills

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.

🔥🔥🔥✓ VerifiedFreeQuick setup

#git #security

🧩 One of 7 skills in the microsoft/dataverse-skills package — works on its own, and pairs well with its siblings.

This is the playbook your agent receives when the skill activates — you don't need to read it to use the skill, but it's here to audit before installing.

Skill: Security — Role Assignment and Self-Elevation

This skill uses first-party CLIs — PAC CLI for role changes, Dataverse CLI to verify. Do NOT write Python scripts for role operations.

Skill boundaries

Need	Use instead
Create or modify tables, columns, relationships	dv-metadata
Manage org settings, audit, bulk delete, retention	dv-admin
Query or read records	dv-query
Write, update, or delete records	dv-data
Tenant-level governance (DLP, env lifecycle)	`pac admin --help`

Assign a Security Role to a User

pac admin assign-user --user <email-or-object-id> --role "System Administrator" --environment <url>

Arguments

Argument	Alias	Required	Description
`--user`	`-u`	Yes	User email (UPN) or Azure AD object ID
`--role`	`-r`	Yes	Security role name (e.g., `System Administrator`, `Basic User`)
`--environment`	`-env`	Yes	Target environment URL or ID
`--application-user`	`-au`	No	Treat user as an application user (service principal)
`--business-unit`	`-bu`	No	Business unit ID. Defaults to the caller's business unit

Verify the assignment — exit code 0 is not proof

pac admin assign-user exits 0 even when it fails (unresolved environment, wrong role name, unknown user). Never treat a clean exit as success.

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.
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:

# Resolve the user's systemuserid, then list their assigned roles.
# --context carries plugin/skill/agent attribution on the managed CLI call.
dataverse api request --target dataverse --method GET \
  --path "/api/data/v9.2/systemusers?%24select=systemuserid&%24filter=internalemailaddress eq 'user@contoso.com'" \
  --environment <same-url-as-assign> \
  --context "app=dataverse-skills/<ver>;skill=dv-security;agent=<agent>"
dataverse api request --target dataverse --method GET \
  --path "/api/data/v9.2/systemusers(<systemuserid>)/systemuserroles_association?%24select=name" \
  --environment <same-url-as-assign> \
  --context "app=dataverse-skills/<ver>;skill=dv-security;agent=<agent>"

If 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.

If the target role is absent, the assignment did not take — re-run, read the output, or fall back to self-elevate.

Batch Workflow: Assign Role Across Multiple Environments

Run in parallel — never sequentially:

Step 1: pac admin list                                              -> Get all environments
Step 2: Filter by type if needed (e.g., Developer, Sandbox)        -> Identify targets
Step 3: Confirm with user — show list of target environments
Step 4: Run ALL assignments in a single bash call:

pac admin assign-user --user user@contoso.com --role "System Administrator" --environment https://dev1.crm.dynamics.com &
pac admin assign-user --user user@contoso.com --role "System Administrator" --environment https://dev2.crm.dynamics.com &
pac admin assign-user --user user@contoso.com --role "System Administrator" --environment https://dev3.crm.dynamics.com &
wait

Step 5: Verify each landed (exit 0 is not proof — see above), then report ("Assigned + verified on 3/3 environments")

Important: Always confirm which environments will be affected before assigning roles, and verify each assignment landed — a clean exit code does not prove success.

Tenant Admin Self-Elevation (Fallback)

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.

If pac admin assign-user fails with "user has not been assigned any roles", use:

pac admin self-elevate --environment https://myorg.crm.dynamics.com

Requires Global Admin, Power Platform Admin, or Dynamics 365 Admin
All elevations are logged to Microsoft Purview
Uses the active auth profile if --environment is omitted

Self-elevation confirmation protocol (stricter than assign-user)

Before running pac admin self-elevate, the agent MUST:

State the risk explicitly. Include this wording (or equivalent) in the pre-run summary:

"This grants YOU System Administrator on <env>. The action is logged to Microsoft Purview with your identity and timestamp."
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.
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.
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.

Flow: Always try pac admin assign-user first. admin self-elevate is the documented fallback, gated by the protocol above.

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.)

Safety Rules

Always confirm before assigning System Administrator role
Show the list of target environments before batch operations
Self-elevation is logged and auditable — warn the user

Copy & paste — that's it

npx skills add microsoft/dataverse-skills --skill "dv-security" --full-depth

Run this in your project — your agent picks the skill up automatically.

Preview Before Running

Role 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.

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.

Examples

Assign role (user given, env missing):

❌ "Which environment should I target?"
✅ "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)."

Admin access across all environments:

❌ "Please provide your email address."
✅ "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."

Prerequisites

PAC CLI installed and authenticated (pac auth create)
System Administrator role in target environment (or Global/PP/D365 Admin for self-elevate)
Active auth profile: pac auth list
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.