AGENT SKILL

socialite-development

Manages OAuth social authentication with Laravel Socialite. Activate when adding social login providers; configuring OAuth redirect/callback flows; retrieving authenticated user details; customizing scopes or parameters; setting up community providers; testing with Socialite fakes; or when the user mentions social login, OAuth, Socialite, or third-party authentication.

License 许可
MIT
最近更新
2026-11-11
Stars
★ 0
Forks
0

01 前言 Front Matter

name
socialite-development
license
MIT
metadata
{ "author": "laravel" }
description
Manages OAuth social authentication with Laravel Socialite. Activate when adding social login providers; configuring OAuth redirect/callback flows; retrieving authenticated user details; customizing scopes or parameters; setting up community providers; testing with Socialite fakes; or when the user mentions social login, OAuth, Socialite, or third-party authentication.

03 SKILL.md 正文

Socialite Authentication

Documentation

Use search-docs for detailed Socialite patterns and documentation (installation, configuration, routing, callbacks, testing, scopes, stateless auth).

Available Providers

Built-in: facebook, twitter, twitter-oauth-2, linkedin, linkedin-openid, google, github, gitlab, bitbucket, slack, slack-openid, twitch

Community: 150+ additional providers at socialiteproviders.com. For provider-specific setup, use WebFetch on https://socialiteproviders.com/{provider-name}.

Configuration key in config/services.php must match the driver name exactly — note the hyphenated keys: twitter-oauth-2, linkedin-openid, slack-openid.

Twitter/X: Use twitter-oauth-2 (OAuth 2.0) for new projects. The legacy twitter driver is OAuth 1.0. Driver names remain unchanged despite the platform rebrand.

Community providers differ from built-in providers in the following ways:

  • Installed via composer require socialiteproviders/{name}
  • Must register via event listener — NOT auto-discovered like built-in providers
  • Use search-docs for the registration pattern

Adding a Provider

1. Configure the provider

Add the provider's client_id, client_secret, and redirect to config/services.php. The config key must match the driver name exactly.

2. Create redirect and callback routes

Two routes are needed: one that calls Socialite::driver('provider')->redirect() to send the user to the OAuth provider, and one that calls Socialite::driver('provider')->user() to receive the callback and retrieve user details.

3. Authenticate and store the user

In the callback, use updateOrCreate to find or create a user record from the provider's response (id, name, email, token, refreshToken), then call Auth::login().

4. Customize the redirect (optional)

  • scopes() — merge additional scopes with the provider's defaults
  • setScopes() — replace all scopes entirely
  • with() — pass optional parameters (e.g., ['hd' => 'example.com'] for Google)
  • asBotUser() — Slack only; generates a bot token (xoxb-) instead of a user token (xoxp-). Must be called before both redirect() and user(). Only the token property will be hydrated on the user object.
  • stateless() — for API/SPA contexts where session state is not maintained

5. Verify

  1. Config key matches driver name exactly (check the list above for hyphenated names)
  2. client_id, client_secret, and redirect are all present
  3. Redirect URL matches what is registered in the provider's OAuth dashboard
  4. Callback route handles denied grants (when user declines authorization)

Use search-docs for complete code examples of each step.

Additional Features

Use search-docs for usage details on: enablePKCE(), userFromToken($token), userFromTokenAndSecret($token, $secret) (OAuth 1.0), retrieving user details.

User object: getId(), getName(), getEmail(), getAvatar(), getNickname(), token, refreshToken, expiresIn, approvedScopes

Testing

Socialite provides Socialite::fake() for testing redirects and callbacks. Use search-docs for faking redirects, callback user data, custom token properties, and assertion methods.

Common Pitfalls

  • Config key must match driver name exactly — hyphenated drivers need hyphenated keys (linkedin-openid, slack-openid, twitter-oauth-2). Mismatch silently fails.
  • Every provider needs client_id, client_secret, and redirect in config/services.php. Missing any one causes cryptic errors.
  • scopes() merges with defaults; setScopes() replaces all scopes entirely.
  • Missing stateless() in API/SPA contexts causes InvalidStateException.
  • Redirect URL in config/services.php must exactly match the provider's OAuth dashboard (including trailing slashes and protocol).
  • Do not pass state, response_type, client_id, redirect_uri, or scope via with() — these are reserved.
  • Community providers require event listener registration via SocialiteWasCalled.
  • user() throws when the user declines authorization. Always handle denied grants.

