Implement OAuth2 Specs

[jay-elizaga-dev]

Generalizing Session Tokens to Follow OAuth 2.0 Specifications

Overview

This guide explains how to align session token implementations with OAuth 2.0 standards (RFC 6749) to create interoperable, secure authentication for native MCP clients and third-party integrations.

The Problem: Non-Standard Session Tokens

Current Implementation (Nexlayer):

• next-auth.session-token cookie interception via WKWebView
• Custom sessionToken/sessionId/userIP parameters injected into MCP tool calls
• Fragile dependency on NextAuth internals
• Not portable across OAuth providers

OAuth 2.0 Standard:

• Access tokens are credentials used to access protected resources represented as a string denoting a specific scope, lifetime, and other access attributes
• Clear separation between authorization (grants) and token usage (Bearer tokens)
• Provider-agnostic token exchange mechanisms

---

OAuth 2.0 Architecture for Session Tokens

Core Components

1. Authorization Server Role

The authorization server issues access tokens to the client after successfully authenticating the resource owner and obtaining authorization.

For session-like scenarios, this means:

• User authentication via login form or passkey
• Scope negotiation (what MCP tools can the client access?)
• Token issuance with expiration and metadata

2. Access Token vs. Session Token

Aspect	OAuth Access Token	Session Token (Current)
Format	Opaque string, JWT, or other	Cookie or custom header
Scope	Explicit permissions	Implicit/undefined
Expiration	Short-lived (minutes to hours)	Long-lived (cookie-based)
Revocation	Explicit via token endpoint	Cookie deletion/server-side
Standard Validation	Bearer token format (RFC 6750)	Custom per-provider

Recommendation: Replace sessionToken with OAuth 2.0 access tokens that encode session context.

---

Proposed Token Structure

Option A: Opaque Access Token with Server-Side Lookup

Token format: random 32+ byte string (base64url encoded)
Server-side store: { token: { user_id, scopes, ip, issued_at, expires_at } }

Pros:

• Simple, flexible
• Can change backend data without invalidating tokens
• Smaller token size

Cons:

• Requires token introspection endpoint (RFC 7662)
• Additional database lookup per request

Option B: JWT-Based Access Token

Token format: JWT with claims
{
  "sub": "user-uuid",
  "iss": "https://nexlayer.com",
  "aud": "mcp-client",
  "scope": "read:credits write:coupon read:referral",
  "iat": 1704067200,
  "exp": 1704070800,
  "user_ip": "192.168.1.1"
}

Pros:

• Self-contained, no server lookup needed
• Signature proves authenticity
• Standard via RFC 9068 (JWT Profile for Access Tokens)

Cons:

• Larger token size
• Revocation harder (need token blacklist)
• Can't change claims without issuing new token

Recommendation for MCP: JWT access tokens with short expiration (15–60 min) + optional refresh tokens for long-lived sessions.

---

Implementation: Authorization Code + PKCE Flow

1. Register Native App Client

Request to Nexlayer OAuth Server:

{
  "client_name": "mac-native-mcp",
  "client_type": "public",
  "redirect_uris": ["nexlayer-mac-native://oauth/callback"],
  "response_types": ["code"],
  "grant_types": ["authorization_code", "refresh_token"],
  "token_endpoint_auth_method": "none"
}

Response:

{
  "client_id": "mac-native-mcp-xyz",
  "client_secret": null,
  "redirect_uris": ["nexlayer-mac-native://oauth/callback"],
  "token_endpoint_auth_method": "none"
}

---

2. Authorization Request with PKCE

PKCE works by the app first generating a new secret each time it starts the Authorization Code flow, and it sends a hash of the secret in the initial authorization request.

Step 1: Generate PKCE Challenge

let codeVerifier = generateRandomString(length: 128) // RFC 7636
let codeChallenge = base64url(sha256(codeVerifier))
let state = generateRandomString(length: 32) // CSRF protection

Step 2: Redirect to Authorization Endpoint

https://nexlayer.com/oauth/authorize?
  client_id=mac-native-mcp-xyz&
  response_type=code&
  scope=read:credits%20write:coupon%20read:referral&
  redirect_uri=nexlayer-mac-native://oauth/callback&
  code_challenge=E9Mrozoa...&
  code_challenge_method=S256&
  state=xyz789&
  prompt=login

