Social auth
19 files1 package1 dependency
This pack adds social sign-in to your API. Because OAuth rides a full-page browser redirect, the backend runs the provider round-trip and hands the result back to your frontend, fitting the guard your app already authenticates with. It ships endpoints, not screens.
- Fits your existing guard, a session guard's cookie rides the redirect, an access-token guard hands the frontend a one-time PKCE-bound code to exchange for a token.
- 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 methods endpoint reports the configured providers and the visitor's last-used one, so the client renders the right buttons without hardcoding them.
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.
- Discover your default guard, access tokens or session, and the frontend URL your OAuth callback redirects to.
- Land the backend as shipped, from the
social_identitiesmigration and the nullable-password change through thewithSocialIdentity()model mixin, the guard-branched OAuth redirect and callback controller, the public methods endpoint, and the connected-accounts endpoints. On a tokens guard it adds the PKCE token-exchange endpoint. - Configure the providers you pick, Google and GitHub by default, record the last-used method on your existing login and signup, and add the two-factor branch when your app already has two-factor.
- Run the tests, drive the endpoints, and hand you a brief for the frontend to build against.
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 and which guard you authenticate with. This is the shape of an apply onto the API starter kit with the auth pack in place.
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
Validators
user.tsapp/validators/user.tsAdds theoauthExchangeValidator. For a tokens guard only.edited
Controllers & responses
social_auth_controller.tsapp/controllers/social_auth_controller.tsRuns the OAuth redirect and callback, redirecting to your frontend with the guard's credential.createdauth_methods_controller.tsapp/controllers/auth_methods_controller.tsReports the configured providers and the visitor's last-used method.createdsocial_identities_controller.tsapp/controllers/social_identities_controller.tsLists and disconnects linked providers, refusing the last factor of a password-less account.createdoauth_token_controller.tsapp/controllers/oauth_token_controller.tsExchanges the one-time PKCE code for an access token. For a tokens guard only.createdsocial_identity_transformer.tsapp/transformers/social_identity_transformer.tsMaps a social identity row into the shape the endpoints return.createdsession_controller.tsapp/controllers/session_controller.tsRecordsemailas the last method after a credential login. Lands on your discovered login controller.editednew_account_controller.tsapp/controllers/new_account_controller.tsRecordsemailas the last method after a signup issues the credential. Lands on your discovered signup controller.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, methods, and connected-accounts routes, and the token-exchange route on a tokens guard.edited
Factories & tests
social_identity_factory.tsdatabase/factories/social_identity_factory.tsSeedssocial_identitiesrows for the tests.createdconnected_accounts.spec.tstests/functional/social_auth/connected_accounts.spec.tsSpecs for listing and disconnecting connected accounts.createdtoken_exchange.spec.tstests/functional/social_auth/token_exchange.spec.tsSpecs for the PKCE token exchange. For a tokens guard only.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 endpoint returns 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.
Added in Flow 0.2.0.