04 同仓库更多 Skills

uranghalus
uranghalus/opt-work

impeccable

Use when the user wants to design, redesign, shape, critique, audit, polish, clarify, distill, harden, optimize, adapt, animate, colorize, extract, or otherwise improve a frontend interface. Covers websites, landing pages, dashboards, product UI, app shells, components, forms, settings, onboarding, and empty states. Handles UX review, visual hierarchy, information architecture, cognitive load, accessibility, performance, responsive behavior, theming, anti-patterns, typography, fonts, spacing, layout, alignment, color, motion, micro-interactions, UX copy, error states, edge cases, i18n, and reusable design systems or tokens. Also use for bland designs that need to become bolder or more delightful, loud designs that should become quieter, live browser iteration on UI elements, or ambitious visual effects that should feel technically extraordinary. Not for backend-only or non-UI tasks.

★ 0
uranghalus
uranghalus/opt-work

impeccable

Use when the user wants to design, redesign, shape, critique, audit, polish, clarify, distill, harden, optimize, adapt, animate, colorize, extract, or otherwise improve a frontend interface. Covers websites, landing pages, dashboards, product UI, app shells, components, forms, settings, onboarding, and empty states. Handles UX review, visual hierarchy, information architecture, cognitive load, accessibility, performance, responsive behavior, theming, anti-patterns, typography, fonts, spacing, layout, alignment, color, motion, micro-interactions, UX copy, error states, edge cases, i18n, and reusable design systems or tokens. Also use for bland designs that need to become bolder or more delightful, loud designs that should become quieter, live browser iteration on UI elements, or ambitious visual effects that should feel technically extraordinary. Not for backend-only or non-UI tasks.

★ 0
uranghalus
uranghalus/opt-work

impeccable

Use when the user wants to design, redesign, shape, critique, audit, polish, clarify, distill, harden, optimize, adapt, animate, colorize, extract, or otherwise improve a frontend interface. Covers websites, landing pages, dashboards, product UI, app shells, components, forms, settings, onboarding, and empty states. Handles UX review, visual hierarchy, information architecture, cognitive load, accessibility, performance, responsive behavior, theming, anti-patterns, typography, fonts, spacing, layout, alignment, color, motion, micro-interactions, UX copy, error states, edge cases, i18n, and reusable design systems or tokens. Also use for bland designs that need to become bolder or more delightful, loud designs that should become quieter, live browser iteration on UI elements, or ambitious visual effects that should feel technically extraordinary. Not for backend-only or non-UI tasks.

★ 0
uranghalus
uranghalus/opt-work

wayfinder-development

Use this skill for Laravel Wayfinder which auto-generates typed functions for Laravel controllers and routes. ALWAYS use this skill when frontend code needs to call backend routes or controller actions. Trigger when: connecting any React/Vue/Svelte/Inertia frontend to Laravel controllers, routes, building end-to-end features with both frontend and backend, wiring up forms or links to backend endpoints, fixing route-related TypeScript errors, importing from @/actions or @/routes, or running wayfinder:generate. Use Wayfinder route functions instead of hardcoded URLs. Covers: wayfinder() vite plugin, .url()/.get()/.post()/.form(), query params, route model binding, tree-shaking. Do not use for backend-only task

★ 0
uranghalus
uranghalus/opt-work

testing-best-practices

Laravel test design and review. Use when selecting coverage, naming or structuring tests, choosing assertions or test data, isolating dependencies, testing HTTP or security boundaries, improving suite performance, or reviewing test value. Use framework guidance or search-docs for Pest and PHPUnit syntax.

★ 0
uranghalus
uranghalus/opt-work

tailwindcss-development

Always invoke when the user's message includes 'tailwind' in any form. Also invoke for: building responsive grid layouts (multi-column card grids, product grids), flex/grid page structures (dashboards with sidebars, fixed topbars, mobile-toggle navs), styling UI components (cards, tables, navbars, pricing sections, forms, inputs, badges), adding dark mode variants, fixing spacing or typography, and Tailwind v3/v4 work. The core use case: writing or fixing Tailwind utility classes in HTML templates (Blade, JSX, Vue). Skip for backend PHP logic, database queries, API routes, JavaScript with no HTML/CSS component, CSS file audits, build tool configuration, and vanilla CSS.

★ 0