Entra ID Module¶

Section: Modules | Article 33
Audience: System Administrators
Last Updated: 2026-04-07

Overview¶

The Entra ID module connects RP-PAM to your Microsoft Entra ID (formerly Azure Active Directory) tenant via the Microsoft Graph API. It enables RP-PAM to:

Discover and import users and groups from Entra ID
Manage group memberships for just-in-time access provisioning
Read audit and sign-in logs for anomaly detection
Synchronise user attributes for risk scoring

Prerequisites¶

Requirement	Detail
App registration created	Entra ID app registration with required permissions, per Article 21
Admin consent granted	All API permissions have admin consent (green checkmarks in Azure portal)
Client secret or certificate	Stored in RP-PAM vault via `rppam-migrate setup-entraid`
Network access	RP-PAM server can reach `graph.microsoft.com` and `login.microsoftonline.com` on port 443

Module Configuration¶

Add or update the Entra ID module configuration in rppam.config.

Windows path: C:\ProgramData\Ravenphyre\RP-PAM\rppam.config
Linux path: /etc/rppam/rppam.config

{
  "modules": {
    "entraId": {
      "enabled": true,
      "tenantId": "YOUR_TENANT_ID",
      "clientId": "YOUR_CLIENT_ID",
      "authMode": "clientSecret",
      "clientSecretVaultKey": "entraid-client-secret",
      "graphBaseUrl": "https://graph.microsoft.com/v1.0",
      "syncIntervalMinutes": 15,
      "userFilter": "accountEnabled eq true",
      "groupFilter": "startswith(displayName, 'sg-pam')",
      "managedGroups": [
        "sg-pam-admins",
        "sg-pam-helpdesk",
        "sg-database-access",
        "sg-vpn-users"
      ],
      "excludeGroups": [
        "Global Administrators",
        "Privileged Role Administrators"
      ],
      "syncAttributes": [
        "displayName",
        "userPrincipalName",
        "mail",
        "department",
        "jobTitle",
        "manager"
      ],
      "connectionTimeoutSeconds": 30,
      "maxRetries": 3,
      "retryDelaySeconds": 5
    }
  }
}

Configuration Field Reference¶

Field	Description	Required	Default
`enabled`	Enable the Entra ID module	Yes	`false`
`tenantId`	Azure AD tenant ID (GUID)	Yes	--
`clientId`	App registration client ID (GUID)	Yes	--
`authMode`	`"clientSecret"` or `"certificate"`	No	`"clientSecret"`
`clientSecretVaultKey`	Vault key for the encrypted client secret	Required if `authMode` is `"clientSecret"`	--
`certificatePath`	Path to PFX certificate file	Required if `authMode` is `"certificate"`	--
`certificatePasswordVaultKey`	Vault key for the certificate password	Required if `authMode` is `"certificate"`	--
`graphBaseUrl`	Microsoft Graph API base URL	No	`https://graph.microsoft.com/v1.0`
`syncIntervalMinutes`	How often to sync users and groups	No	`15`
`userFilter`	OData filter for user discovery	No	Active accounts only
`groupFilter`	OData filter for group discovery	No	All groups
`managedGroups`	Group display names that RP-PAM can modify	Yes	--
`excludeGroups`	Groups that RP-PAM must never modify	No	Built-in admin roles
`syncAttributes`	User attributes to import from Entra ID	No	Standard set
`connectionTimeoutSeconds`	HTTP request timeout	No	`30`
`maxRetries`	Number of retries on transient failures	No	`3`
`retryDelaySeconds`	Delay between retries	No	`5`

Government and Sovereign Cloud Endpoints¶

If your tenant is in a sovereign cloud, change graphBaseUrl:

Cloud	`graphBaseUrl`
Commercial (default)	`https://graph.microsoft.com/v1.0`
US Government (GCC High)	`https://graph.microsoft.us/v1.0`
China (21Vianet)	`https://microsoftgraph.chinacloudapi.cn/v1.0`

Enable the Module¶

Using the Web Portal¶

Log in as pam_admin.
Navigate to Modules > Entra ID.
Fill in the tenant ID, client ID, and other settings.
Click Test Connection to verify connectivity to Microsoft Graph.
Click Enable.

Using the API¶

Linux:

curl -s -X PUT http://localhost:7101/api/v1/modules/entraId/config \
  -H "Authorization: Bearer $ADMIN_JWT" \
  -H "Content-Type: application/json" \
  -d '{
    "enabled": true,
    "tenantId": "YOUR_TENANT_ID",
    "clientId": "YOUR_CLIENT_ID",
    "clientSecretVaultKey": "entraid-client-secret",
    "managedGroups": ["sg-pam-admins", "sg-vpn-users"]
  }' | jq .

PowerShell:

$config = @{
    enabled              = $true
    tenantId             = "YOUR_TENANT_ID"
    clientId             = "YOUR_CLIENT_ID"
    clientSecretVaultKey = "entraid-client-secret"
    managedGroups        = @("sg-pam-admins", "sg-vpn-users")
} | ConvertTo-Json

Invoke-RestMethod -Uri "http://localhost:7101/api/v1/modules/entraId/config" `
  -Method Put `
  -Headers @{ Authorization = "Bearer $adminJwt" } `
  -ContentType "application/json" `
  -Body $config

Restart and Verify¶

After saving the configuration, restart RP-PAM.

Windows PowerShell:

Restart-Service RpPam

Linux:

sudo systemctl restart rppam

Check Module Status¶

Linux:

curl -s http://localhost:7101/api/v1/modules \
  -H "Authorization: Bearer $ADMIN_JWT" | jq '.items[] | select(.moduleName == "entraId")'

