Scope & Claim Best Practices

Best Practices for Scope and Claim Usage¶

Scopes and claims are foundational to defining access boundaries in OAuth2 and OpenID Connect (OIDC) systems. Misconfigurations or over-privileged requests can lead to privilege escalation, data breaches, or compliance violations. This section outlines strategies to enforce least-privilege principles and ensure secure usage of scopes and claims.

1. Scope Minimization and Granular Scope Design¶

Always request the minimum required scopes for a given operation. Avoid broad, catch-all scopes like openid or email unless absolutely necessary. Instead, use granular scopes that align with specific permissions (e.g., read:users, write:orders).

Example: Scope Request with Granularity¶

GET /api/data HTTP/1.1
Host: example.com
Authorization: Bearer <token>

Ensure the token contains only the scopes required for the request (e.g., read:reports instead of openid).

Diagram: Scope Minimization¶

[Client] --> [Request Scopes: read:reports] --> [Authorization Server] --> [Issue Token with Scopes] --> [Service]

Command: Validate Scope Usage¶

# Use an OIDC introspection endpoint to check token scopes
curl -k https://auth.example.com/introspect \
  -H "Authorization: Bearer <token>" \
  -d "token=<token>"

2. Claim Selection and Validation¶

Claims (e.g., email, roles, groups) should be explicitly validated against business rules or policies. Avoid relying on untrusted claims and ensure they are scoped to specific contexts (e.g., roles for access control, email for user identification).

Example: Claim Validation in a Service¶

from oidcmsg.oauth2 import UserInfo

def validate_user_role(token, required_role):
    user_info = UserInfo(token).get("roles")
    if required_role in user_info:
        return True
    raise PermissionError("Insufficient privileges")

Diagram: Claim-Based Access Control¶

[User] --> [Request Token with roles: admin] --> [Service] --> [Check roles: admin] --> [Grant Access]

3. Scope Composition and Hierarchical Scopes¶

Use hierarchical scopes to model complex access hierarchies (e.g., read:users vs. read:users:profile). This allows fine-grained control and reduces the risk of over-privileged access.

Example: Hierarchical Scope Usage¶

GET /api/users/profile HTTP/1.1
Host: example.com
Authorization: Bearer <token>

Ensure the token includes read:users:profile instead of a generic read:users.

4. Dynamic Scope Delegation and Time-Bound Scopes¶

Limit scope lifetimes and use dynamic scope delegation (e.g., via OAuth2's scope parameter in refresh tokens) to ensure privileges are temporary. Avoid long-lived tokens with broad scopes.

Command: Issue Time-Bound Token¶

# Use a short-lived access token and refresh token with restricted scope
curl -k https://auth.example.com/token \
  -d "grant_type=client_credentials" \
  -d "scope=read:reports" \
  -d "expires_in=3600"

5. Regular Audits and Monitoring¶

Audit scope and claim usage to detect anomalies (e.g., unexpected scopes, missing claims). Integrate with SIEM tools to monitor access patterns and enforce compliance.

Example: Audit Log Query¶

SELECT * FROM access_logs 
WHERE scope LIKE '%write:users%' 
AND timestamp > NOW() - INTERVAL '7 days';

Key takeaways¶

Minimize scopes to adhere to least-privilege principles.
Validate claims against explicit policies to prevent misuse.
Use hierarchical scopes for granular access control.
Limit token lifetimes and avoid long-lived tokens with broad scopes.
Audit and monitor scope and claim usage regularly for compliance.