---

name: azure-osdu description: Queries OSDU users and entitlements via the OSDU Entitlements API. Use when listing OSDU users, checking roles (Viewer, Editor, Admin, Ops), resolving GUIDs to names, or troubleshooting OSDU access.

OSDU Entitlements Operations

Reference documentation for querying OSDU users and entitlements via the OSDU Entitlements API.

Prerequisites

Verify environment variables are set before any operation:

Copyecho "AI_OSDU_HOST: ${AI_OSDU_HOST:-NOT SET}"
echo "AI_OSDU_DATA_PARTITION: ${AI_OSDU_DATA_PARTITION:-NOT SET}"
echo "AI_OSDU_CLIENT: ${AI_OSDU_CLIENT:-NOT SET}"
echo "AI_OSDU_SECRET: ${AI_OSDU_SECRET:+SET}"
echo "AI_OSDU_TENANT_ID: ${AI_OSDU_TENANT_ID:-NOT SET}"

Test configuration and authentication:

Copyuv run .claude/skills/azure-osdu/scripts/osdu_manage.py check

Quick Reference

List Users and Roles

Copy# List all OSDU users with their roles
uv run .claude/skills/azure-osdu/scripts/osdu_users.py

# JSON output for processing
uv run .claude/skills/azure-osdu/scripts/osdu_users.py --json

# Filter to specific role
uv run .claude/skills/azure-osdu/scripts/osdu_users.py --role Admin

# Skip GUID resolution (faster)
uv run .claude/skills/azure-osdu/scripts/osdu_users.py --no-resolve

Manage User Roles

Copy# Add user as Viewer
uv run .claude/skills/azure-osdu/scripts/osdu_manage.py add \
  --user "user@example.com" --role Viewer

# Add user as Editor with OWNER rights
uv run .claude/skills/azure-osdu/scripts/osdu_manage.py add \
  --user "user@example.com" --role Editor --as-owner

# Remove from specific role
uv run .claude/skills/azure-osdu/scripts/osdu_manage.py remove \
  --user "user@example.com" --role Viewer

# Remove from all roles
uv run .claude/skills/azure-osdu/scripts/osdu_manage.py remove \
  --user "user@example.com" --all-roles

Owner Management

Users in OSDU groups have one of two membership types:

• OWNER: Can add/remove members from the group (management capability)
• MEMBER: Has access granted by the group (no management capability)

Copy# Change user from MEMBER to OWNER (promote)
uv run .claude/skills/azure-osdu/scripts/osdu_manage.py update \
  --user "user@example.com" --role Editor --to OWNER

# Change user from OWNER to MEMBER (demote)
uv run .claude/skills/azure-osdu/scripts/osdu_manage.py update \
  --user "user@example.com" --role Editor --to MEMBER

# Remove an OWNER (blocked by default if last owner)
uv run .claude/skills/azure-osdu/scripts/osdu_manage.py remove \
  --user "owner@example.com" --role Admin

# Force removal of last OWNER (use with caution!)
uv run .claude/skills/azure-osdu/scripts/osdu_manage.py remove \
  --user "owner@example.com" --role Admin --force

Last-Owner Protection: By default, the script prevents removing or demoting the last OWNER of a group to avoid orphaning it. Use --force to override this protection when necessary.

GUID Resolution

OSDU stores users as GUIDs. The osdu_users.py script automatically resolves GUIDs to human-readable names via Azure AD.

How It Works

1. Check cache - Session-scoped cache prevents repeated lookups
2. Try user - Look up in Azure AD users
3. Try service principal - Check Azure AD service principals (prefixed with [SP])
4. Try application - Check Azure AD applications (prefixed with [App])

Requirements

• Azure CLI authenticated: az login
• Permission to read Azure AD objects

Performance

GUID Resolution Performance:

• With --no-resolve: ~2 seconds (fast)
• With resolution: ~20-30 seconds (parallel resolution of ~150 GUIDs)

The script uses parallel GUID resolution with 10 concurrent workers to minimize lookup time.

Use --no-resolve flag when:

• Processing large user lists
• Cross-referencing with Azure AD (you already have names from tenant)
• Running in /audit workflows (names come from tenant lookup)
• Azure CLI not available
• Speed is more important than readability

Copy# Fast mode without GUID resolution
uv run .claude/skills/azure-osdu/scripts/osdu_users.py --no-resolve

# For audit workflows, always use --no-resolve with --json
uv run .claude/skills/azure-osdu/scripts/osdu_users.py --json --no-resolve

Role Groups

Output Formats

JSON Output Structure

Copy{
  "success": true,
  "host": "osdu.energy.azure.com",
  "partition": "opendes",
  "total_users": 5,
  "users": [
    {
      "email": "user@example.com",
      "display_name": "John Doe",
      "is_root": false,
      "roles": {"Viewer": "MEMBER", "Editor": "OWNER"}
    }
  ]
}

Environment Variables

Error Handling

Best Practices

1. Verify environment - Run check command before operations
2. Start with Viewer - Assign least privilege, escalate as needed
3. Use email addresses - Easier to track than GUIDs
4. Use --no-resolve for bulk - Faster for large user lists
5. Check Azure CLI auth - GUID resolution requires az login

Reference Files

• reference/entitlements.md - Full API reference
• reference/troubleshooting.md - Detailed error solutions
• scripts/osdu_users.py - User listing script
• scripts/osdu_manage.py - User management script