querying-adme-entitlements

name	querying-adme-entitlements
description	Queries Azure Data Manager for Energy (ADME) users and entitlements via OSDU API. Use when listing ADME users, checking roles (Viewer, Editor, Admin, Ops), resolving GUIDs to names, or troubleshooting ADME access.

ADME Entitlements Operations

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

Prerequisites

Verify environment variables are set before any operation:

echo "ADME_HOST: ${ADME_HOST:-NOT SET}"
echo "ADME_DATA_PARTITION: ${ADME_DATA_PARTITION:-NOT SET}"
echo "ADME_CLIENT: ${ADME_CLIENT:-NOT SET}"
echo "ADME_SECRET: ${ADME_SECRET:+SET}"
echo "ADME_TENANT_ID: ${ADME_TENANT_ID:-NOT SET}"

Test configuration and authentication:

uv run ${CLAUDE_PLUGIN_ROOT}/skills/azure-adme/scripts/adme_manage.py check

Quick Reference

List Users and Roles

# List all ADME users with their roles
uv run ${CLAUDE_PLUGIN_ROOT}/skills/azure-adme/scripts/adme_users.py

# JSON output for processing
uv run ${CLAUDE_PLUGIN_ROOT}/skills/azure-adme/scripts/adme_users.py --json

# Filter to specific role
uv run ${CLAUDE_PLUGIN_ROOT}/skills/azure-adme/scripts/adme_users.py --role Admin

# Skip GUID resolution (faster)
uv run ${CLAUDE_PLUGIN_ROOT}/skills/azure-adme/scripts/adme_users.py --no-resolve

Manage User Roles

# Add user as Viewer
uv run ${CLAUDE_PLUGIN_ROOT}/skills/azure-adme/scripts/adme_manage.py add \
  --user "[e-mail]" --role Viewer

# Add user as Editor with OWNER rights
uv run ${CLAUDE_PLUGIN_ROOT}/skills/azure-adme/scripts/adme_manage.py add \
  --user "[e-mail]" --role Editor --as-owner

# Remove from specific role
uv run ${CLAUDE_PLUGIN_ROOT}/skills/azure-adme/scripts/adme_manage.py remove \
  --user "[e-mail]" --role Viewer

# Remove from all roles
uv run ${CLAUDE_PLUGIN_ROOT}/skills/azure-adme/scripts/adme_manage.py remove \
  --user "[e-mail]" --all-roles

Owner Management

Users in ADME 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)

# Change user from MEMBER to OWNER (promote)
uv run ${CLAUDE_PLUGIN_ROOT}/skills/azure-adme/scripts/adme_manage.py update \
  --user "[e-mail]" --role Editor --to OWNER

# Change user from OWNER to MEMBER (demote)
uv run ${CLAUDE_PLUGIN_ROOT}/skills/azure-adme/scripts/adme_manage.py update \
  --user "[e-mail]" --role Editor --to MEMBER

# Remove an OWNER (blocked by default if last owner)
uv run ${CLAUDE_PLUGIN_ROOT}/skills/azure-adme/scripts/adme_manage.py remove \
  --user "[e-mail]" --role Admin

# Force removal of last OWNER (use with caution!)
uv run ${CLAUDE_PLUGIN_ROOT}/skills/azure-adme/scripts/adme_manage.py remove \
  --user "[e-mail]" --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

ADME stores users as GUIDs. The adme_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

Use --no-resolve flag when:

• Processing large user lists
• Azure CLI not available
• Speed is more important than readability

# Fast mode without GUID resolution
uv run ${CLAUDE_PLUGIN_ROOT}/skills/azure-adme/scripts/adme_users.py --no-resolve

Role Groups

Role	Group Pattern	Access Level
Viewer	users.datalake.viewers@{partition}.{domain}	Read-only
Editor	users.datalake.editors@{partition}.{domain}	Read-write
Admin	users.datalake.admins@{partition}.{domain}	Administrative
Ops	users.datalake.ops@{partition}.{domain}	Operations
Root	users.data.root@{partition}.{domain}	Superuser

Output Formats

Format	Flag	Use Case
Table	(default)	Human readable with colors
JSON	--json	Automation and processing

JSON Output Structure

{
  "success": true,
  "host": "adme.energy.azure.com",
  "partition": "opendes",
  "total_users": 5,
  "users": [
    {
      "email": "[e-mail]",
      "display_name": "John Doe",
      "is_root": false,
      "roles": {"Viewer": "MEMBER", "Editor": "OWNER"}
    }
  ]
}

Environment Variables

Variable	Required	Description
ADME_HOST	Yes	ADME instance hostname
ADME_DATA_PARTITION	Yes	Data partition ID
ADME_CLIENT	Yes	App registration client ID
ADME_SECRET	Yes	App registration secret
ADME_TENANT_ID	Yes	Azure AD tenant ID
ADME_DOMAIN	No	Entitlements domain (default: dataservices.energy)

Error Handling

Error	Cause	Solution
401 Unauthorized	Invalid/expired token	Check ADME_SECRET, re-authenticate
403 Forbidden	Missing API permissions	Add Entitlements API permissions in ADME
404 Not Found	Group/user not found	Verify group name format and partition ID
409 Conflict	User already in group	User is already a member (not an error)
Last owner	Removing/demoting last OWNER	Add another OWNER first, or use --force
Missing env vars	Not configured	Set required ADME_* environment variables
GUID not resolved	Azure AD issue	Check az login, try --no-resolve

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/adme_users.py - User listing script
• scripts/adme_manage.py - User management script