Step 3: User Authenticates

• System browser opens (via ASWebAuthenticationSession)
• User logs in with email/passkey
• Nexlayer validates credentials

Step 4: Authorization Redirect

nexlayer-mac-native://oauth/callback?
  code=auth-code-xyz&
  state=xyz789

---

3. Token Exchange

Step 5: Back-Channel Token Request

POST https://nexlayer.com/oauth/token
Content-Type: application/x-www-form-urlencoded

code=auth-code-xyz&
client_id=mac-native-mcp-xyz&
code_verifier=jkajsd...&
redirect_uri=nexlayer-mac-native://oauth/callback&
grant_type=authorization_code

Step 6: Token Response

{
  "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "token_type": "Bearer",
  "expires_in": 3600,
  "refresh_token": "refresh-token-xyz",
  "scope": "read:credits write:coupon read:referral"
}

Step 7: Store Tokens Securely

// macOS Keychain
keychain.store(
  key: "nexlayer.access_token",
  value: accessToken,
  accessControl: .userPresenceRequired  // Optional: biometric unlock
)
keychain.store(
  key: "nexlayer.refresh_token",
  value: refreshToken,
  accessControl: .unlockableWhenUnlocked
)

---

4. MCP Tool Calls with Access Token

Instead of:

// Current: fragile cookie interception
{
  "name": "nexlayer_apply_coupon",
  "arguments": {
    "coupon_code": "SAVE20",
    "sessionToken": "session-cookie-value",  // ❌ Injected by Claude
    "userIP": "192.168.1.1"
  }
}

Use OAuth Bearer Token:

// Standard: Authorization header
{
  "name": "nexlayer_apply_coupon",
  "arguments": {
    "coupon_code": "SAVE20"
  },
  "headers": {
    "Authorization": "Bearer eyJhbGciOiJIUzI1NiI..."
  }
}

---

Token Refresh & Lifecycle

Refresh Token Flow

Refresh Token Rotation is strongly recommended by RFC 9700 (Security BCP) and OAuth 2.1, making Refresh Tokens single-use and replacing them on every refresh.

When Access Token Expires:

POST https://nexlayer.com/oauth/token
Content-Type: application/x-www-form-urlencoded

grant_type=refresh_token&
refresh_token=refresh-token-xyz&
client_id=mac-native-mcp-xyz

Response:

{
  "access_token": "new-access-token...",
  "token_type": "Bearer",
  "expires_in": 3600,
  "refresh_token": "new-refresh-token-xyz"
}

Client Behavior:

1. Attempt MCP tool call with current access token
2. If 401 Unauthorized, refresh using refresh token
3. Retry with new access token
4. Update Keychain with new tokens

---

Security Best Practices

1. Token Expiration Strategy

• Access Token: 15–60 minutes (short-lived)
• Refresh Token: 7–30 days (longer-lived)
• Allowing unlimited refresh would make the risk of a leaked Refresh Token permanent; in practice, limits are almost always applied

2. PKCE Mandatory for Native Apps

The latest Security Best Current Practice recommends using PKCE for all types of apps, even apps with a client secret.

3. No Client Secret in Native Apps

• Public clients (no secret) prevent attackers from impersonating the app
• All authentication relies on user presence via system browser

4. Secure Token Storage

// ✅ Use platform secure storage
keychain.store(token, accessControl: .unlockableWhenUnlocked)

// ❌ Avoid
UserDefaults.standard["accessToken"] = token  // Plaintext

5. Token Revocation on Logout

POST https://nexlayer.com/oauth/revoke
Content-Type: application/x-www-form-urlencoded

token=access-token-value&
client_id=mac-native-mcp-xyz

---

API Compatibility Layer

Backward Compatibility: Adapter Pattern

If Nexlayer's MCP tools still expect sessionToken parameter:

func callMCPTool(_ toolName: String, args: [String: Any]) -> Result {
  var adaptedArgs = args
  
  // Inject access token as legacy parameter
  if let token = keychain.getAccessToken() {
    adaptedArgs["sessionToken"] = token
  }
  
  return mcp.call(toolName, adaptedArgs)
}

