Facebook Sign In

Mushu supports Facebook as an identity provider using the OAuth 2.0 web flow. Users authenticate with Facebook and Mushu creates a session with JWT tokens.

How It Works

1. Your app redirects to Mushu's Facebook authorize endpoint
2. Mushu redirects to Facebook's OAuth consent screen
3. User authenticates and grants permissions
4. Facebook redirects back to Mushu's callback
5. Mushu exchanges the code for a token, fetches the user's profile, creates a session
6. Mushu redirects to your app with JWT tokens

Setup

1. Create a Facebook App

Go to Meta for Developers and create a new app (or use an existing one). You'll need:

• App ID — displayed on the app dashboard
• App Secret — under Settings > Basic

Under Facebook Login > Settings, add your callback URL:

https://auth.mushucorp.com/auth/facebook/callback

2. Register with Mushu

Configure Facebook as an auth provider for your app:

POST /apps/{'{app_id}'}/auth-providers
Authorization: Bearer YOUR_TOKEN
Content-Type: application/json

{'{'}
  "provider_type": "facebook",
  "facebook_app_id": "YOUR_FB_APP_ID",
  "facebook_app_secret": "YOUR_FB_APP_SECRET",
  "facebook_scopes": ["email", "public_profile"]
{'}'}

The app secret is stored securely in AWS Secrets Manager and never returned in API responses.

3. Configure Scopes

Default scopes are email and public_profile. To request additional permissions (e.g., for Facebook Ads), add them to facebook_scopes:

{'{'}
  "facebook_scopes": ["email", "public_profile", "ads_read", "ads_management"]
{'}'}

Web OAuth Flow

Start the Flow

Redirect the user to the authorize endpoint:

GET /auth/facebook/authorize?redirect_uri=https://yourapp.com/auth/callback&app_id=app_xxxxxxxx

Parameter	Required	Description
redirect_uri	Yes	Where to send tokens after auth completes
app_id	Yes	Your Mushu app ID

Handle the Callback

After Facebook authentication, Mushu redirects to your redirect_uri with tokens. The delivery method depends on the redirect type:

Redirect Type	Token Delivery	Example
Localhost (CLI/dev)	Query parameters	http://localhost:8080/callback?access_token=...&refresh_token=...
Web (production)	URL fragment	https://yourapp.com/callback#access_token=...&refresh_token=...

Example: Reading Tokens in JavaScript

// On your callback page
const hash = window.location.hash.substring(1);
const params = new URLSearchParams(hash);

const accessToken = params.get('access_token');
const refreshToken = params.get('refresh_token');

if (accessToken) {
  // Store tokens securely
  sessionStorage.setItem('access_token', accessToken);
  sessionStorage.setItem('refresh_token', refreshToken);

  // Redirect to app
  window.location.href = '/dashboard';
}

Token Format

Mushu issues standard JWT tokens. The access token contains:

{'{'}
  "sub": "user_abc123",
  "user_type": "facebook",
  "app_id": "app_xxxxxxxx",
  "iss": "auth.mushucorp.com",
  "exp": 1706000000,
  "iat": 1705996400
{'}'}

Claim	Description
sub	Mushu user ID
user_type	facebook
app_id	Your app ID
iss	Token issuer
exp	Expiry timestamp (1 hour from issue)

Differences from Apple and Google

	Apple	Google	Facebook
app_id required	Optional (has fallback)	Yes	Yes
Native mobile SDK	ASAuthorizationController	Google Sign-In SDK	Not supported (web only)
Lifecycle events	S2S notifications	RISC events	None
Credentials needed	Team ID, Key ID, private key	Client ID, client secret	App ID, app secret
Default scopes	name, email	openid, email, profile	email, public_profile

Facebook Sign In + Connections

Facebook Sign In and Connections serve different purposes:

	Facebook Sign In	Facebook Connection
Purpose	Authenticate a user (create session)	Link a Facebook account for API access
Result	Mushu JWT tokens	Stored Facebook access token
Use case	User logs into your app	Your app calls Facebook APIs (e.g., Ads)
Token owner	Mushu (session management)	Your org or user (retrieved via /token)

You can use both: a user signs in with Facebook (authentication), then connects their Facebook Ad account (connection) so your app can manage their ads.

Troubleshooting

Error: "Facebook provider not configured"

Register Facebook as an auth provider for your app. See Setup above.

Error: "Invalid redirect_uri"

The redirect_uri must be an allowed URL. Localhost URLs are allowed for development. For production, the domain must be registered.

Error: "Token exchange error"

Usually means the Facebook App Secret is wrong, or the callback URL in your Facebook app settings doesn't match. Verify both in the Meta Developer Dashboard.

Users see limited permissions

Extended permissions (beyond email and public_profile) require Meta's App Review. Until approved, only app developers and test users can grant extended permissions.