Get your Facebook credentials
To use Facebook sign in, you need a client ID and client Secret. You can get them from the Facebook Developer Portal. Select your app, navigate to App Settings > Basic, locate the following:
- App ID: This is your
client_id - App Secret: This is your
client_secret.
Avoid exposing the client_secret in client-side code (e.g., frontend apps) because it’s sensitive information.
Make sure to set the redirect URL to http://localhost:3000/api/auth/callback/facebook for local development. For production, you should set it to the URL of your application. If you change the base path of the auth routes, you should update the redirect URL accordingly.
Configure the provider
To configure the provider, you need to import the provider and pass it to the social_providers option of the auth instance.
require "better_auth"
auth = BetterAuth.auth(
secret: ENV.fetch("BETTER_AUTH_SECRET"),
base_url: ENV.fetch("BETTER_AUTH_URL", "http://localhost:3000"),
social_providers: {
facebook: BetterAuth::SocialProviders.facebook(
client_id: ENV.fetch("FACEBOOK_CLIENT_ID"),
client_secret: ENV.fetch("FACEBOOK_CLIENT_SECRET")
)
}
)BetterAuth also supports Facebook Login for Business, all you need
to do is provide the configId as listed in Facebook Login For Business > Configurations alongside your client_id and client_secret. Note that the app must be a Business app and, since BetterAuth expects to have an email address and account id, the configuration must be of the "User access token" type. "System-user access token" is not supported.
Facebook may omit email even when the permission is granted (phone-only accounts, revoked consent, or addresses Meta has marked invalid). See Handling Providers Without Email for the recommended map_profile_to_user fallback.
Sign In with Facebook
To sign in with Facebook, call auth.api.sign_in_social on your Ruby auth instance. The endpoint body takes the following properties:
provider: The provider to use. It should be set tofacebook.
response = auth.api.sign_in_social(
body: {
provider: "facebook",
callback_url: "/dashboard",
error_callback_url: "/login",
disable_redirect: true
}
)
redirect_url = response.fetch(:url)Additional Configuration
Scopes
By default, Facebook provides basic user information. If you need additional permissions, you can specify scopes in your auth configuration:
require "better_auth"
auth = BetterAuth.auth(
secret: ENV.fetch("BETTER_AUTH_SECRET"),
base_url: ENV.fetch("BETTER_AUTH_URL", "http://localhost:3000"),
social_providers: {
facebook: BetterAuth::SocialProviders.facebook(
client_id: ENV.fetch("FACEBOOK_CLIENT_ID"),
client_secret: ENV.fetch("FACEBOOK_CLIENT_SECRET")
)
}
)Additional options:
scopes: Access basic account information (overwrites).- Default:
"email", "public_profile"
- Default:
fields: Extend list of fields to retrieve from the Facebook user profile (assignment).- Default:
"id", "name", "email", "picture"
- Default:
Sign In with Facebook With ID or Access Token
To sign in with Facebook using the ID Token, you can use the auth.api.sign_in_social function to pass the ID Token.
This is useful when you have the ID Token from Facebook on your app and want to use it to sign in on the server.
If ID token is provided no redirection will happen, and the user will be signed in directly.
For limited login, you need to pass id_token.token, for only access_token you need to pass id_token.access_token and id_token.token together because of #1183.
result = auth.api.sign_in_social(
body: {
provider: "facebook",
id_token: {
token: facebook_id_token,
access_token: facebook_access_token
}
}
)
user = result.fetch(:user)For a complete list of available permissions, refer to the Permissions Reference.