Designing a Secure and Granular OAuth Authorization System for AI Agents
This article explores the complexities of designing robust OAuth authorization for AI agents, which differs significantly from traditional application authorization. It proposes a three-layer model where a platform acts as an authorization broker, translating platform-native scopes to provider-specific permissions, and emphasizes granular control over resources and explicit consent for background execution to enhance security and user experience.
Read original on Dev.to #systemdesignThe Challenge of AI Agent Authorization
Traditional OAuth models, designed for apps with limited and static functionality, fall short for AI agents. AI agents are dynamic, multi-step, autonomous, and interact with numerous third-party services on behalf of users. This complexity can quickly lead to either a poor user experience with constant re-authentication or a dangerous system granting excessive permissions. The core problem shifts from simple authentication to *delegating the minimum necessary access to a dynamic system acting on behalf of users across multiple services, while maintaining understandability, revocability, and security*.
Three-Layer Authorization Model
To address the challenges, a three-layer authorization model is proposed, separating concerns and establishing clear boundaries:
- User to Platform (Identity): Focuses on user authentication to the AI agent platform, establishing user identity and associated accounts/apps. This layer is distinct from service authorization.
- User to Service through Platform (Service Connection): The user connects third-party services (e.g., GitHub, Slack) to the *platform*. The platform securely stores provider-specific OAuth tokens. At this stage, the user has only authorized the platform to *broker* access, not individual apps directly.
- User to App through Platform (App Authorization): Individual apps, agents, or integrations request platform-level permissions, not raw provider tokens. The platform determines if existing service connections and scopes suffice, guiding the user to provide missing authorizations or scope upgrades if needed. This centralizes permission management and ensures apps only receive access to specific platform capabilities.
The Pitfall of Direct Token Provision
Directly providing apps with raw provider tokens (e.g., GitHub tokens) is a common but flawed design. It leads to poor permission isolation, weak auditability, difficult revocation, vendor lock-in with provider-specific logic, and a larger blast radius in case of compromise. The platform should always act as an authorization broker, abstracting provider details from applications.
Platform-Native Scopes and Granular Controls
Effective authorization for AI agents requires defining platform-native scopes rather than exposing raw provider scopes directly. These platform scopes (e.g., `services.github.repositories.read`, `agents.jobs.background`) provide a consistent permission language, improve user experience, offer tighter product control, and simplify development by abstracting provider-specific complexities. The platform maps these native scopes to the underlying provider scopes and service states.
Beyond scopes, resource narrowing is crucial. Users often desire more granular control than broad OAuth scopes allow (e.g., specific channels, repositories, or folders). The platform can introduce product-layer restrictions to narrow effective access, even if the underlying provider scopes are broad. This builds trust by aligning authorization closer to user intent.
Enhanced User Experience and Incremental Authorization
Consent screens for AI agents must be extremely explicit, clearly stating: what app is asking, who built it, what actions it wants to perform, which connected services are involved, what permissions already exist vs. what's missing, and whether access is read-only, write-enabled, or allows background execution. This transparency enables informed user decisions.
Incremental authorization is vital. Instead of forcing users through a full re-authorization for minor changes, the system should present only the delta of new permissions required. This reduces friction and prevents users from blindly approving requests. Similarly, online access (session-based) and background access (continuous, asynchronous) should be distinct permissions, as they represent fundamentally different levels of trust and authority, requiring separate explicit consent.