Skip to Content
better-auth-plugins

Authentication

Sign in with Steam, Epic Games, and Xbox, like any built-in social provider.

The authentication plugin adds sign-in providers that better-auth doesn't ship itself, so far the gaming platforms Steam, Epic Games, and Xbox. They work exactly like better-auth's built-in social providers: you sign in with signIn.social, link with linkSocial, and the callback is better-auth's own /callback/<provider>. Account linking, callbackURL checks, state and CSRF protection, disableSignUp, and session handling are better-auth's, unchanged.

This page covers what all providers share. Each provider has its own page for its credentials and options:

ProviderProtocolCredentials
SteamOpenID 2.0None needed; an optional API key
Epic GamesEpic Account Services (OpenID Connect)Client id and secret
XboxMicrosoft account, then Xbox LiveClient id and secret, Xbox developers only

Players get a placeholder email that nobody else can claim, since these platforms share no email address (see Placeholder emails).

Installation

Install the package

npm install @checodo/better-auth-authentication

Add the plugin to your auth config

Configure only the providers you use:

auth.ts
import { betterAuth } from "better-auth";
import { authentication } from "@checodo/better-auth-authentication";

export const auth = betterAuth({
  plugins: [
    authentication({
      steam: { apiKey: process.env.STEAM_API_KEY },
      epic: {
        clientId: process.env.EPIC_CLIENT_ID!,
        clientSecret: process.env.EPIC_CLIENT_SECRET!,
      },
      xbox: {
        clientId: process.env.XBOX_CLIENT_ID!,
        clientSecret: process.env.XBOX_CLIENT_SECRET!,
      },
    }),
  ],
});

The plugin adds no tables: users, accounts, and sessions are better-auth's own. Each provider's page says where to get its credentials.

Add the client plugin

auth-client.ts
import { createAuthClient } from "better-auth/client";
import { authenticationClient } from "@checodo/better-auth-authentication/client";

export const authClient = createAuthClient({
  plugins: [authenticationClient()],
});

It adds the plugin's error codes to the client; sign-in itself needs no new methods.

Usage

Sign in

await authClient.signIn.social({ provider: "steam", callbackURL: "/dashboard" });
await authClient.signIn.social({ provider: "epic", callbackURL: "/dashboard" });
await authClient.signIn.social({ provider: "xbox", callbackURL: "/dashboard" });

Everything signIn.social accepts works: errorCallbackURL, newUserCallbackURL, disableRedirect, requestSignUp, and additionalData (read by other plugins, such as a referral code).

Signed-in users can link a provider account to their user:

await authClient.linkSocial({ provider: "steam", callbackURL: "/settings" });

better-auth only links an account when the provider is trusted or vouches for a verified email, and when the emails match. These platforms share no email, so allow linking for them:

auth.ts
betterAuth({
  account: {
    accountLinking: {
      trustedProviders: ["steam", "epic", "xbox"],
      allowDifferentEmails: true,
    },
  },
});

This is safe for these providers: linking still needs the signed-in user to prove they own the provider account, and their placeholder emails can't match another user (see below). Without it, linking fails with error=unable_to_link_account.

Keep the placeholder email when providers are trusted

A trusted provider signs a user into an existing account with the same email, without asking. That is only safe because the placeholder emails belong to one provider account each. Don't set email or emailVerified in mapProfileToUser from the profile (a display name, say, or anything the player can change): with the provider trusted, a player who sets their profile to ceo@your-company.com would be signed in as that user.

Both settings apply to every provider, not only these three: allowDifferentEmails lets signed-in users link any social account, whatever its email (they still have to sign in to it), so turn it on only if that is fine for all your providers.

Placeholder emails

better-auth needs an email for every user, and Steam, Epic, and Xbox share none. Players get a placeholder made from their account id:

ProviderPlaceholder
Steam76561197960287930@steam.invalid
Epic<Epic account id>@epic.invalid
Xbox<XUID>@xbox.invalid
  • .invalid is reserved: these addresses can never receive email. Password resets, verification emails, and magic links don't reach these users; let them add a real email later (changeEmail) if you need one.
  • emailVerified is false.
  • Nobody can sign up with, or change their email to, a placeholder domain: that fails with EMAIL_DOMAIN_RESERVED. Only the provider's own callback (and your server code outside a request) can use it, so nobody can take a user's placeholder before that user signs in.
  • A user who has a real email (they signed up with it and linked the provider account, or changed their email later) keeps it: with overrideUserInfoOnSignIn, the provider updates their name and image, but never replaces their email with a placeholder.
  • Change the domain per provider with emailDomain, e.g. steam: { emailDomain: "steam.players.example.com" }. Each provider needs a domain of its own.

To show something nicer than the placeholder, use the user's name (the Steam persona name, Epic display name, or gamertag).

Errors

A failed sign-in redirects to better-auth's error page, or to errorCallbackURL, with an error query parameter: better-auth's own (state_mismatch, unable_to_get_user_info, ...), and for Steam two more, listed on the Steam page. They are exported as AUTHENTICATION_CALLBACK_ERRORS.

Not supported

  • Unity: Unity Player Accounts signs players in to Unity games, not to websites; Unity offers no OAuth or OpenID Connect sign-in for other apps.
  • Nintendo and PlayStation Network: neither offers a public sign-in for third-party websites.

Providers are one file each in this plugin, so another provider is easy to add once a platform offers web sign-in.

Error codes

Exported as AUTHENTICATION_ERROR_CODES from both entry points:

CodeStatusWhen
EMAIL_DOMAIN_RESERVED400Signing up with, or changing an email to, a placeholder domain

Options

Prop

Type

Provider options

Every provider accepts these, like better-auth's built-in providers:

Prop

Type

On this page