|
1 | 1 | # Validate Sufficient Scope |
| 2 | + |
| 3 | +👨💼 Some users are authenticating with no scopes which results in having a valid token, but not enough permissions to actually do anything useful with the MCP server. It would be better if we could let them know up front that they don't have enough permissions and need a new token with the appropriate scopes. |
| 4 | + |
| 5 | +To do this, you return a `403 Forbidden` response with the appropriate `WWW-Authenticate` header: |
| 6 | + |
| 7 | +```ts |
| 8 | +// A music streaming app might check scopes like this |
| 9 | +const requiredScopes = ['music:read', 'playlists:write'] |
| 10 | +const userScopes = ['music:read'] // User only has read access |
| 11 | + |
| 12 | +const hasRequiredScopes = requiredScopes.every((scope) => |
| 13 | + userScopes.includes(scope), |
| 14 | +) |
| 15 | + |
| 16 | +if (!hasRequiredScopes) { |
| 17 | + return new Response('Forbidden', { |
| 18 | + status: 403, |
| 19 | + headers: { |
| 20 | + 'WWW-Authenticate': [ |
| 21 | + `Bearer realm="MusicApp"`, |
| 22 | + `error="insufficient_scope"`, |
| 23 | + `scopes="${requiredScopes.join(' ')}"`, |
| 24 | + ].join(', '), |
| 25 | + }, |
| 26 | + }) |
| 27 | +} |
| 28 | +``` |
| 29 | + |
| 30 | +The `WWW-Authenticate` header includes: |
| 31 | + |
| 32 | +- The realm (`MusicApp`) |
| 33 | +- The error type (`insufficient_scope`) |
| 34 | +- The required scopes (`music:read playlists:write`) |
| 35 | + |
| 36 | +However, the `scopes` auth param is tricky for us because there's actually a list of valid scope combinations that are allowed. The user could have one of several scopes that would be enough to use the MCP server. There's not an established pattern for handling this case, so we'll skip the `scopes` auth param and instead include a `error_description` that explains what scope combinations are valid. |
| 37 | + |
| 38 | +```mermaid |
| 39 | +sequenceDiagram |
| 40 | + Client->>MCP_Server: Request with valid token |
| 41 | + MCP_Server->>Auth_Server: Introspect token |
| 42 | + Auth_Server-->>MCP_Server: Token info + scopes |
| 43 | + MCP_Server->>MCP_Server: Check hasSufficientScope() |
| 44 | + alt Has sufficient scope |
| 45 | + MCP_Server-->>Client: Success - MCP server access granted |
| 46 | + else Insufficient scope |
| 47 | + MCP_Server-->>Client: 403 Forbidden with scope requirements |
| 48 | + end |
| 49 | +``` |
| 50 | + |
| 51 | +<callout-muted> |
| 52 | + 📜 For more details on OAuth scope validation and error handling, see the |
| 53 | + [OAuth 2.0 Authorization Framework |
| 54 | + RFC](https://tools.ietf.org/html/rfc6749#section-3.3) and [OAuth 2.0 Bearer |
| 55 | + Token Usage RFC](https://tools.ietf.org/html/rfc6750#section-3.1). |
| 56 | +</callout-muted> |
| 57 | + |
| 58 | +🧝♀️ I created a `minimalValidScopeCombinations` array and a `hasSufficientScope` function for you to use. It's just hard to describe what you should do, but simple once you see it. Feel free to <PrevDiffLink>check out my changes</PrevDiffLink> if you want. |
| 59 | + |
| 60 | +Now, let's implement the scope validation logic to ensure only properly authorized clients can access the EpicMe MCP server! |
0 commit comments