Better: Update Nexlayer MCP tools to:

1. Accept Bearer token in Authorization header
2. Parse JWT and extract sub (user ID), scope, etc.
3. Gradually deprecate sessionToken parameter

---

Discovery: OAuth Server Metadata

Authorization Server Metadata (RFC 8414) allows clients to discover OAuth endpoints and authorization server capabilities.

Request:

GET https://nexlayer.com/.well-known/openid-configuration

Response (OIDC Discovery):

{
  "issuer": "https://nexlayer.com",
  "authorization_endpoint": "https://nexlayer.com/oauth/authorize",
  "token_endpoint": "https://nexlayer.com/oauth/token",
  "revocation_endpoint": "https://nexlayer.com/oauth/revoke",
  "introspection_endpoint": "https://nexlayer.com/oauth/introspect",
  "jwks_uri": "https://nexlayer.com/.well-known/jwks.json",
  "scopes_supported": ["read:credits", "write:coupon", "read:referral"],
  "response_types_supported": ["code"],
  "grant_types_supported": ["authorization_code", "refresh_token"],
  "token_endpoint_auth_methods_supported": ["none"]
}

Benefit: Clients auto-discover endpoints without hardcoding.

---

Implementation Checklist

• OAuth Authorization Server Setup

  • Create /oauth/authorize endpoint
  • Create /oauth/token endpoint
  • Create /oauth/revoke endpoint
  • Publish .well-known/openid-configuration

• Native Client (mac-native-mcp)

  • Implement PKCE flow with ASWebAuthenticationSession
  • Secure token storage in Keychain
  • Automatic token refresh on expiration
  • Update MCP tool calls to use Bearer tokens

• MCP Tool Backend

  • Update tool handlers to validate Bearer tokens
  • Extract user context from JWT claims (no sessionToken param needed)
  • Implement token introspection if using opaque tokens
  • Add scope-based authorization checks

• Testing & Security

  • Test PKCE flow end-to-end
  • Test token refresh & expiration
  • Test revocation
  • Verify Bearer token rejection on invalid/expired tokens
  • Penetration test token handling

---

References

• RFC 6749: The OAuth 2.0 Authorization Framework
• RFC 6750: Bearer Token Usage (access token format)
• RFC 7662: Token Introspection
• RFC 8414: Authorization Server Metadata
• RFC 8252: Native Apps recommendations
• RFC 9068: JWT Profile for Access Tokens
• RFC 9700: OAuth Security Best Current Practice

---

Migration Path

1. Phase 1: Implement OAuth server alongside existing auth
2. Phase 2: Update native client to use OAuth flow
3. Phase 3: Dual-support both Bearer tokens and sessionToken parameter
4. Phase 4: Deprecate sessionToken, require Bearer tokens
5. Phase 5: Sunset legacy auth mechanism

This phased approach ensures backward compatibility while modernizing the authentication layer.

[jay-elizaga-dev]

Existing OAuth implementations require gated approval to trusted OAuth clients.

DO NOT GIVE OAuth keys without centralized/federated authorization from a signing-source within Nexlayer. Third-part OAuth apps MUST be associated with a verified users.

[jay-elizaga-dev]

[jay-elizaga-dev]

billing mutations are gated without Oauth Implementations

[musaabhasan]

For MCP clients, I would avoid carrying browser session-token semantics forward and make the OAuth boundary explicit.

A practical model is:

• Use authorization code with PKCE or device authorization for native/CLI clients.
• Issue audience-bound access tokens for the MCP resource server, not general web-session tokens.
• Map scopes to tool groups or action classes, for example mcp:deploy:read, mcp:deploy:write, mcp:logs:read.
• Keep high-impact tools behind step-up approval or a short-lived delegated grant.
• Include token expiry, subject, client ID, tenant/project, and scope in the MCP audit event for every tool call.
• Support revocation and introspection so a disabled client or user session stops working quickly.

The most important distinction is that an MCP token should authorize a bounded tool action, not impersonate the whole web session. That makes third-party clients easier to reason about and safer to revoke.