Social auth
22 files1 package1 dependency
This pack adds social sign-in to your app. Provider buttons on your login and signup pages run an OAuth round-trip, and signed-in users get a connected-accounts area to link more providers or disconnect ones they no longer use.
- Provider emails are trusted only when the provider verifies them, and an unverified one is routed through your existing email-verification flow.
- An email that already belongs to a local account is refused rather than silently linked to the provider.
- A password-less account cannot disconnect its last provider, so it can never lock itself out.
- A "Last used" hint marks whichever method the visitor signed in with last.
Depends on Auth
This pack extends the auth pack's User model and reuses its email-verification flow. Apply the auth pack first.
Apply the social auth pack with Flow. Start a new session in your selected coding agent and execute the following slash command inside it.
$ npx @adonisplus/flow apply --pack=social-auth --agent=claude
$ npx @adonisplus/flow apply --pack=social-auth --agent=codex
$ npx @adonisplus/flow apply --pack=social-auth --agent=cursor
$ npx @adonisplus/flow apply --pack=social-auth --agent=opencode
After applying, Flow will make the following changes to your app.
- Reuse your account settings area to host the connected accounts, or establish a minimal profile page when you have none.
- Land the backend as shipped, from the
social_identitiesmigration and the nullable-password change through thewithSocialIdentity()model mixin, the OAuth redirect and callback controller, the disconnect controller, the transformer, and the routes. - Configure the providers you pick, Google and GitHub by default, wire the "Last used" hint into your login and signup, and add the two-factor branch when your app already has two-factor.
- Restyle the provider buttons on your login and signup pages and the connected-accounts section to your design system.
- Run the tests, then walk the sign-in, connect, and disconnect flow and show you the result.
Delta will differ
Flow adapts the pack to your app, so the exact set of created and edited files depends on what you already have. This is the shape of an apply onto the React starter kit with the auth pack in place.
Layouts
settings.tsxinertia/layouts/settings.tsxLists the Profile page in the settings sidebar.editedapp.tsxinertia/layouts/app.tsxLinks the settings area in the navigation.edited
Migrations
xxxx_create_social_identities_table.tsdatabase/migrations/xxxx_create_social_identities_table.tsCreates thesocial_identitiestable, with a unique constraint on the provider and provider user id.createdxxxx_make_password_nullable_in_users.tsdatabase/migrations/xxxx_make_password_nullable_in_users.tsMakes the userspasswordcolumn nullable, for accounts that only ever sign in through a provider.created
Model
user.tsapp/models/user.tsAdds thewithSocialIdentity()mixin to the compose chain.edited
Controllers & responses
social_auth_controller.tsapp/controllers/social_auth_controller.tsRuns the OAuth redirect and callback, dispatching the four sign-in outcomes.createdsocial_identities_controller.tsapp/controllers/social_identities_controller.tsDisconnects a linked provider, refusing the last factor of a password-less account.createdsocial_identity_transformer.tsapp/transformers/social_identity_transformer.tsMaps a social identity row into the shape the profile page consumes.createdprofile_controller.tsapp/controllers/profile_controller.tsLoads the connected identities and password state and passes them to the profile page. Created when you have no settings area for Flow to reuse.editedsession_controller.tsapp/controllers/session_controller.tsPasses thelastLoginMethodprop to the login page and recordsemailas the last method after a credential login.editednew_account_controller.tsapp/controllers/new_account_controller.tsPasses thelastLoginMethodprop to the signup page and recordsemailas the last method after a signup logs the new user in.edited
Pages
social_identities.tsinertia/lib/social_identities.tsIndexes a user's identities by provider name for the profile page.createdlogin.tsxinertia/pages/auth/login.tsxAdds the provider buttons and the "Last used" badge.editedsignup.tsxinertia/pages/auth/signup.tsxAdds the provider buttons and their "Last used" badges.editedprofile.tsxinertia/pages/account/profile.tsxAdds the connected-accounts section. Created alongside the controller when you have no settings page.edited
Routes & config
ally.tsconfig/ally.tsAlly configuration for the providers you chose.createdadonisrc.tsadonisrc.tsRegisters the ally provider.editedenv.tsstart/env.tsAdds the provider credential env vars.edited.env.envAdds placeholder values for the provider credentials. Replace them with the real client ID and secret.editedroutes.tsstart/routes.tsAdds the OAuth redirect and callback routes and the disconnect route.edited
Factories & tests
social_identity_factory.tsdatabase/factories/social_identity_factory.tsSeedssocial_identitiesrows for the tests.createdlinking.spec.tstests/browser/social_auth/linking.spec.tsSpecs for the last-factor lockout and disconnecting with another factor present.created
Configuration
Section titled "Configuration"Social identities are stored by the withSocialIdentity() mixin on the User model, which reads and writes one row per linked provider account. Pass an options object to the mixin to change where those rows live.
tablestringsocial_identities.export default class User extends compose(
UserSchema,
withAuthFinder(hash),
withManagedEmail(),
withSocialIdentity({ table: 'oauth_identities' })
) {}One provider account links to one user
Section titled "One provider account links to one user"Every linked account is a row keyed by its provider name and the provider's own user id, with a unique constraint on that [provider, provider_user_id] pair behind it. Two behaviors follow:
- Linking a provider account the user already holds just refreshes it in place, so re-authenticating with the same provider is safe to repeat.
- Linking one that already belongs to a different user is refused with an error, so a single Google or GitHub account can never attach to two local accounts.
Provider data is a snapshot, not your source of truth
Section titled "Provider data is a snapshot, not your source of truth"Each identity row keeps the provider's email, name, nickname, and avatarUrl, and every sign-in refreshes them from the provider. These fields stay on the identity row and never flow back to your users table.
So a user renaming themselves on GitHub does not rename their account with you. The connected-accounts view reads the fresh provider snapshot, while your account record stays under your app's control.
Provider emails are trusted only when verified
Section titled "Provider emails are trusted only when verified"Not every provider confirms that the person owns the email it hands back. Ally reports this per provider as emailVerificationState, one of verified, unverified, or unsupported, and a new signup forks on it:
- A
verifiedemail is treated as active immediately. - Any other state routes the new account through the same email-verification flow the auth pack ships, so an unconfirmed address still has to prove itself before the account is active.
A colliding email is refused, not merged
Section titled "A colliding email is refused, not merged"When someone signs in with a provider whose email already belongs to a local account that has no link to that provider, resolveSocialIdentity returns a link_required outcome and the pack refuses the sign-in. It neither logs them in nor attaches the provider to the existing account.
Auto-linking on a matching email would let anyone who controls an address at a provider take over the local account that happens to share it. Instead the user is told to sign in with their original method and connect the provider from their account settings, where the link is made against a session that is already theirs.
Flow 1.1.0
Section titled "Flow 1.1.0"- The profile page now loads the connected accounts inside the
identitiesprop, so a partial reload of the page's other props no longer runs that query. - The test for disconnecting the last social account now checks that the button is disabled, instead of clicking it.
Flow 0.2.0
Section titled "Flow 0.2.0"- Added the pack.