15. Authorization Scopes

Chapter 15 of 22 · 20 min

KEY INSIGHT

Authentication identifies who you are; authorization determines what you can do. Scope-based access control limits tool exposure based on verified identity. Define scopes that map to tool capabilities. Fine-grained scopes enable the principle of least privilege: ```python SCOPES = { "files:read": ["read_file", "list_directory", "search_files"], "files:write": ["write_file", "delete_file", "create_directory"], "files:admin": ["files:read", "files:write", "format_disk"], "database:query": ["execute_select", "list_tables"], "database:mutate": ["database:query", "execute_insert", "execute_update"], "admin": ["*"], # All scopes } def check_scope(token_scopes: list[str], required_tool: str) -> bool: for scope in token_scopes: allowed = SCOPES.get(scope, []) if required_tool in allowed or scope == "admin": return True return False ``` Enforce scopes at the tool level: ```python def require_scopes(*required): """Decorator to enforce authorization scopes.""" def decorator(func): @wraps(func) async def wrapper(request: Request, *args, **kwargs): token = request.state.token # Set by auth middleware if not token: raise HTTPException(401, "Authentication required") tool_name = func.__name__ if not check_scope(token.get("scopes", []), tool_name): raise HTTPException(403, f"Scope required for {tool_name}") return await func(request, *args, **kwargs) return wrapper return decorator @mcp.tool() @require_scopes("files:write") async def write_file(path: str, content: str) -> dict: # Implementation pass ``` Hierarchical scopes simplify management. A scope like `files:admin` implies `files:read` and `files:write`: ```python def expand_scopes(requested_scopes: list[str]) -> set[str]: """Expand scopes to include all implied scopes.""" expanded = set() to_process = list(requested_scopes) while to_process: scope = to_process.pop() if scope in expanded: continue expanded.add(scope) implied = SCOPES_IMPLICATIONS.get(scope, []) to_process.extend(implied) return expanded ``` Resource-level authorization adds another dimension. Beyond checking scope, verify the specific resource: ```python def check_resource_permission( user: dict, action: str, resource: str ) -> bool: # Check explicit grants if resource in user.get("allowed_resources", []): return True # Check pattern-based grants for pattern in user.get("resource_patterns", []): if re.match(pattern, resource): return True return False ```

Local verification checkpoint

Run the smallest example from this chapter in a local workspace and record the package version, runtime, data path, and observed output. If the result depends on model size, vector count, CPU/GPU backend, or available memory, note that constraint beside the exercise so the lesson remains reproducible.

EXERCISE

Design an authorization system with at least four scope levels. Implement a tool that behaves differently based on scopeΓÇöfor instance, returning summaries for limited users but full data for elevated users. Write tests verifying each scope level.