Matt Glaman Examines OAuth Scope and Permission Mismatch in Drupal

Permission handling in Drupal behaves differently when evaluated through OAuth scopes, exposing a gap between the system’s internal access logic and external authentication workflows. In a blog post, Matt Glaman examines how this mismatch affects operations performed through the Simple OAuth module.

Drupal’s access system relies on handler logic such as NodeAccessControlHandler, where administrative permissions like administer nodes and bypass node access short-circuit more granular permission checks. This approach works in session-based requests because access is evaluated in a top-down sequence, allowing administrative users to bypass lower-level checks entirely.

OAuth-based requests follow a different model. The Simple OAuth module evaluates permissions directly using scope mappings and user permissions through methods such as hasPermission(). For authorization code grants, both the OAuth token and the user account must explicitly grant a permission. Because administrative permissions do not formally include the granular permissions they imply, these checks can fail even when a user would normally have access.

Glaman identifies this as a structural inconsistency: Drupal’s access system encodes relationships between permissions implicitly in handler logic rather than explicitly in the permission model. Systems that evaluate permissions independently—such as OAuth, REST, JSON:API, and GraphQL—do not inherit those implicit relationships, leading to unexpected access failures.

The post outlines a workaround using Drupal’s Access Policy system introduced in Drupal 10.3. By programmatically expanding administrative permissions to include all related granular permissions, developers can ensure that scope-based permission checks align with Drupal’s existing access control behaviour. Glaman notes that this approach compensates for a limitation that may be better addressed in Drupal core or the Entity API module.