oauth2-oidc-security-flows
Implement enterprise OAuth 2.1 and OpenID Connect (OIDC) authorization code flow with Proof Key for Code Exchange (PKCE), state and nonce verification, refresh token rotation, token revocation, and centralized IdP federation (Keycloak, Auth0, Okta). Trigger when building secure authentication, single sign-on (SSO), or third-party delegated authorization.
- License 许可
- MIT
- 最近更新
- 2026-10-17
- Stars
- ★ 8
- Forks
- 1
01 前言 Front Matter
- name
- oauth2-oidc-security-flows
- metadata
- { "category": "Identity Auth and Access Management" }
- description
- Implement enterprise OAuth 2.1 and OpenID Connect (OIDC) authorization code flow with Proof Key for Code Exchange (PKCE), state and nonce verification, refresh token rotation, token revocation, and centralized IdP federation (Keycloak, Auth0, Okta). Trigger when building secure authentication, single sign-on (SSO), or third-party delegated authorization.
- compatibility
- OAuth 2.1 RFC standards, OIDC Core 1.0, RFC 7636 (PKCE), RFC 7009
03 SKILL.md 正文
OAuth 2.1 & OpenID Connect Security Flows Skill Guide
This skill governs standard, hardened implementation of OAuth 2.1 and OIDC authentication and authorization patterns for modern SPAs, mobile apps, and backend APIs.
1. Authorization Code Flow with PKCE (RFC 7636)
OAuth 2.1 mandates PKCE (Proof Key for Code Exchange) for all clients, deprecating the legacy Implicit Grant and Resource Owner Password Credentials (ROPC) grant.
+--------+ +---------------+
| |--(A)- Generate code_verifier -| |
| | and code_challenge | |
| | | |
| |--(B)- GET /authorize -------->| Authorization |
| | &code_challenge=SHA256 | Server (IdP) |
| Client | &state=RANDOM_NONCE | (Keycloak/ |
| (App) |<-(C)- 302 Redirect with code -| Auth0/Okta) |
| | | |
| |--(D)- POST /token ----------->| |
| | code + code_verifier | |
| | &client_id | |
| |<-(E)- Return Tokens ----------| |
| | (access, id, refresh) | |
+--------+ +---------------+
2. Production Implementation Patterns
A. PKCE Generator & Validator (TypeScript / Node.js)
import crypto from "node:crypto";
export interface PKCEPair {
codeVerifier: string;
codeChallenge: string;
}
/**
* Generates a cryptographically secure PKCE code verifier and SHA256 challenge.
*/
export function generatePKCE(): PKCEPair {
// RFC 7636 Section 4.1: High-entropy cryptographic random string (43 to 128 characters)
const codeVerifier = crypto
.randomBytes(32)
.toString("base64url");
const codeChallenge = crypto
.createHash("sha256")
.update(codeVerifier)
.digest("base64url");
return { codeVerifier, codeChallenge };
}
/**
* Validates code_verifier against code_challenge on the authorization server.
*/
export function verifyPKCE(verifier: string, challenge: string): boolean {
const computed = crypto
.createHash("sha256")
.update(verifier)
.digest("base64url");
return crypto.timingSafeEqual(
Buffer.from(computed),
Buffer.from(challenge)
);
}
B. OIDC Token Exchange & Validation Handler (Python)
import time
import httpx
from jose import jwt, jwk
from pydantic import BaseModel
class TokenResponse(BaseModel):
access_token: str
id_token: str
refresh_token: str
token_type: str
expires_in: int
class OIDCClient:
def __init__(self, idp_base_url: str, client_id: str, client_secret: str | None = None):
self.idp_base_url = idp_base_url.rstrip("/")
self.client_id = client_id
self.client_secret = client_secret
self._jwks_cache = None
async def get_jwks(self) -> dict:
if not self._jwks_cache:
async with httpx.AsyncClient() as client:
resp = await client.get(f"{self.idp_base_url}/protocol/openid-connect/certs")
resp.raise_for_status()
self._jwks_cache = resp.json()
return self._jwks_cache
async def exchange_code(
self,
code: str,
code_verifier: str,
redirect_uri: str,
) -> TokenResponse:
data = {
"grant_type": "authorization_code",
"client_id": self.client_id,
"code": code,
"code_verifier": code_verifier,
"redirect_uri": redirect_uri,
}
if self.client_secret:
data["client_secret"] = self.client_secret
async with httpx.AsyncClient() as client:
resp = await client.post(
f"{self.idp_base_url}/protocol/openid-connect/token",
data=data,
headers={"Content-Type": "application/x-www-form-urlencoded"},
)
resp.raise_for_status()
return TokenResponse(**resp.json())
async def verify_id_token(self, id_token: str, expected_nonce: str) -> dict:
jwks = await self.get_jwks()
unverified_header = jwt.get_unverified_header(id_token)
kid = unverified_header["kid"]
key = next((k for k in jwks["keys"] if k["kid"] == kid), None)
if not key:
raise ValueError(f"Public key {kid} not found in IdP JWKS")
claims = jwt.decode(
id_token,
key,
algorithms=["RS256"],
audience=self.client_id,
issuer=f"{self.idp_base_url}",
)
if claims.get("nonce") != expected_nonce:
raise ValueError("Nonce mismatch: potential replay attack")
return claims
3. Security Guidelines & Attack Mitigations
- Always Enforce PKCE: Never allow plain
code_challenge_method=plain; strictly reject anything exceptS256. - State Parameter for CSRF: Generate an unpredictable, encrypted or hashed
stateparameter stored in an HttpOnly session cookie, verified upon redirect. - Nonce for Replay Prevention: Include a unique
noncein/authorizerequests and verify that the returnedid_tokencontains an identicalnonceclaim. - Refresh Token Rotation (RTR): Invalidate the old refresh token whenever a new one is issued. If a revoked refresh token is presented, revoke all descended tokens immediately (compromise detection).
04 同仓库更多 Skills
security-audit
Comprehensive security guidance, source code audit, vulnerability assessment, and penetration test review for codebases, APIs, microservices, CLI tools, libraries, and LLM-backed applications. Triggers on requests to audit a codebase, conduct security reviews, find vulnerabilities or flaws, pen-test source code, or when the user asks in Arabic (فحص أمني، تدقيق الكود أمنياً، مراجعة الثغرات، فحص أمان المشروع). Supports Guidance mode (focused review) and Full Audit mode (deterministic 6-phase harness).
malware-analysis-reversing
Production malware analysis workflows, reverse engineering methodologies, isolated sandbox triage, static/dynamic binary analysis, memory forensics, and YARA detection rule authoring.
application-security-pentesting
Production Application Security (AppSec) standards, OWASP Top 10 vulnerability remediation, SAST/DAST pipeline integration, secure code review, threat modeling, and defensive security posture.
jwt-session-management-hardening
Harden JWT-based authentication and session lifecycles using asymmetric signing (RS256/EdDSA), JWKS rotation, strict claims validation, Redis-backed sliding window sessions, revocation lists, and secure HttpOnly cookie storage. Trigger when implementing token validation, session revocation, or hardening API authentication.
soc2-compliance-automation
Best practices for implementing SOC 2 Type II compliance controls, continuous evidence collection, infrastructure policy-as-code, and automated security monitoring. Use when automating Trust Services Criteria (Security, Availability, Confidentiality, Processing Integrity, Privacy), audit logging, IAM least privilege, or CI/CD security gates.
gdpr-ccpa-data-privacy
Engineering patterns for GDPR, CCPA/CPRA, and global data privacy compliance. Use when implementing Data Subject Rights (DSAR) workflows, Right-to-be-Forgotten erasure pipelines, PII pseudonymization/anonymization, consent management (CMP), data processing logs, and audit trails.