What you need before writing code
Choose the providers your audience already uses, decide where users should return after authentication, and make sure your application has a backend or serverless function. The backend is essential because a browser must never hold the secret used to retrieve a verified identity.
- A short tenant identifier for your application
- A server-side API key stored as an environment variable
- A return page that can handle a completed, pending or failed login
- A user record and application-session strategy that remain under your control
1. Start the provider login in the browser
When a user clicks a provider button, create a unique session ID and send the browser to the broker initiation URL. Login Broker supports google, github, apple, facebook, linkedin and microsoft as lowercase provider names.
Redirect mode is the most predictable choice for mobile browsers and strict popup policies. Popup mode can keep the original page in place, but it needs careful handling when the window closes before verification finishes.
2. Treat the returning session ID as untrusted
After the provider returns, the page receives a session ID and status. Neither proves who signed in. A session ID is a reference to an authentication attempt, not a credential and not a user identity.
If the result is still pending, poll the public status endpoint. That endpoint intentionally exposes only pending, completed or failed. It does not return the email address.
3. Verify on your server
Send the session ID to your own backend. Your backend then calls the protected result endpoint with the X-LoginBroker-ApiKey header. Accept the login only when the request succeeds, the status is completed, the tenant matches and a non-empty email is present.
Create your own application session only after those checks. Keep the Login Broker API key on the server, never in JavaScript delivered to the browser, a mobile binary or a public repository.
4. Handle expiry and failure deliberately
Login Broker sessions expire ten minutes after creation. Your UI should stop polling, clear its pending state and offer another attempt when a login fails or expires. Disable overlapping verification requests so a popup-close event and a status update cannot finish the same attempt twice.
The shortest safe checklist
A secure social-login integration is small when each boundary has one job. The browser initiates, the provider authenticates, the broker normalizes the result, and your backend decides whether to create a local session.
- Generate a fresh session ID per attempt
- Use HTTPS and URL-encode all path and return values
- Keep the API key server-side
- Match the returned tenant and completed status
- Use the verified email to find or create your own user
- Rotate the API key immediately if it is exposed