querying-azure-ad

name	querying-azure-ad
description	Queries Azure AD/Entra ID users and groups using Azure CLI. Use when listing users, searching groups, checking memberships, or troubleshooting Azure AD operations.

Azure AD/Entra ID Operations

Reference documentation for querying Azure AD users and groups via Azure CLI.

Prerequisites

Verify Azure CLI authentication before any operation:

az account show --query "{name:name, user:user.name, tenantId:tenantId}" -o table

Quick Reference

User Queries

# List all users (table format)
az ad user list --query "[].{name:displayName, mail:mail, type:userType}" -o table

# Find specific user
az ad user show --id "[e-mail]" -o table

# Filter guest users
az ad user list --filter "userType eq 'Guest'" -o table

# Search by name prefix
az ad user list --filter "startswith(displayName,'John')" -o table

# Count users
az ad user list --query "length(@)"

Group Queries

# List all groups
az ad group list --query "[].{name:displayName, type:securityEnabled}" -o table

# Get group members
az ad group member list --group "GroupName" --query "[].{name:displayName, mail:mail}" -o table

# Get user's groups
az ad user get-member-groups --id "[e-mail]" -o table

# Check membership
az ad group member check --group "GROUP_ID" --member-id "USER_ID"

Group Management

# Add user to group (requires object IDs)
USER_ID=$(az ad user show --id "[e-mail]" --query "id" -o tsv)
GROUP_ID=$(az ad group show --group "GroupName" --query "id" -o tsv)
az ad group member add --group "$GROUP_ID" --member-id "$USER_ID"

OData Filter Syntax

Filter	Example
Equals	"mail eq '[e-mail]'"
Starts with	"startswith(displayName,'J')"
User type	"userType eq 'Guest'"
Enabled	"accountEnabled eq true"
Security groups	"securityEnabled eq true"

Important: OData functions are case-sensitive. Use startswith, not StartsWith.

Output Formats

Format	Flag	Use Case
Table	-o table	Human readable
JSON	-o json	Full details
TSV	-o tsv	Single values for variables

JMESPath Queries

# Select specific fields
--query "[].{name:displayName, email:mail}"

# Filter in query
--query "[?userType=='Guest']"

# Count results
--query "length(@)"

Required Permissions

Operation	Minimum Role
List users/groups	Directory Readers
Add to group	Groups Administrator
Invite guests	Guest Inviter

Error Handling

Error	Cause	Solution
Authorization_RequestDenied	Insufficient permissions	Request Directory Readers role
Request_ResourceNotFound	User/group not found	Verify spelling, use object ID
Request_BadRequest	Invalid filter	Check OData syntax, use lowercase functions

Guest User Invitation

Invite external users to your tenant using the /ag1:invite command.

Usage

# Invite a guest user
/ag1:invite [e-mail]

# Or use the script directly with options
uv run ${CLAUDE_PLUGIN_ROOT}/skills/azure-ad/scripts/invite_guest.py invite --email [e-mail]

# With custom options
uv run ${CLAUDE_PLUGIN_ROOT}/skills/azure-ad/scripts/invite_guest.py invite \
  --email [e-mail] \
  --redirect-url "https://myapp.com" \
  --message "Welcome to our organization!"

# Check authentication status
uv run ${CLAUDE_PLUGIN_ROOT}/skills/azure-ad/scripts/invite_guest.py check

Required Permissions

Operation	Permission	Role
Invite guests	User.Invite.All	Guest Inviter

Script Options

Option	Description	Default
--email	Email address to invite (required)	-
--redirect-url	URL after accepting invitation	https://myapps.microsoft.com
--send-email/--no-send-email	Send invitation email	Yes
--message	Custom message in invitation	None
--json	Output as JSON	No

Reference Files

For detailed documentation:

• reference/commands.md - Full CLI command reference
• reference/troubleshooting.md - Detailed error solutions
• scripts/invite_guest.py - Guest invitation script