PowerShell:

$modules = Invoke-RestMethod -Uri "http://localhost:7101/api/v1/modules" `
  -Headers @{ Authorization = "Bearer $adminJwt" }
$modules.items | Where-Object { $_.moduleName -eq "entraId" } | ConvertTo-Json

Expected:

{
  "moduleName": "entraId",
  "status": "healthy",
  "tenantId": "YOUR_TENANT_ID",
  "lastSync": "2026-04-07T10:00:00Z",
  "usersDiscovered": 150,
  "groupsManaged": 4,
  "graphApiReachable": true
}

Verify User Lookup¶

Linux:

curl -s "http://localhost:7101/api/v1/users?source=entraId&limit=5" \
  -H "Authorization: Bearer $ADMIN_JWT" | jq '.items[] | {displayName, userPrincipalName}'

PowerShell:

$users = Invoke-RestMethod -Uri "http://localhost:7101/api/v1/users?source=entraId&limit=5" `
  -Headers @{ Authorization = "Bearer $adminJwt" }
$users.items | Select-Object displayName, userPrincipalName | Format-Table

Verify Group Management¶

Linux:

curl -s "http://localhost:7101/api/v1/resources?source=entraId&type=group&limit=5" \
  -H "Authorization: Bearer $ADMIN_JWT" | jq '.items[] | {displayName, memberCount}'

PowerShell:

$groups = Invoke-RestMethod -Uri "http://localhost:7101/api/v1/resources?source=entraId&type=group&limit=5" `
  -Headers @{ Authorization = "Bearer $adminJwt" }
$groups.items | Select-Object displayName, memberCount | Format-Table

Common Graph API Errors¶

The Microsoft Graph API returns structured error responses. Here are the most common errors and their solutions.

Error Code	Error Message	Cause	Solution
`Authorization_RequestDenied`	Insufficient privileges to complete the operation	Missing API permission or admin consent not granted	Add the required permission in Azure portal and grant admin consent
`Request_ResourceNotFound`	Resource does not exist	Group or user ID is invalid	Verify the resource exists in Entra ID; check for typos in `managedGroups`
`Authentication_MissingOrMalformed`	Access token is missing or malformed	Client secret expired or invalid	Rotate the client secret (see Article 21)
`InvalidAuthenticationToken`	CompactToken parsing failed	Token request failed; usually wrong tenant ID or client ID	Verify `tenantId` and `clientId` in configuration
`ServiceNotApplicable`	Service is not applicable for this tenant	Feature not available in your Entra ID tier	Check if the API requires Entra ID P1 or P2
`ThrottledRequest`	Too many requests	Graph API rate limit exceeded	RP-PAM handles this automatically with retries; increase `retryDelaySeconds` if persistent
`Directory_ResultSizeLimitExceeded`	Result size limit exceeded	Query returned too many results	Add a more specific `groupFilter` or `userFilter` to reduce result size
`BadRequest`	Invalid filter clause	Malformed OData `$filter` in `userFilter` or `groupFilter`	Verify OData filter syntax; test the filter in Graph Explorer

Testing with Microsoft Graph Explorer¶

Before troubleshooting in RP-PAM, you can test Graph API calls directly:

Open Graph Explorer.
Sign in with your admin account.
Test the same queries RP-PAM would make:

GET https://graph.microsoft.com/v1.0/users?$filter=accountEnabled eq true&$top=5
GET https://graph.microsoft.com/v1.0/groups?$filter=startswith(displayName, 'sg-pam')
GET https://graph.microsoft.com/v1.0/groups/{group-id}/members

Hybrid AD + Entra ID Environments¶

If your organisation uses both on-premises AD and Entra ID (with Azure AD Connect sync), you can enable both the AD module and the Entra ID module simultaneously.

How RP-PAM Handles Duplicates¶

RP-PAM uses the userPrincipalName to match users across sources. If a user exists in both AD and Entra ID:

The user appears once in the RP-PAM user list.
The source field shows "hybrid".
Group memberships from both sources are visible.
Access provisioning routes to the correct source automatically (AD groups via LDAP, Entra ID groups via Graph API).

Configuration for Hybrid¶

Simply enable both modules in rppam.config:

{
  "modules": {
    "activeDirectory": {
      "enabled": true,
      "domain": "corp.local"
    },
    "entraId": {
      "enabled": true,
      "tenantId": "YOUR_TENANT_ID"
    }
  }
}

Troubleshooting¶

Problem	Cause	Solution
`"status": "unhealthy"`	Cannot authenticate to Graph API	Check client secret/certificate validity; verify tenant/client IDs
No users discovered	`userFilter` too restrictive	Simplify or remove the filter; test in Graph Explorer first
Groups visible but cannot modify members	Missing `Group.ReadWrite.All` permission	Add the permission in Azure portal and grant admin consent
`"Client secret expired"` warning	Secret approaching or past expiration date	Rotate the secret (see Article 21, Secret Rotation)
Sync runs but misses some users	Paginated results not fully consumed	Increase `connectionTimeoutSeconds`; check for transient Graph API errors in logs
`"Cannot reach graph.microsoft.com"`	Firewall or proxy blocking outbound HTTPS	Open port 443 to `graph.microsoft.com` and `login.microsoftonline.com`; configure proxy if needed
Duplicate users after enabling hybrid	UPN mismatch between AD and Entra ID	Ensure Azure AD Connect syncs the same UPN to both directories

Next Steps¶

Service Account Setup (Entra ID) -- Review app registration and permissions
Active Directory Module -- Configure the on-premises AD module
Configuration Reference -- Full module configuration options