oauth-oidc-implementer — Claude Code skill: setup & features
oauth-oidc-implementer guides implementation of OAuth 2.0 and OpenID Connect flows, token rotation, social logins, and secure JWT verification in web apps.
MIT 183 installs ★ 274 updated 2026-10-30
npx skills add curiositech/some_claude_skills --skill oauth-oidc-implementer -a claude-codeWhat oauth-oidc-implementer does
The skill supplies code blueprints and validation steps for core authorization flows. It covers Authorization Code with PKCE for single-page apps, Client Credentials for machine-to-machine calls, and Device Authorization flows. It enforces token validation, state checks to prevent CSRF, and nonces against replay attacks.
It covers identity provider integrations for Auth0, Okta, Keycloak, alongside social login with Google, GitHub, and Microsoft. Storing refresh tokens in httpOnly cookies is treated as mandatory over localStorage to avoid credential leaks via script injection.
Legacy Implicit flow is addressed purely to explain why teams must replace it.
What it helps with
- configure social login with Google, GitHub, or Microsoft
- implement Authorization Code flow with PKCE in single-page applications
- handle refresh token rotation with httpOnly cookie storage
- verify incoming JWT signatures using JWKS in backend services
Example prompts for the agent
- Set up GitHub OAuth login in Next.js App Router with refresh tokens in httpOnly cookies
- Generate a PKCE verifier and challenge function in TypeScript for a client-side app
- Write an Express middleware to validate JWTs against a JWKS endpoint
How to install oauth-oidc-implementer
1Skills CLI (Vercel)
npx skills add curiositech/some_claude_skills --skill oauth-oidc-implementer -a claude-code2Manually: put the files in place
~/.claude/skills/oauth-oidc-implementer/SKILL.mdCopy the whole skill folder; for one project use .claude/skills/oauth-oidc-implementer/
1Skills CLI (Vercel)
npx skills add curiositech/some_claude_skills --skill oauth-oidc-implementer -a codex2Manually: put the files in place
.agents/skills/oauth-oidc-implementer/SKILL.mdFor all projects use ~/.agents/skills/
1Skills CLI (Vercel)
npx skills add curiositech/some_claude_skills --skill oauth-oidc-implementer -a cursor2Manually: put the files in place
.cursor/skills/oauth-oidc-implementer/SKILL.mdCursor also reads .agents/skills/ and .claude/skills/
1GitHub CLI
gh skill install curiositech/some_claude_skills .claude/skills/oauth-oidc-implementer2Manually: put the files in place
.github/skills/oauth-oidc-implementer/SKILL.md1Skills CLI (Vercel)
npx skills add curiositech/some_claude_skills --skill oauth-oidc-implementer -a gemini-cli2Platform CLI
gemini skills install https://github.com/curiositech/some_claude_skills --path .claude/skills/oauth-oidc-implementerManually: put the files in place
.devin/skills/oauth-oidc-implementer/SKILL.mdThe legacy .windsurf/skills/ path still works
Skills CLI (Vercel)
npx skills add curiositech/some_claude_skills --skill oauth-oidc-implementer -a opencodeClaude.ai
Zip the folder and upload it in Settings → Capabilities → Skills
Step by step, with commands for each platform: How to install skills in Claude Code: five ways
Questions about oauth-oidc-implementer
How do I install oauth-oidc-implementer in Claude Code?
Run npx skills add curiositech/some_claude_skills --skill oauth-oidc-implementer -a claude-code in your terminal. You can also place the file directly at ~/.claude/skills/oauth-oidc-implementer/SKILL.md.
What does oauth-oidc-implementer do?
It provides architecture patterns and code examples for setting up OAuth 2.0 and OIDC flows securely. It assists with token storage, claims validation, and social login configurations.
Which identity providers does this skill cover?
It details setups for Auth0, Okta, self-hosted Keycloak, and social providers like Google, GitHub, and Microsoft.
Source text
SKILL.md · MIT
---
name: oauth-oidc-implementer
description: Expert in implementing OAuth 2.0 and OpenID Connect (OIDC) authentication flows. Specializes in secure token handling, social login integration, API authorization, and identity provider configuration.
Handles both client-side and server-side flows with security best practices.
version: 1.0.0
metadata:
category: security
tags:
- oauth
- oidc
- authentication
- authorization
- jwt
- security
pairs-with:
- skill: modern-auth-2026
reason: OAuth/OIDC is one auth mechanism alongside passkeys in the modern auth stack
- skill: security-auditor
reason: OAuth token handling and PKCE flow security require dedicated vulnerability scanning
- skill: api-architect
reason: API authentication design patterns depend on OAuth scope and token architecture
---
# OAuth/OIDC Implementer
## Overview
Expert in implementing OAuth 2.0 and OpenID Connect (OIDC) authentication flows. Specializes in secure token handling, social login integration, API authorization, and identity provider configuration. Handles both client-side and server-side flows with security best practices.
## When to Use
- Implementing "Login with Google/GitHub/etc." social login
- Setting up OAuth 2.0 for API authorization
- Configuring OIDC for enterprise SSO
- Designing token refresh and session management
- Implementing PKCE for mobile/SPA applications
- Securing API endpoints with JWT validation
- Integrating with identity providers (Auth0, Okta, Keycloak)
- Troubleshooting OAuth flow failures
## Capabilities
### OAuth 2.0 Flows
- Authorization Code flow (with PKCE)
- Client Credentials flow for service-to-service
- Implicit flow (legacy, understand why to avoid)
- Device Authorization flow for IoT
- Refresh token rotation
### OpenID Connect
- ID token validation and claims
- UserInfo endpoint usage
- Discovery document (`.well-known/openid-configuration`)
- Session management (front-channel/back-channel logout)
- PKCE for public clients
### Token Management
- JWT structure (header, payload, signature)
- Access token vs ID token vs refresh token
- Token storage strategies (httpOnly cookies vs localStorage)
- Token refresh patterns
- Revocation and logout
### Security Best Practices
- PKCE (Proof Key for Code Exchange)
- State parameter for CSRF protection
- Nonce for replay protection
- Secure token storage
- Short-lived access tokens
### Identity Providers
- Auth0 integration
- Okta configuration
- Keycloak self-hosted
- Google/GitHub/Microsoft social login
- SAML to OIDC bridge
## Dependencies
Works well with:
- `nextjs-app-router-expert` - Full-stack auth implementation
- `api-architect` - API authorization design
- `cloudflare-worker-dev` - Edge authentication
- `site-reliability-engineer` - Auth monitoring
## Examples
### Authorization Code Flow with PKCE (SPA)
```typescript
// 1. Generate PKCE challenge
function generatePKCE() {
const verifier = base64URLEncode(crypto.getRandomValues(new Uint8Array(32)));
const challenge = base64URLEncode(
await crypto.subtle.digest('SHA-256', new TextEncoder().encode(verifier))
);
return { verifier, challenge };
}
// 2. Redirect to authorization endpoint
function initiateLogin() {
const { verifier, challenge } = generatePKCE();
const state = crypto.randomUUID();
// Store verifier and state for later validation
sessionStorage.setItem('pkce_verifier', verifier);
sessionStorage.setItem('oauth_state', state);
const params = new URLSearchParams({
response_type: 'code',
client_id: 'your-client-id',
redirect_uri: 'https://yourapp.com/callback',
scope: 'openid profile email',
state: state,
code_challenge: challenge,
code_challenge_method: 'S256',
});
window.location.href = `https://auth.example.com/authorize?${params}`;
}
// 3. Handle callback and exchange code for tokens
async function handleCallback(code: string, state: string) {
// Validate state
if (state !== sessionStorage.getItem('oauth_state')) {
throw new Error('State mismatch - possible CSRF attack');
}
const verifier = sessionStorage.getItem('pkce_verifier');
const response = await fetch('https://auth.example.com/token', {
method: 'POST',
headers: { 'Content-Type': 'application/x-www-form-urlencoded' },
body: new URLSearchParams({
grant_type: 'authorization_code',
code,
redirect_uri: 'https://yourapp.com/callback',
client_id: 'your-client-id',
code_verifier: verifier,
}),
});
const tokens = await response.json();
// { access_token, id_token, refresh_token, expires_in }
// Clean up
sessionStorage.removeItem('pkce_verifier');
sessionStorage.removeItem('oauth_state');
return tokens;
}
```
### Next.js API Route Token Handler
```typescript
// app/api/auth/callback/route.ts
import { cookies } from 'next/headers';
import { NextResponse } from 'next/server';
export async function GET(request: Request) {
const { searchParams } = new URL(request.url);
const code = searchParams.get('code');
const state = searchParams.get('state');
// Validate state from cookie
const cookieStore = cookies();
const storedState = cookieStore.get('oauth_state')?.value;
if (state !== storedState) {
return NextResponse.redirect('/auth/error?reason=state_mismatch');
}
// Exchange code for tokens (server-side, can use client_secret)
const tokenResponse = await fetch('https://auth.example.com/token', {
method: 'POST',
headers: { 'Content-Type': 'application/x-www-form-urlencoded' },
body: new URLSearchParams({
grant_type: 'authorization_code',
code: code!,
redirect_uri: process.env.REDIRECT_URI!,
client_id: process.env.CLIENT_ID!,
client_secret: process.env.CLIENT_SECRET!,
}),
});
const tokens = await tokenResponse.json();
// Store refresh token in httpOnly cookie
const response = NextResponse.redirect('/dashboard');
response.cookies.set('refresh_token', tokens.refresh_token, {
httpOnly: true,
secure: process.env.NODE_ENV === 'production',
sameSite: 'lax',
maxAge: 60 * 60 * 24 * 30, // 30 days
path: '/',
});
// Access token can go to client or httpOnly cookie
response.cookies.set('access_token', tokens.access_token, {
httpOnly: true,
secure: process.env.NODE_ENV === 'production',
sameSite: 'lax',
maxAge: tokens.expires_in,
path: '/',
});
return response;
}
```
### JWT Validation (Node.js)
```typescript
import jwt from 'jsonwebtoken';
import jwksClient from 'jwks-rsa';
const client = jwksClient({
jwksUri: 'https://auth.example.com/.well-known/jwks.json',
cache: true,
rateLimit: true,
});
function getKey(header: jwt.JwtHeader, callback: jwt.SigningKeyCallback) {
client.getSigningKey(header.kid, (err, key) => {
const signingKey = key?.getPublicKey();
callback(err, signingKey);
});
}
export async function validateToken(token: string): Promise<JWTPayload> {
return new Promise((resolve, reject) => {
jwt.verify(
token,
getKey,
{
algorithms: ['RS256'],
issuer: 'https://auth.example.com/',
audience: 'your-client-id',
},
(err, decoded) => {
if (err) reject(err);
else resolve(decoded as JWTPayload);
}
);
});
}
// Middleware usage
export async function authMiddleware(req: Request) {
const token = req.headers.get('Authorization')?.replace('Bearer ', '');
if (!token) {
return new Response('Unauthorized', { status: 401 });
}
try {
const payload = await validateToken(token);
// Attach user to request context
return { user: payload };
} catch (error) {
return new Response('Invalid token', { status: 401 });
}
}
```
### Token Refresh Pattern
```typescript
// Client-side token refresh with race condition handling
let refreshPromise: Promise<string> | null = null;
async function getAccessToken(): Promise<string> {
const accessToken = localStorage.getItem('access_token');
const expiresAt = localStorage.getItem('token_expires_at');
// Check if token is still valid (with 60s buffer)
if (accessToken && expiresAt && Date.now() < parseInt(expiresAt) - 60000) {
return accessToken;
}
// Deduplicate concurrent refresh requests
if (refreshPromise) {
return refreshPromise;
}
refreshPromise = refreshAccessToken();
try {
return await refreshPromise;
} finally {
refreshPromise = null;
}
}
async function refreshAccessToken(): Promise<string> {
const response = await fetch('/api/auth/refresh', {
method: 'POST',
credentials: 'include', // Send httpOnly refresh token cookie
});
if (!response.ok) {
// Refresh failed, redirect to login
window.location.href = '/login';
throw new Error('Token refresh failed');
}
const { access_token, expires_in } = await response.json();
localStorage.setItem('access_token', access_token);
localStorage.setItem('token_expires_at', String(Date.now() + expires_in * 1000));
return access_token;
}
```
### Social Login Setup (Auth0)
```typescript
// auth0.config.ts
export const auth0Config = {
domain: process.env.AUTH0_DOMAIN!,
clientId: process.env.AUTH0_CLIENT_ID!,
clientSecret: process.env.AUTH0_CLIENT_SECRET!,
redirectUri: process.env.AUTH0_REDIRECT_URI!,
scope: 'openid profile email',
audience: process.env.AUTH0_AUDIENCE, // For API access
};
// Login URL builder
export function getLoginUrl(connection?: string) {
const params = new URLSearchParams({
response_type: 'code',
client_id: auth0Config.clientId,
redirect_uri: auth0Config.redirectUri,
scope: auth0Config.scope,
state: generateState(),
...(auth0Config.audience && { audience: auth0Config.audience }),
...(connection && { connection }), // 'google-oauth2', 'github', etc.
});
return `https://${auth0Config.domain}/authorize?${params}`;
}
```
### OIDC Discovery
```typescript
// Fetch and cache OIDC configuration
interface OIDCConfig {
authorization_endpoint: string;
token_endpoint: string;
userinfo_endpoint: string;
jwks_uri: string;
issuer: string;
}
let oidcConfig: OIDCConfig | null = null;
export async function getOIDCConfig(issuer: string): Promise<OIDCConfig> {
if (oidcConfig) return oidcConfig;
const response = await fetch(`${issuer}/.well-known/openid-configuration`);
oidcConfig = await response.json();
return oidcConfig;
}
```
## Best Practices
1. **Always use PKCE** - Even for confidential clients, it adds security
2. **Validate state parameter** - Prevents CSRF attacks
3. **Use httpOnly cookies** - For refresh tokens, never localStorage
4. **Short-lived access tokens** - 15 minutes is common, refresh as needed
5. **Validate tokens server-side** - Don't trust client-side validation alone
6. **Use the nonce claim** - Prevents replay attacks with ID tokens
7. **Implement proper logout** - Revoke tokens and clear sessions
8. **Validate audience and issuer** - Ensure tokens are for your app
9. **Rotate refresh tokens** - Issue new refresh token on each use
## Common Pitfalls
- **Storing tokens in localStorage** - Vulnerable to XSS attacks
- **Not validating state** - Opens CSRF vulnerability
- **Implicit flow for SPAs** - Deprecated, use Authorization Code + PKCE
- **Long-lived access tokens** - Increases risk if compromised
- **Not validating JWT signature** - Anyone can forge unsigned tokens
- **Hardcoded client secrets** - Use environment variables
- **Missing token revocation** - Users can't properly log out
- **Not handling token expiry** - Silent refresh failures cause bad UX
© curiositech · MIT · curiositech/some_claude_skills