Purpose
Turn a described application type and user type into a stage-by-stage narrative of the recommended authentication and authorization journey — from first login through token refresh and logout — so a solutions engineer can walk a customer through exactly how identity flows through their system, including the failure paths and edge cases that surface during real implementation.
When to Use
Invoke this skill when the user asks to:
- Map or document an authentication flow for a specific customer application
- Explain how login, SSO, MFA, and token refresh should work end to end
- Scope the recommended auth journey for a new app type (SPA, native mobile, B2B SaaS, machine-to-machine)
- Compare journey differences between user types (consumer, employee, partner, admin)
- Prepare a flow narrative for a technical design doc, SOW, or customer walkthrough
- Identify the failure and step-up paths that need handling before build
Inputs Required
Before starting, collect:
- Application type: SPA, server-rendered web app, native mobile, desktop, API/backend service, or M2M
- User type: Consumer B2C, employee/workforce, B2B partner, admin/privileged, or service account
- Identity provider model: Self-hosted auth, third-party IdP (Okta, Auth0, Entra ID, Cognito), federated SSO, or social login
- Auth protocol preference: OAuth 2.0 / OIDC, SAML, or "recommend one" if unspecified
- MFA requirements: Required always, risk-based/step-up only, optional, or none
- Session & token expectations: Desired session length, whether refresh tokens are allowed, single vs. multi-device
- Compliance or security constraints: Any regulatory driver (SOC 2, HIPAA, PCI, FedRAMP) that shapes the flow
If protocol or IdP model is unspecified, default to OAuth 2.0 with OIDC using Authorization Code + PKCE for interactive apps, and Client Credentials for M2M, and note the assumption.
Instructions
Step 1: Select the Grant Type and Flow Baseline
Match the application and user type to the correct OAuth/OIDC grant before describing anything:
- SPA / native mobile / desktop: Authorization Code + PKCE (never implicit — it's deprecated)
- Server-rendered web app with a confidential backend: Authorization Code with client secret
- Machine-to-machine / service account: Client Credentials
- Workforce SSO into a SaaS app: SAML or OIDC federation via the enterprise IdP
- Legacy or constrained device: Device Authorization Grant
State the chosen grant, why it fits this app + user type, and what token types will be issued (ID token, access token, refresh token).
Step 2: Describe the Journey Stage by Stage
Write the flow as an ordered narrative. For each stage, describe the actor action, the system response, and the artifact produced:
- Entry & unauthenticated state — how the user arrives, what they see, when the redirect to auth is triggered
- Identity assertion (login) — credential entry or IdP redirect; for SSO, the federation handoff and assertion validation
- MFA / step-up challenge — when it fires (always vs. risk-based), factor types, and what a passed vs. failed challenge produces
- Consent / authorization — scope grant (skip for first-party workforce apps; describe explicitly for third-party or partner access)
- Token issuance & session establishment — which tokens are returned, where they're stored (memory, secure cookie, keychain), and what the authenticated session now permits
- Authorized activity — how the access token is presented on each request and how the resource server validates it (signature, audience, scope, expiry)
- Token refresh — when the access token expires, how a refresh token silently obtains a new one, and refresh token rotation behavior
- Step-up for sensitive actions — re-authentication or additional factor required before high-risk operations (payment, admin change, data export)
- Logout & session termination — local logout vs. IdP single logout (SLO), token revocation, and refresh token invalidation
Step 3: Map the Failure and Edge Paths
For the journey above, describe what happens when things go wrong — customers always ask about these:
- Expired or revoked refresh token: forced re-authentication path
- MFA failure or lockout: retry limits and recovery flow
- Concurrent session / multi-device: how sessions coexist or invalidate each other
- IdP unavailable: fallback behavior and error surface
- Token replay or theft: rotation, binding, and detection response
- Consent revoked mid-session: how access is withdrawn
Step 4: Note the User-Type-Specific Adjustments
Call out how this journey differs from the default for the specified user type — e.g., admins get mandatory step-up and shorter sessions, partners get scoped and time-boxed access, service accounts skip interactive login entirely and rotate credentials on a schedule.
Step 5: Produce a Sequence Summary
Close with a compact numbered actor→system sequence (client → authorization server → resource server) that a reader can trace at a glance without the surrounding prose.
Output Format
- Structure: Grant-type selection → stage-by-stage journey narrative → failure/edge paths → user-type adjustments → sequence summary
- Length: 800–1,200 words
- Format: Structured document — numbered journey stages with actor/system/artifact detail; failure paths and adjustments as labeled bullets; sequence summary as a numbered list
- Sections: Grant & Token Baseline → Journey Stages (1–9) → Failure & Edge Paths → User-Type Adjustments → Sequence Summary
- Tone: Solutions engineer explaining to a customer's technical team — precise, protocol-correct, plain about tradeoffs, no marketing language
Quality Checklist
Before delivering output, verify:
- [ ] The chosen grant type is protocol-correct for the app + user type (no implicit grant for SPAs)
- [ ] All 9 journey stages are present and each names the artifact it produces (token, session, assertion)
- [ ] Token storage location is specified per app type (memory/cookie/keychain — not left ambiguous)
- [ ] At least 4 failure/edge paths are described with concrete system behavior
- [ ] User-type-specific adjustments are stated, not just the generic default flow
- [ ] The closing sequence summary traces client → authorization server → resource server in order
Notes
- The single most common customer confusion is refresh token behavior — always be explicit about rotation and what forces a full re-login
- For workforce SSO, the "login" stage is a federation handoff, not a credential form; don't describe a password screen the app never shows
- Step-up authentication is frequently omitted in first drafts — if any high-risk action exists in the app, the journey must include it
- When compliance constraints are provided, tie specific journey decisions to them (e.g., PCI → shorter sessions and mandatory step-up on payment) rather than listing them separately
How to use this skill
This file is a Claude Code skill in Anthropic's standard format — markdown with YAML frontmatter at the top.
Installing in Claude Code:
~/.claude/skills/<folder-name>/SKILL.md— auto-loads in every session anywhere on your machine (recommended for skills you'll use across multiple projects)<your-project>/.claude/skills/<folder-name>/SKILL.md— auto-loads only when working in that project (recommended for project-specific skills)
Restart Claude Code or open a new session to register.
Using in Claude.ai, ChatGPT, Gemini, or other AI tools:
- Drag this file into a new chat, or copy and paste its contents
- Send your task or request as your next message — the AI will apply the skill where it fits
For Claude Code skill details: https://docs.anthropic.com/en/docs/claude-code/skills