omnisense/omniauth

Installation

composer require omnisense/omniauth                       # password, link, code by e-mail, backup codes, trusted devices, identity providers
composer require omniauth/otp omniauth/webauthn omniauth/google   # an authenticator application, passkeys, Google: one package each

Requirements

• PHP 8.2 or later.
• omnisense/omniauth requires psr/cache (^2.0 or ^3.0), psr/simple-cache (^2.0 or ^3.0), psr/clock (^1.0), psr/event-dispatcher (^1.0) and symfony/password-hasher (^6.4, ^7.0 or ^8.0), a component that loads no framework. Nothing else: no ORM, no HTTP client, no OAuth library.
• It suggests league/oauth2-client (Omniauth\OAuth\Provider\LeagueProvider: the provider packages require it), symfony/cache (a PSR-6 pool or PSR-16 cache for CacheThrottle in plain PHP), phpunit/phpunit (the providers' conformance suite) and omnisense/omnibridge (the hosts' contracts, among them Omnibridge\Contract\Tokens for a form's CSRF token).
• omniauth/otp adds ext-sodium, spomky-labs/otphp and paragonie/constant_time_encoding; omniauth/webauthn adds ext-openssl, web-auth/webauthn-lib, symfony/serializer and symfony/uid; omniauth/google adds league/oauth2-client and league/oauth2-google (Guzzle through them).

Plain PHP

No framework, no ORM: the accounts and their proofs stay in your tables, behind small store contracts (The contracts). The whole thing by hand - the in-memory stores of Omniauth\Testing stand in for yours:

<?php

require 'vendor/autoload.php';

use Omniauth\ArrayState;
use Omniauth\BackupCode\BackupCodeMethod;
use Omniauth\CacheThrottle;
use Omniauth\Context;
use Omniauth\EmailCode\EmailCodeMethod;
use Omniauth\Link\LinkMethod;
use Omniauth\Method\Methods;
use Omniauth\Omniauth;
use Omniauth\Password\PasswordMethod;
use Omniauth\Testing\ArrayCache;
use Omniauth\Testing\InMemoryStore;
use Omniauth\Testing\RecordingSender;
use Omniauth\Testing\TestAccount;
use Omniauth\TrustedDevice\TrustedDevices;
use Symfony\Component\PasswordHasher\Hasher\NativePasswordHasher;

$secret = 'the-application-secret-32-bytes-at-least';     // Symfony's kernel.secret, Laravel's APP_KEY...
$hasher = new NativePasswordHasher();                      // bcrypt, cost 13: Symfony's "auto"

// Your stores: here one account with a password and the code by e-mail.
$store = new InMemoryStore(new TestAccount('42', 'ringo', 'ringo@example.org', $hasher->hash('yellow-submarine'), emailCodeEnabled: true));
$sender = new RecordingSender();                           // yours sends an e-mail

$session = [];                                             // $_SESSION, in a real page: ArrayState::session()
$omniauth = new Omniauth(
    accounts: $store,
    methods: new Methods([
        new PasswordMethod($store, $store, $hasher),
        new LinkMethod($store, $store, $sender),
        new EmailCodeMethod($store, $store->emailCodes(), $sender, $secret),
        new BackupCodeMethod($store),
        new TrustedDevices($store, $store, $secret),
    ]),
    state: new ArrayState($session),
    throttle: new CacheThrottle(new ArrayCache()),         // any PSR-6 pool or PSR-16 cache
);

// What your page knows of the request.
$context = new Context(origin: 'https://example.org', host: 'example.org', ip: '203.0.113.7', trustedDevice: $_COOKIE['trusted_device'] ?? null);

$result = $omniauth->verify('password', $context, ['identifier' => 'ringo@example.org', 'password' => 'yellow-submarine']);
echo $result->status->value, ': ', implode(', ', array_map(fn ($f) => $f->value, $result->offered)), "\n";
// second-factor-required: email-code

$omniauth->begin('email-code', $context);                  // the code goes out
$code = $sender->last()->secret;                           // what the person reads in the mail

$result = $omniauth->verify('email-code', $context, ['code' => $code, 'trust' => true]);
echo $result->status->value, ' as ', $result->account->identifier, ' by ', implode(' + ', array_map(fn ($f) => $f->value, $result->passed)), "\n";
// authenticated as ringo by password + email-code

echo $result->trustDevice ? "trusted_device cookie to set\n" : '';
// setcookie('trusted_device', $result->trustDevice, ...): next time, no code

What your page does with the result is the host's part: Authenticated - renew the session id (session_regenerate_id(true)) and keep the account's handle in the session; set a remember-me when $result->remember; set the trusted_device cookie when $result->trustDevice is given. SecondFactorRequired - show the second-factor page with $result->offered. Failed - translate $result->failure (a stable key: bad-credentials, throttled, account-refused...). Check your form's CSRF token before calling (Omnibridge\Contract\Tokens under a bridged host).

docker/harness/bin/bare is a whole script of the same, every method in turn; Tests/DocsTest runs the block above as it is written here.

Run in the harness on 2026-10-25 (PHP 8.4), the script prints:

second-factor-required: email-code
authenticated as ringo by password + email-code
trusted_device cookie to set

The pieces:

• the methods, one per factor, each over the stores it reads (PasswordMethod over Passwords, EmailCodeMethod over EmailCodes and a Sender...), mounted in a Method\Methods;
• the conductor, Omniauth, over the accounts, the methods, the visitor's State (here an array; the session under a framework) and optionally a Throttle, a PSR-14 dispatcher, a PSR-20 clock and a second-factor rule (by default EnrolledSecondFactors);
• a Context per request (origin, host, address, browser, the trusted_device cookie, the firewall's name) and the proof the visitor sent, as an array.

The same script with Google in place of the password is the identity providers page's; with an authenticator application, omniauth/otp's installation page; with a passkey, omniauth/webauthn's.

In a framework

• Symfony: omnibridge/symfony's OmnibridgeBundle registers omniauth's extension where omniauth is installed; config/packages/omniauth.yaml turns each method on, and one authenticator, Omnibridge\Symfony\Auth\OmniauthAuthenticator, signs in by all of them: Symfony.
• Laravel: omnibridge/laravel's Auth\AuthServiceProvider, on with config/omnibridge.php's 'auth' => true; config/omniauth.php takes the same keys as omniauth.yaml, and the guard driver omniauth signs in: Laravel.
• Any other host: build the conductor once per request (or once per worker, with a State that reads the current request's session), as the script above does, and answer its Result as described above.

Symfony and Laravel

omniauth is the same under every host; the bridges live in omnibridge (Marco's decision QA8), where omniauth is only suggested:

• omnibridge/symfony (Omnibridge\Symfony\Auth\, step AU6): one authenticator per firewall over Omniauth::verify(), the "second factor in progress" token answering IS_AUTHENTICATED_2FA_IN_PROGRESS (scheb/2fa's name, so access_control does not change), the ceremonies' routes at the paths and under the names scheb/2fa, web-auth/webauthn-symfony-bundle and hwi/oauth-bundle had, the session as State, omniauth's CacheThrottle on a cache pool as Throttle, the hasher security.yaml sets for the user class: Symfony.
• omnibridge/laravel (Omnibridge\Laravel\Auth\, step AU8): a guard and a user provider (driver omniauth) over the same conductor, the same addresses and route names, the session as State, CacheThrottle on a Laravel cache store, the gate answering Security's attributes (ROLE_*, IS_AUTHENTICATED_FULLY...): Laravel.

Both read the same keys - config/packages/omniauth.yaml under Symfony, config/omniauth.php under Laravel - so a site and its twin on one database say the same thing once each. What two hosts of one database must share for a visitor to cross from one to the other:

A host that is neither mounts omniauth by hand, as the installation shows: the conductor over its session, its answers to the Result.

Symfony

omniauth runs without a framework (Installation); in a Symfony application, omnibridge/symfony (Omnibridge\Symfony\Auth\) does the wiring: the conductor and its methods from config/packages/omniauth.yaml, one authenticator for every way in, the second factor's token, voter, trust resolver and gate, the ceremonies' routes and their controller. This page describes omnibridge/symfony's Auth\ namespace at its 1.x branch.

Registering

composer require omnisense/omniauth omnibridge/symfony

Omnibridge\Symfony\OmnibridgeBundle (omnibridge/symfony's bundle) registers omniauth's container extension, Omnibridge\Symfony\Auth\DependencyInjection\OmniauthExtension (alias omniauth), when the class Omniauth\Omniauth exists; an application's own bundle can do the same with OmniauthExtension::register($container) (omnibase's BaseBundle does). Without an omniauth.yaml, or with one that holds no key, the extension loads nothing: no service, no route.

# config/packages/security.yaml
security:
    firewalls:
        main:
            custom_authenticators: [Omnibridge\Symfony\Auth\OmniauthAuthenticator]
            entry_point: Omnibridge\Symfony\Auth\OmniauthAuthenticator   # optional: start() sends to login_route
            remember_me: { secret: '%kernel.secret%' }                   # Security's own, used when omniauth says "remember"
            logout: { path: security_logout }
    access_control:
        - { path: ^/login/2fa, roles: IS_AUTHENTICATED_2FA_IN_PROGRESS }

# config/routes/omniauth.yaml
omniauth: { resource: ., type: omniauth }

# config/packages/omniauth.yaml - each key turns its method on
omniauth:
    password: { routes: [security_login] }
    link: { route: security_loginWithToken }        # 15 minutes, once, hashed
    email_code: ~
    backup_codes: ~
    trusted_device: ~                                # scheb/2fa's cookie and tokens
    totp: { secret_key: '%env(OMNIAUTH_TOTP_KEY)%' } # omniauth/otp; the secrets sealed at rest
    passkey: { rp_id: '%env(RELYING_PARTY_ID)%' }    # omniauth/webauthn
    oauth:
        providers:
            google: { client_id: '%env(GOOGLE_CLIENT_ID)%', client_secret: '%env(GOOGLE_CLIENT_SECRET)%' }   # omniauth/google

A method whose package is missing cannot be turned on: totp without omniauth/otp, passkey without omniauth/webauthn, oauth without Omniauth\OAuth\OAuthMethod stop the container's compilation with a LogicException naming the package to require (omniauth.yaml turns "totp" on, which needs omniauth/otp: composer require omniauth/otp.).

The configuration tree

password and throttle are on unless set to false (canBeDisabled); link, email_code, backup_codes, trusted_device, totp, passkey and oauth are off unless their key is present (canBeEnabled: ~ turns one on with its defaults). The defaults below were read by resolving the tree with Symfony's Config Processor in omnibridge/symfony's image on 2026-10-25.

Services

The stores are the application's: each contract's service by its own name, or the id stores names (omnibase binds its Base\Auth\ stores). The clock is the container's clock service when it has one. omniauth's events go to Symfony's event_dispatcher: listen to Omniauth\Event\SignedIn (and the others, Events) as to any event.

A class of the application that implements Omniauth\OAuth\Provider\ProviderFactory is autoconfigured with the tag omniauth.oauth_provider_factory and makes the entries of its kind.

The bridge registers no console command and no Twig function.

The authenticator

OmniauthAuthenticator knows a sign-in by its route (the router runs before the firewall):

What it answers:

• Authenticated: a self-validating passport for the account (it must be a Symfony UserInterface), Security's RememberMeBadge enabled when Result::$remember, the trusted_device cookie when omniauth gave one (path /, HTTP only, SameSite=Lax, secure when the request is, for trusted_device.lifetime); a redirect to the posted _target_path when it is an address of this site, else the firewall's saved target path, else default_target_path; a passkey gets {"status": "ok", "errorMessage": ""}.
• SecondFactorRequired: a PendingToken (below) and a redirect to second_factor.form_route; a passkey gets the JSON with redirect.
• Failed and IdentityUnknown: a SignInRefused (a CustomUserMessageAuthenticationException carrying the factor, omniauth's failure and reason, and the identity). The password goes back to its own route, the others to login_route, the error in _security.last_error; a passkey gets {"status": "failed", "errorMessage": ...} with HTTP 401; a refused link empties the route's parameter and lets the page behind answer as for no link; a refused second factor goes back to its page with the error, or to login_route when the attempt is gone (expired, no-attempt); an unknown identity is kept in the session (omnibridge.auth.pending_identity) and goes to oauth.sign_up_route when one is set.

Every passport carries an OmniauthBadge (the Result): a listener of Security's own events (CheckPassportEvent, LoginSuccessEvent, LoginFailureEvent) that does what an omniauth listener does skips a passport that carries it.

The session keys it uses: _security.last_username (the identifier typed), _security.last_error, omnibridge.auth.factor (the second factor chosen), omnibridge.auth.second_factor_error, omnibridge.auth.pending_identity (an array: provider, subject, email, emailVerified, name), and omniauth's own omniauth.attempt and omniauth.enrolment.<factor>.

Messages

A failure's message is looked up as <failure>:<reason>, then <failure>, in messages over these defaults (Security's own message keys, which its translations already have):

omniauth:
    messages:
        'account-refused:banned': 'security.banned'
        'refused': 'security.refused.%reason%'

The routes

omniauth: { resource: ., type: omniauth } imports, under the names and at the addresses configured:

The sign-in page itself, the link's page and the sign-out are the application's routes (login_route, link.route, the firewall's logout).

The second factor's page renders second_factor.template (TwigBundle required) with the variables scheb/2fa's FormController gave it, so a template written for scheb/2fa renders unchanged: twoFactorProvider (totp, email for omniauth's email-code, backup-code), availableTwoFactorProviders, authenticationError, authenticationErrorData, displayTrustedOption (true when trusted devices are on), authCodeParameterName, trustedParameterName, isCsrfProtectionEnabled, csrfParameterName, csrfTokenId, checkPathRoute, checkPathUrl, logoutPath; ?preferProvider=email picks the factor shown. The code by e-mail is sent when its page is first shown, and again once it has expired. The page is answered with Cache-Control: no-store.

Between two factors

• PendingToken: the token of a visitor whose first factor passed. It carries no role, is never "fully" signed in (PendingTrustResolver refuses IS_AUTHENTICATED_FULLY to it) and lists the factors offered (offered()).
• PendingVoter grants IS_AUTHENTICATED_2FA_IN_PROGRESS to that token alone: neither a visitor signed out nor one signed in opens the second factor's page.
• SecondFactorGate sends that visitor to the second factor's page from any other page, after the firewall (priority 7 on kernel.request) and when Security refused a page (kernel.exception, priority 2) - but the page and its check, a page access_control opens to everybody (PUBLIC_ACCESS) or to that token, and the sign-out.

Laravel

omnibridge/laravel (Omnibridge\Laravel\Auth\, step AU8) wires omniauth under Laravel as omnibridge/symfony wires it under Symfony, from config/omniauth.php - the same keys as omniauth.yaml, so a site and its Laravel twin say the same thing - plus what Laravel needs of its own: a guard and a user provider, the gate's answers to Security's attributes, the sign-in pages, the sign-out and a signed remember-me cookie. This page describes omnibridge/laravel's Auth\ namespace at its 1.x branch.

Turning it on

composer require omnisense/omniauth omnibridge/laravel
php artisan vendor:publish --tag=omniauth-config      # config/omniauth.php, to edit

// config/omnibridge.php
'auth' => true,

// config/auth.php
'guards' => ['web' => ['driver' => 'omniauth', 'provider' => 'omnibase']],
'providers' => ['omnibase' => ['driver' => 'omniauth']],

OmnibridgeServiceProvider registers Auth\AuthServiceProvider when the class Omniauth\Omniauth exists; the provider wires nothing at boot unless omnibridge.auth is on (true; false or null is off, the default). The controllers read the default guard, which must be the omniauth one (LogicException otherwise).

config/omniauth.php

Each method's key turns it on; null (or false) turns it off. The defaults are those the provider fills in (Auth\Settings), the same as omniauth.yaml's where both have the key.

Bindings

At boot the provider also: registers the guard driver and the user provider driver omniauth; answers Security's attributes from the gate (Gate::before, Auth\Roles); leaves the trusted_device and remember-me cookies out of EncryptCookies (the Symfony site writes and reads them plain); appends Middleware\SecondFactorPending to the web group, before the auth middleware; registers the routes; and, with omnibase's stores, its sign-in listeners.

Routes

In the web group, without Laravel's CSRF middleware (the forms' tokens are checked by the bridge through the Tokens contract, with Security's field names):

The link routes exist with link on, the passkey routes with passkey, the password route with password. Controllers\SignIn answers the Result as omnibridge/symfony's authenticator does (the same redirects, the same JSON for a passkey, the same session-kept identity for the sign-up), with a Refusal (message key and data, factor, failure, reason) kept in the session under omnibridge.auth.last_error for the page that follows. The second factor's page receives the same variables as under Symfony, so the Symfony site's template renders unchanged. Pages are rendered through the bound Base\Screen\Negotiation and answered with Cache-Control: no-store, private.

The guard

Auth\OmniauthGuard (a StatefulGuard) keeps the account's handle in the session (omnibridge.auth.handle) and reads the account back through omniauth's Accounts at each request, wrapped as Auth\AccountUser (the handle as its identifier, the account's getRoles() as its roles; a method the wrapper has not is the account's). Omnibridge\Contract\Access::getUser(), the screens' viewer and Twig's app.user unwrap it: the application sees its own object.

Auth\OmniauthUserProvider (driver omniauth) finds accounts by handle or by identifier and checks a password with the same hasher as PasswordMethod (a password longer than 72 bytes verifies as under Symfony); it keeps no remember token.

The remember-me cookie (Auth\RememberMe) is base64url(handle):expiry:signature, the signature an HMAC-SHA256 under secret of the account's class, handle, expiry, password hash and address (Security's signature_properties): a new password or a new address forgets every browser. No token is stored.

Auth\Roles answers the gate: PUBLIC_ACCESS and IS_AUTHENTICATED_ANONYMOUSLY to everybody, IS_AUTHENTICATED and IS_AUTHENTICATED_REMEMBERED to an account signed in, IS_AUTHENTICATED_FULLY to one not signed in by its remember-me cookie, IS_AUTHENTICATED_2FA_IN_PROGRESS to the visitor between two factors, IS_IMPERSONATOR and IS_REMEMBERED to nobody, ROLE_* to an account that holds it or a role above it in role_hierarchy; any other ability is left to the gate's own definitions.

Middleware\SecondFactorPending sends a visitor between two factors to the second factor's page from any route but the page, its check, the sign-out's two routes and second_factor.open_routes.

With omnibase

With stores: 'omnibase' and omnisense/omnibase 4.x, Auth\OmnibaseEffects registers what a sign-in does around omniauth under Symfony, with the same omnibase classes: the browsers an account signs in from (Base\Security\ConnectionTracker), the new device warned of, the captcha after failed sign-ins from an address (Base\Security\SignInCaptcha, its gateway config/omnishield.php's, counted in captcha.pool), "welcome back" to a disabled account, the sign-in e-mails written by Base\Notifier\Mail\SignInMails and sent by Laravel's mailer (mail), omnibase's NotifierSender as omniauth's Sender, and Middleware\EnrolmentPrompt (the second factor's enrolment an account is sent to). Without omnibase 4.x but with its stores, the listeners Base\Auth\Listener\UpdateAccount and Auth\Listener\WelcomeFlash (the word of welcome) listen to Omniauth\Event\SignedIn.

Concepts

A sign-in is an attempt: one visitor, the factors passed so far, the second factors still offered, what a ceremony keeps between its two steps. The conductor runs each step against the method of a factor and answers with a result; the host keeps the attempt between two requests (Contract\State) and reads the result to answer the visitor. The interfaces the application and the host fill in are the contracts.

The conductor

use Omniauth\Omniauth;

$omniauth = new Omniauth(
    accounts: $accounts,       // Contract\Accounts
    methods: $methods,         // Method\Methods: the methods mounted, one per factor
    state: $state,             // Contract\State: the session, or ArrayState
    policy: null,              // Contract\SecondFactorPolicy; null: new EnrolledSecondFactors($methods)
    throttle: null,            // Contract\Throttle; null: no limit
    events: null,              // PSR-14 EventDispatcherInterface; null: no event
    clock: null,               // PSR-20 ClockInterface; null: SystemClock
    lifetime: Omniauth::LIFETIME,   // seconds an attempt lasts: 600
);

A factor is given as the enum or as its value ('email-code'); a value that is no factor throws PHP's \ValueError, a factor no method was mounted for Exception\UnknownMethod (Errors).

What verify() does

The same sequence whatever the method - that single sequence is what makes the behaviour the same under every host:

1. A first factor starts a new attempt (keeping what a ceremony kept: a challenge begun before it). A second factor goes on with the attempt in progress: none, or one older than the lifetime, fails with no-attempt or expired; a factor the attempt did not offer fails with not-offered.
2. The throttle: scope the factor's value (password, email-code...), key what was typed and the visitor's address for a first factor (ringo@example.org|203.0.113.7, lower case), the account for a second one (account:<handle>, whatever the address). Refused: throttled, and nothing is checked.
3. Event\Verifying: a listener may refuse (refused, with its reason).
4. The method checks the proof and gives a Method\Verdict. A provider's identity that no account is linked to ends the attempt with IdentityUnknown; a refusal keeps the attempt and fails with the method's failure (bad-credentials when it gave none) and reason.
5. Accounts::check(): an account that may not sign in now ends the attempt with account-refused and its reason (Event\AccountRefused is dispatched).
6. The throttle is reset for that scope and key; the factor is marked passed; "remember me" is kept when a first factor's proof asked it (remember) or the method asked it (the sign-in link).
7. The second-factor rule says what remains (The second-factor rule). When something does, each ambient method (the trusted device) is tried on the way; if one passes, the rule is asked again. Still due: SecondFactorRequired with the factors offered, the attempt kept, Event\SecondFactorRequired.
8. Done: Authenticated, the attempt cleared, Event\SignedIn; after a second factor whose proof asked trust, the first ambient method's new cookie value in Result::$trustDevice.

Every failure dispatches Event\SignInFailed (the factor, the failure, the context, the identifier typed, the account when known, the reason - never the secret).

begin() follows the first steps of the same sequence: a first factor restarts the attempt, a second one needs the attempt in progress and a factor it offered; the throttle's scope is <factor>.begin (link.begin, email-code.begin: what sends something), keyed by the address typed alone for a first factor (identifier:ringo@example.org, lower case: what is sent goes to that address, whichever network asks), as a verification is otherwise; Event\Beginning may refuse; the method's challenge is returned and the attempt saved. A method that is not Challenging has nothing to begin: LogicException.

Enrolment

$enrolment = $omniauth->enrol('email-code', $account);    // LogicException for a method that is not Enrolling
$challenge = $enrolment->begin($context);                 // a code sent, a secret and its address, options to sign, or nothing
$enrolled = $enrolment->confirm($context, ['code' => '481516']);
$enrolled->isDone();                                      // true, or $enrolled->failure and ->reason
$enrolled->secrets;                                       // what to show once (backup codes)

An enrolment has an attempt of its own (omniauth.enrolment.<factor>), the account identified, apart from any sign-in. begin() starts it over (a code sent again has its own ten minutes) and is throttled as <factor>.begin; confirm() is throttled as <factor>, keyed by the account. Once done: the enrolment is forgotten, the throttle reset, Event\CredentialAdded dispatched - and a new password makes every trusted browser fall back to the second factor.

revoke() dispatches Event\Revoking (a listener may refuse: Enrolled::failed(Failure::Refused, $reason)), turns the factor off, makes the trusted devices fall back unless the factor revoked is the trusted device itself (which forgets every browser), and dispatches Event\CredentialRemoved. A method that is not Revocable (the password, the link, a passkey, an identity provider) throws a LogicException.

The attempt

Omniauth\Attempt is what State keeps between two requests, as an array of scalars:

[
    'started' => 1792497600,           // when it began (the clock's timestamp)
    'handle' => '42',                  // the account found by the first factor (Accounts::handle()), or null
    'passed' => ['password'],          // the factors passed, in their order
    'offered' => ['email-code', 'backup-code'],
    'kept' => ['email-code' => 1792498200],   // what ceremonies keep (a deadline, a challenge, the OAuth state)
    'remember' => false,
]

It holds the account's handle, never the account: the conductor loads the account again (Accounts::byHandle()) each time it reads the attempt back, and an account gone since ends the attempt. Anything malformed in the state reads as no attempt.

identify(), pass(), offer() and remember() are the conductor's (@internal).

The result

Omniauth\Result, read-only:

isAuthenticated() and needsSecondFactor() read the status; Result::failed($failure, $reason, $account) builds a failure.

Status (Omniauth\Status, a string enum):

Failure (Omniauth\Failure): stable keys a page translates, never a message.

Factors

Omniauth\Factor names what a person proves, once for every method, policy and host: the key of routes, settings and translations.

Factor::of(Factor|string) gives the case (PHP's \ValueError for an unknown value); role() gives Role::First (it finds the account) or Role::Second (the account is known).

The request and the proof

Omniauth\Context, read-only - what the host knows of the request, with no object of its framework:

Omniauth\Proof wraps what the visitor sent, an array: ['identifier' => ..., 'password' => ...], ['code' => ...], ['token' => ...], a WebAuthn credential's JSON under json, an OAuth return's code and state. Two keys mean the same to every method: remember (at the first factor: the host sets its remember-me) and trust (at the second: a trusted-device cookie).

What a ceremony gives back

Method\Challenge, the answer of begin() and of an enrolment's begin():

Enrolled (failure, secrets, reason; isDone(), Enrolled::done($secrets), Enrolled::failed($failure, $reason)) is what setting a factor up, or turning it off, ended with.

Message (factor, secret, until) is what a method asks the host's Sender to send: the link's token or the code as secret - never logged, never stored as it is.

PendingIdentity (provider, subject, email, emailVerified, name) is someone a provider vouched for whom no account is linked to.

Method interfaces

A method checks a proof within an attempt and touches neither request nor response. Its interfaces, in Omniauth\Method\ - what the conductor asks of it:

Method\Verdict is what a method concluded: Verdict::passed($account, $remember), Verdict::refused($failure, $reason), Verdict::expired(), Verdict::unknown(PendingIdentity); hasPassed().

Method\Methods holds the methods mounted, one per factor (a second one for the same factor replaces the first): add(), has(), get() (throws UnknownMethod), secondFactors() (the SecondFactor methods that are not ambient), ambient(); iterable and countable. Writing a method of your own: Writing a method or a provider.

The contracts

omniauth decides who signs in; the application keeps its accounts and their proofs, the host its request, response, session and pages. Between them, small interfaces in Omniauth\Contract\.

The accounts

Accounts - an account is any object of the application, which implements nothing of omniauth:

check() is called after the proof passed, never before: an unknown address and a banned account are told apart only once the password is right.

The stores of each proof

One store per proof, so a site takes only what it serves:

No table, no ORM here: the structure stays the application's, described once, read by every host. Omniauth\Testing\InMemoryStore implements all of them but the passkeys over TestAccount objects (Testing).

The host's small duties

What stays the host's alone: its firewall or guard, reading the request and writing the response, the session cookie and its renewal at each sign-in (against session fixation), signing out, the remember-me, switching user, API tokens, and the pages with their forms.

ArrayState keeps a PHP array by reference (new ArrayState($array), or none for its own); ArrayState::session() binds it to $_SESSION and throws a LogicException when no session is started; all() gives what it holds.

The Throttle contract's docblock names Symfony's RateLimiterFactory and Laravel's RateLimiter as hosts' throttles; both bridges mount omniauth's CacheThrottle instead (on a cache pool, or a cache store). Either may implement the contract: one with an atomic store is exact under concurrent tries, CacheThrottle is not (Configuration).

Password

new PasswordMethod($accounts, $passwords, $hasher = null);   // null: NativePasswordHasher, bcrypt cost 13 - Symfony's "auto"
$omniauth->verify('password', $context, ['identifier' => 'ringo@example.org', 'password' => '...', 'remember' => true]);

Checked by symfony/password-hasher under every host, never by password_verify() alone: Symfony prehashes a password longer than 72 bytes (or holding a NUL byte) in SHA-512 and base64 before bcrypt, so password_verify() - and Laravel's Hash - would refuse those accounts. The same hasher says when to rehash: a hash of another cost is rewritten at sign-in (Passwords::update()), and a hash of the hasher's own cost is left as it is (Laravel's default of 12 would rehash every Symfony account on each sign-in).

Under Symfony, pass the hasher security.yaml builds (PasswordHasherFactory, "auto": a MigratingPasswordHasher); the hashes it wrote yesterday verify the same.

An unknown address and a wrong password get the same answer (bad-credentials) in the same time: an unknown account is checked against a hash of nothing. A banned account is refused (account-refused, with its reason) only once its password is right. Five tries a minute for an identifier from an address (CacheThrottle::LIMITS['password']).

A new password, from the settings: $omniauth->enrol('password', $account)->confirm($context, ['password' => 'new', 'current' => 'old']) - current is checked when it is given (leave it out for a reset by e-mail) - and every trusted browser falls back to the second factor.

What is checked

The account is found by Accounts::byIdentifier(): an address, a user name - what the store accepts. Accounts::check() runs after the password passed (the conductor's step), so a banned account answers account-refused only to whoever knows its password.

A password cannot be turned off through omniauth: revoke('password', $account) throws a LogicException (PasswordMethod is not Revocable).

Sign-in link

new LinkMethod($accounts, $linkTokens, $sender, $lifetime = 900, $clock = null);
$omniauth->begin('link', $context, ['identifier' => 'ringo@example.org']);   // Challenge "sent", whatever the address
$omniauth->verify('link', $context, ['token' => $tokenFromTheLink]);         // the link's page, a GET from a mailbox

By Marco's decision QA4 (2026-10-20):

• 15 minutes (LinkMethod::LIFETIME), once (LinkTokens::consume() uses it up);
• hashed: the token is 32 random bytes (base64url, 43 characters) sent to the account; the store keeps its SHA-256 (LinkMethod::hash()), so whoever reads the table cannot sign in with it;
• a new link at each request (the old "a link is still valid, nothing sent" is gone), 3 an hour (link.begin in CacheThrottle::LIMITS), counted per address typed (lower case), whichever network the requests come from;
• the same answer whether the address has an account or not, and nothing sent for one that has none.

The message (Message: the factor, the token as secret, until) goes to the host's Sender, which builds the address of its link page. A link signs in with the host's remember-me, as omnibase's did; it is a first factor like the password, so the second factor follows when the account has one.

The links issued before the switch were kept in clear: a store that still holds some also implements PlainLinkTokens, and they serve once, as they are, until their end.

The link's steps

The whole way, with the in-memory store (run in the harness on 2026-10-25):

<?php

require 'vendor/autoload.php';

use Omniauth\ArrayState;
use Omniauth\CacheThrottle;
use Omniauth\Context;
use Omniauth\Link\LinkMethod;
use Omniauth\Method\Methods;
use Omniauth\Omniauth;
use Omniauth\Testing\ArrayCache;
use Omniauth\Testing\InMemoryStore;
use Omniauth\Testing\RecordingSender;
use Omniauth\Testing\TestAccount;

$store = new InMemoryStore(new TestAccount('42', 'ringo', 'ringo@example.org'));
$sender = new RecordingSender();
$omniauth = new Omniauth($store, new Methods([new LinkMethod($store, $store, $sender)]), new ArrayState(), throttle: new CacheThrottle(new ArrayCache()));
$context = new Context(origin: 'https://example.org', host: 'example.org', ip: '203.0.113.7');

echo $omniauth->begin('link', $context, ['identifier' => 'nobody@example.org'])->kind, ', ', $sender->count(), " sent\n";
echo $omniauth->begin('link', $context, ['identifier' => 'ringo@example.org'])->kind, ', ', $sender->count(), " sent\n";
$token = $sender->last()->secret;                         // the link: https://example.org/login/token/<token>
echo strlen($token), ' characters, good for ', $sender->last()->until->getTimestamp() - time(), " seconds\n";

$result = $omniauth->verify('link', $context, ['token' => $token]);
echo $result->status->value, ' as ', $result->account->identifier, ', remember: ', var_export($result->remember, true), "\n";
echo $omniauth->verify('link', $context, ['token' => $token])->failure->value, " the second time\n";

foreach (range(1, 2) as $i) {
    $omniauth->begin('link', $context, ['identifier' => 'ringo@example.org']);
}
echo $omniauth->begin('link', $context, ['identifier' => 'ringo@example.org'])->failure?->value, " at the fourth link of the hour for one address\n";
echo $omniauth->begin('link', new Context(ip: '198.51.100.9'), ['identifier' => 'ringo@example.org'])->failure?->value, " from another network too\n";

sent, 0 sent
sent, 1 sent
43 characters, good for 900 seconds
authenticated as ringo, remember: true
invalid-link the second time
throttled at the fourth link of the hour for one address
throttled from another network too

Under Symfony the link's page is the application's route link.route (a GET with the token signs in through the authenticator); under Laravel the bridge's security_loginWithToken (/login/token/{token?}), whose POST sends the link (Symfony, Laravel).

Code by e-mail

new EmailCodeMethod($accounts, $emailCodes, $sender, $secret, $digits = 6, $lifetime = 600, $clock = null);
$omniauth->begin('email-code', $context);                       // the second-factor page, or "send again"
$omniauth->verify('email-code', $context, ['code' => '481516', 'trust' => true]);

A second factor: offered once a first factor passed for an account that turned it on (EmailCodes::enabled()). Six digits drawn as scheb/2fa draws them, good for 10 minutes and once.

By Marco's decision QA5 (2026-10-20) the code is kept hashed: an HMAC-SHA256 keyed by the host's secret and bound to the account (EmailCodeMethod::hash()), compared in constant time; the deadline is kept in the attempt. Five tries per account in 15 minutes, whatever the address (email-code), 3 codes sent in 15 minutes (email-code.begin).

Turning it on, from the settings: enrol('email-code', $account)->begin($context) sends a code, ->confirm($context, ['code' => ...]) checks it and turns the factor on. Off: revoke('email-code', $account) - the trusted browsers fall back with it.

The code's steps

enrolled() is EmailCodes::enabled(). The constructor refuses an empty secret and digits outside 4 to 9 (InvalidArgumentException). hash($account, $code) is hash_hmac('sha256', handle."\0".code, $secret): a host that sent a code under another secret (the Symfony site's kernel.secret and the twin's) must share it for the code to be good on both.

The code expires after $lifetime seconds, but the attempt that holds its deadline expires after the conductor's lifetime (600 seconds by default) whichever comes first.

Backup codes

new BackupCodeMethod($backupCodes, $count = 8);
$codes = $omniauth->enrol('backup-code', $account)->confirm($context)->secrets;   // show them once
$omniauth->verify('backup-code', $context, ['code' => 'A1B2C3-D4E5F6']);

Eight codes, A1B2C3-D4E5F6 as omnibase draws them, kept as password_hash() hashes - the very hashes omnibase's user.backupCodes holds, read as they are. Each serves once: the one that matches is removed. They stand in for another second factor and are offered after it; alone, they ask for none (as in scheb/2fa). A new set replaces the former; revoke('backup-code', $account) clears them.

The backup codes' steps

enrolled() is true while the account has at least one hash. Backup codes alone ask no second factor: the rule offers them after another second factor the account set up, and last (The second-factor rule). Each code costs one password_verify() (bcrypt) per hash tried: up to $count of them for a wrong code.

Trusted devices

new TrustedDevices($accounts, $trustedVersion, $secret, $lifetime = 2592000, $clock = null);
$result = $omniauth->verify('email-code', $context, ['code' => '...', 'trust' => true]);
setcookie(TrustedDevices::COOKIE, $result->trustDevice, ...);      // "trusted_device", 30 days
// next time: new Context(..., trustedDevice: $_COOKIE['trusted_device'] ?? null)

A second factor already passed on this browser. The conductor tries it by itself when a second factor is required (Method\Ambient): a valid token passes as Factor::TrustedDevice and no code is asked. After a second factor passed with trust, Result::$trustDevice is the cookie's new value.

scheb/2fa's format, byte for byte, so the browsers trusted before the switch stay trusted: JWTs signed HS256 with the host's secret (Symfony's kernel.secret), claims iat, exp (with their microseconds when they have some, as lcobucci/jwt writes them), usr (the account's Accounts::identifier()), fwl (Context::$firewall), vsn (the account's TrustedVersion), several tokens joined by ; - the other accounts' and firewalls' kept, this one's replaced, the invalid and expired dropped. Written with PHP's HMAC, with no JWT library; read as scheb reads them (signature, alg, iat <= now < exp). The key needs 32 bytes, as lcobucci/jwt requires.

A token counts while its version is the account's: turning a second factor off, setting a new password or revoke('trusted-device', $account) raises it, and every browser falls back.

The proof: Tests/TrustedDevicesTest compares omniauth's tokens with scheb's JwtTokenEncoder's for the same input (recorded, and live in the harness, where scheb/2fa is a development dependency), and each reads the other's.

The tokens' checks

TrustedDevices::COOKIE is trusted_device, TrustedDevices::LIFETIME 2592000 seconds (30 days). The constructor refuses a secret shorter than 32 bytes (InvalidArgumentException). The cookie itself - its name, path, flags and expiry - is the host's: the bridges set it on /, HTTP only, SameSite=Lax, secure on HTTPS, for the configured lifetime. Trusted devices are offered on the second factor's page as "trust this browser" when the method is mounted (displayTrustedOption); the proof's trust asks it.

Identity providers (OAuth 2, OpenID Connect)

composer require omnisense/omniauth omniauth/google

The mechanics every provider shares are omniauth's own, under Omniauth\OAuth\ (they were the package omniauth/oauth until 2026-10-23: same namespace, same class names); omniauth requires no OAuth library. Each provider is a package of its own - omniauth/google first, which brings league/oauth2-client and league/oauth2-google. No bundle, no framework: the links between your accounts and their providers stay in your table, behind omniauth's Contract\Identities (a provider, the person's identifier there - sub -, the account).

The whole thing by hand - the in-memory stores of Omniauth\Testing stand in for yours, and Omniauth\OAuth\Testing\FakeProvider for Google and the person consenting there:

<?php

require 'vendor/autoload.php';

use Omniauth\ArrayState;
use Omniauth\Context;
use Omniauth\Method\Methods;
use Omniauth\OAuth\NoSecondFactorLinking;
use Omniauth\OAuth\OAuthMethod;
use Omniauth\OAuth\Provider\Providers;
use Omniauth\OAuth\Testing\FakeProvider;
use Omniauth\Omniauth;
use Omniauth\Testing\InMemoryStore;
use Omniauth\Testing\TestAccount;

$store = new InMemoryStore($ringo = new TestAccount('42', 'ringo', 'ringo@example.org'));
// Yours: omniauth/google's new GoogleProvider($clientId, $clientSecret, '/login/google/callback')
$google = new FakeProvider('google', redirectUri: 'https://example.org/login/google/callback');

$session = [];                                             // $_SESSION, in a real page
$methods = new Methods();
$methods->add(new OAuthMethod($store, $store, new Providers($google), new NoSecondFactorLinking($methods)));
$omniauth = new Omniauth(accounts: $store, methods: $methods, state: new ArrayState($session));
$context = new Context(origin: 'https://example.org', host: 'example.org', ip: '203.0.113.7');

// /connect/google: the visitor is sent to the provider.
$challenge = $omniauth->begin('oauth', $context, ['provider' => 'google']);
// header('Location: '.$challenge->payload); the person consents; the browser comes back with ?code=…&state=…
$return = $google->consent($challenge->payload, ['sub' => '108204', 'email' => 'ringo@example.org', 'email_verified' => true]);

// /login/google/callback: the return's query, as it is.
$result = $omniauth->verify('oauth', $context, $return);
echo $result->status->value, ' as ', $result->account->identifier, ', linked to google ', $ringo->identities['google'], "\n";
// authenticated as ringo, linked to google 108204

// Someone no account knows: a result for the sign-up page, no account made.
$return = $google->consent($omniauth->begin('oauth', $context)->payload, ['sub' => '9001', 'email' => 'john@example.org', 'email_verified' => true]);
$result = $omniauth->verify('oauth', $context, $return);
echo $result->status->value, ': ', $result->identity->email, "\n";
// identity-unknown: john@example.org

What your pages do around it is the host's part: the start route redirects to $challenge->payload; the return route hands its query to verify() and, on Authenticated, renews its session id and keeps the account's handle; on SecondFactorRequired it shows the second-factor page (an account that has one passes it after Google too: Marco's decision QA2); on IdentityUnknown it keeps $result->identity in its session and shows its sign-up, then calls OAuthMethod::adopt($account, $identity) once the account exists; on a failure, the sign-in page with $result->reason translated.

Next: the method and its linking rule, then the providers, below.

The method

OAuthMethod is a first factor (Factor::OAuth), Challenging and Enrolling:

new OAuthMethod(
    accounts: $accounts,          // Omniauth\Contract\Accounts
    identities: $identities,      // Omniauth\Contract\Identities: provider + sub -> account
    providers: new Providers(new GoogleProvider($id, $secret, '/login/google/callback')),   // omniauth/google
    byEmail: new NoSecondFactorLinking($methods),   // true (any account, the default), false (never), or a rule
    clock: null,                  // PSR-20: Identities::used()'s date; null: SystemClock
);

providers() gives the Providers it serves (what the sign-in page lists: names()).

The trip

The state stops a return the visitor did not begin (login CSRF: an attacker's own code landed in the victim's browser). PKCE stops a code used in a trip it was not issued for (a code stolen from a log or a referrer, or injected with the victim's state): the provider refuses to exchange it with another trip's verifier. The nonce ties the ID token to the trip. What the attempt keeps lives as long as the attempt (ten minutes).

Who it is: the linking rule (QA3)

1. The account linked to the provider's subject (Identities::owner($provider, $sub)), whatever the address says now: Google's sub is the person's stable identifier there; an address can change hands.
2. Else, only when the provider says the address is verified (Google's email_verified), the account of that address (Accounts::byIdentifier(), then Accounts::email() compared, case aside: a user name that looks like the address is not it) - linked there and then (Identities::link()), unless:
   • byEmail refuses it: false never links by an address; NoSecondFactorLinking refuses an account that set up a second factor (Marco's QA3: never for an account with a second factor or an administration role - omnibase's own rule adds the roles, step AU4);
   • the account is linked to another subject of that provider already: an address does not move a link. Then: not-enrolled, reason link-from-settings - the person signs in otherwise and links the provider from the settings.
3. Else nobody: Status::IdentityUnknown, $result->identity (a PendingIdentity: provider, subject, address, whether it is verified, name). No account is created here - not even a transient one (lesringostars' hwi/oauth-bundle made one, and an address without an account ended in a 500 "User identifier is NULL"). The host shows its sign-up, prefilled; once the account exists, adopt($account, $identity) links it. Keep the identity in the session, never in a form field.

An address the provider does not vouch for is never looked up: an unverified address finds no account, and the sign-up knows it is not proved (emailVerified: false).

After it

The conductor does what it does after any first factor: Accounts::check() (banned, locked...), then the second-factor rule - an account that has a second factor passes it after Google (Marco's QA2: EnrolledSecondFactors::AFTER holds Factor::OAuth; lesringostars today signs in by Google without it).

From the settings

$enrolment = $omniauth->enrol(Factor::OAuth, $account);
$challenge = $enrolment->begin($context, ['provider' => 'google']);   // redirect
$enrolled = $enrolment->confirm($context, $return);                   // the return's query

The same trip, state and PKCE included, in the enrolment's own attempt (a sign-in in progress is not touched). The address does not matter there (the person is signed in); the subject is refused when another account holds it (linked-elsewhere), and an account keeps one identity per provider (other-identity). With one return address per provider, the host tells the two apart by whether the visitor is signed in: signed in, enrol()->confirm(); not, verify().

Refusals

bad-credentials with a stable reason: unknown-provider (at the beginning), state-mismatch, provider-denied (the person said no: error=access_denied), provider-error, missing-code, exchange-failed (the provider refused the code: used, expired, or not this trip's verifier), invalid-id-token, no-subject, hosted-domain, and from the settings linked-elsewhere, other-identity; not-enrolled / link-from-settings (above); expired when the attempt kept nothing. The provider's own message is for the server's log (ProviderError::getMessage()), not the page.

A link keeps what the provider said of the address at that moment (Identities::link()'s $email and $emailVerified), and every sign-in by an identity marks it used (Identities::used(), the method's clock). Turning a link off is the store's Identities::unlink($account, $provider), which the host's settings page calls; omnibase's store is Base\Auth\UserIdentities on its userIdentity table.

The providers

A provider (Provider\Provider) gives the authorization address for an Authorization (state, verifier, nonce, the origin the trip began at) and, for the code that came back, the Identity it vouches for - or throws a ProviderError with a stable reason. omniauth has none that speaks to a real server: each provider is a package of its own (Marco's decision, 2026-10-21, the shape of omnishield's captchas) - omniauth/google first, over league/oauth2-google.

The return address

A provider's return address is its configuration's, never a request's: an absolute address, or a path (/login/google/callback). A path is completed by the origin of the request that began the trip (Authorization::returnAddress(), the origin kept in the attempt with the state): a site served on two hosts, or a long-running worker (FrankenPHP) that serves several, sends each visitor back to the host they left from - never to the first host the worker served -, and the exchange repeats that trip's address, as an authorization server compares them. Each address must be one of the client's registered return addresses at the provider.

By configuration

Providers::configured() reads the tree a host's omniauth.yaml (or config/omniauth.php) holds, each entry made by the first factory (Provider\ProviderFactory) that knows its kind:

Providers::configured([
    'google' => ['client_id' => $id, 'client_secret' => $secret, 'redirect_uri' => '/login/google/callback'],
], new Omniauth\Google\GoogleFactory());

An entry without a client_id is not served (lesringostars declares providers with no credentials: they stay out); one without a redirect_uri, or that no factory makes, is a mistake (InvalidArgumentException, naming the package to install). Providers given as they are (a service) sit beside them: new Providers($given, ...Providers::configured($config, ...$factories)).

Providers::fromConfig() (deprecated, kept one release) makes its Google entries through omniauth/google's factory when that package is installed; Omniauth\OAuth\Provider\GoogleProvider is an alias of omniauth/google's class for the same release.

Over league/oauth2-client

Provider\LeagueProvider makes any league/oauth2-client provider an omniauth Provider: the authorization address with omniauth's state and S256 challenge, the code exchanged with its verifier, the person read from the resource owner's details ($fields names the subject, the address, whether it is verified, the name). omniauth/google's GoogleProvider is built on it; a provider without a package of its own can be served through it by hand (league/oauth2-facebook, a GenericProvider on a provider's three addresses). league is not required by omniauth - the provider packages require it -, so the class loads without it but is usable only with it. PKCE is omniauth's: leave the league provider's pkceMethod unset. (Omniauth\Google\LeagueProvider is an alias of it for one release.)

use League\OAuth2\Client\Provider\GenericProvider;
use Omniauth\OAuth\Provider\LeagueProvider;

$forge = new LeagueProvider(
    name: 'forge',                                   // the provider's key: the routes' {provider}, Identities' $provider
    league: new GenericProvider([
        'clientId' => $id, 'clientSecret' => $secret,
        'urlAuthorize' => 'https://forge.example/oauth/authorize',
        'urlAccessToken' => 'https://forge.example/oauth/token',
        'urlResourceOwnerDetails' => 'https://forge.example/api/user',
    ]),
    scopes: ['read:user'],                           // [] : the league provider's defaults
    fields: ['subject' => 'id', 'email' => 'email', 'verified' => 'email_verified', 'name' => 'name'],
    redirectUri: '/login/forge/callback',            // null: the league provider's own redirectUri
);

For a trip begun at https://example.org, its authorization address (run in the harness on 2026-10-25, no network: building the address calls nothing) is forge.example/oauth/authorize with state, code_challenge, code_challenge_method, scope (read:user), redirect_uri (https://example.org/login/forge/callback) and league's own response_type, approval_prompt and client_id.

What it does: the address is league's getAuthorizationUrl() with state, code_challenge, code_challenge_method=S256, scope and redirect_uri (a league provider that drew a PKCE code of its own is refused with a LogicException); the exchange is getAccessToken('authorization_code', code, code_verifier, redirect_uri), any exception there a ProviderError exchange-failed; the person is getResourceOwner()'s toArray() (a failure exchange-failed, league/oauth2-google's HostedDomainException hosted-domain), a subject missing or empty no-subject. The Identity keeps every detail in claims. A subclass overrides authorizationOptions(), identity(), details() or fromClaims() (omniauth/google adds the nonce and reads the ID token).

In tests

Testing\FakeProvider is an authorization server in memory: consent($authorizationUrl, $person) gives the return's code and state, deny() an access_denied; identify() exchanges a code once, only with the verifier whose challenge the address carried and for the return address it was given to, and checks the nonce. Its return address may be a path too. Under it a host's tests sign in with no network, and a forged or injected return fails as it would at Google.

new FakeProvider(
    name: 'google',
    redirectUri: 'https://example.org/login/google/callback',   // or a path
    clientId: 'omniauth-test-client',
    scopes: ['openid', 'email', 'profile'],
);

Its address is FakeProvider::AUTHORIZE (https://provider.test/authorize) with the client, the return address, response_type=code, the scopes, the state, the S256 challenge and the nonce. consent() takes an Identity or an array (sub, email, email_verified, name) and refuses an address not of its client and return address, or without its challenge (InvalidArgumentException); returnUrl($return) gives the address the browser lands on; $exchanges lists every exchange asked (code and verifier). A code unknown or used, a verifier that is not the challenge's, a return address that is not the authorization's are ProviderError exchange-failed; a nonce that is not the trip's invalid-id-token.

Conformance suite

Omniauth\Testing\ProviderContractTests is the Provider contract as PHPUnit tests: every provider package runs it in a Tests/<Name>ContractTest.php of its own (FakeProvider in the core's Tests/FakeProviderContractTest.php, omniauth/google in its Tests/GoogleContractTest.php). The test case gives the provider for a return address, and makes its server answer - recorded answers, no network: consented() (the server will vouch for the person on the code it returns, the authorization's nonce in its ID token), refused() (an invalid_grant), and unanswered() (an HTTP 503 or no connection; null, the default, for a provider in memory). With factory() and entry() it checks the factory too, with secret() that no message shows the client's secret.

use Omniauth\Testing\ProviderContractTests;

final class GoogleContractTest extends TestCase
{
    use ProviderContractTests;

    protected function provider(string $redirectUri): Provider { /* a GoogleProvider on a Guzzle MockHandler */ }
    protected function consented(Provider $provider, Authorization $authorization, string $authorizationUrl): string { /* the token answer queued */ }
    protected function refused(Provider $provider): string { /* an invalid_grant queued */ }
    protected function unanswered(Provider $provider): string { /* a 503 queued */ }
}

The methods (Method\Method: passwords, codes, TOTP, passkeys) are another contract, each with its own tests: this suite is the identity providers'.

The second-factor rule

interface SecondFactorPolicy
{
    /** @return list<Factor> the second factors still due (any one suffices); none: done */
    public function required(object $account, array $passed, Context $context): array;
}

The default, EnrolledSecondFactors: an account that set up a second factor (an authenticator application, the code by e-mail: each Method\SecondFactor says whether it is enrolled()) must pass one of them - or a backup code, offered last - after a first factor of the list EnrolledSecondFactors::AFTER; a second factor passed (a trusted device among them) is enough.

AFTER is [Password, Link, OAuth], Marco's decisions of 2026-10-20:

• QA1 - no second factor after a passkey: it already proves the device and the gesture or the code that unlocks it. Passkey is not in the list.
• QA2 - a second factor after an identity provider: an account with its TOTP no longer signs in by Google without it. OAuth is in the list; it is the one behaviour that differs from the bundles by default.

A host changes the list (new EnrolledSecondFactors($methods, [...])) or writes its own policy: omnibase decorates this one with its SecurityPolicy (a role that requires a second factor and has none is sent to enrol; the demo account never is). Refusing to turn a factor off ("the administrator wins") is a listener of Event\Revoking.

How the default rule decides

EnrolledSecondFactors::required($account, $passed, $context), with $after the list above:

1. none of the factors passed is in $after (a passkey alone, say): nothing is due;
2. a second factor was passed already (a trusted device, read by the conductor on the way): nothing is due;
3. the second factors mounted that the account set up (Method\SecondFactor::enrolled(); the ambient trusted device is not one) are listed in the order the methods were mounted; without any but backup codes, nothing is due;
4. otherwise those factors are due, any one of them, and backup codes last when the account has some.

use Omniauth\EnrolledSecondFactors;
use Omniauth\Factor;

// A second factor after a passkey too: QA1 undone for this host.
$policy = new EnrolledSecondFactors($methods, [Factor::Password, Factor::Link, Factor::OAuth, Factor::Passkey]);
$omniauth = new Omniauth($accounts, $methods, $state, policy: $policy);

The conductor builds new EnrolledSecondFactors($methods) when no policy is given. A policy of the host's own receives the account, the factors passed and the Context (the host can ask more of a visitor from an unknown network, say) and returns the factors still due; an empty list ends the sign-in.

Events

PSR-14, optional: pass any EventDispatcherInterface as events:.

A refusal ends the attempt with Failure::Refused and the listener's reason in Result::$reason.

What each event carries

Beginning, Verifying and Revoking have refuse(string $reason) and refusal(): ?string; the last listener to refuse sets the reason. A begin() refused by a listener answers Challenge::failed(refused, $reason) and dispatches no SignInFailed; an IdentityUnknown result dispatches neither SignedIn nor SignInFailed. Without a dispatcher (events: null) nothing is dispatched and nothing is refused.

A listener refusing a sign-in from one address, with a dispatcher of a few lines (run in the harness on 2026-10-25):

<?php

require 'vendor/autoload.php';

use Omniauth\ArrayState;
use Omniauth\Context;
use Omniauth\Event\SignedIn;
use Omniauth\Event\SignInFailed;
use Omniauth\Event\Verifying;
use Omniauth\Method\Methods;
use Omniauth\Omniauth;
use Omniauth\Password\PasswordMethod;
use Omniauth\Testing\InMemoryStore;
use Omniauth\Testing\TestAccount;
use Psr\EventDispatcher\EventDispatcherInterface;

// Any PSR-14 dispatcher; a tiny one here.
$events = new class implements EventDispatcherInterface {
    /** @var array<class-string, list<callable>> */
    public array $listeners = [];

    public function dispatch(object $event): object
    {
        foreach ($this->listeners[$event::class] ?? [] as $listener) {
            $listener($event);
        }

        return $event;
    }
};
$events->listeners[Verifying::class][] = static function (Verifying $event): void {
    if ('203.0.113.66' === $event->context->ip) {
        $event->refuse('not-a-human');                 // omnishield's answer, say
    }
};
$events->listeners[SignInFailed::class][] = static fn (SignInFailed $e) => print("failed: {$e->factor->value} {$e->failure->value} {$e->reason} {$e->identifier}\n");
$events->listeners[SignedIn::class][] = static fn (SignedIn $e) => print('signed in: '.$e->account->identifier.' from '.$e->context->ip."\n");

$store = new InMemoryStore(new TestAccount('42', 'ringo', 'ringo@example.org', password_hash('yellow-submarine', PASSWORD_BCRYPT)));
$omniauth = new Omniauth($store, new Methods([new PasswordMethod($store, $store)]), new ArrayState(), events: $events);

$proof = ['identifier' => 'ringo', 'password' => 'yellow-submarine'];
$result = $omniauth->verify('password', new Context(ip: '203.0.113.66'), $proof);
echo $result->failure->value, ': ', $result->reason, "\n";
$omniauth->verify('password', new Context(ip: '203.0.113.7'), $proof);

failed: password refused not-a-human ringo
refused: not-a-human
signed in: ringo from 203.0.113.7

Configuration reference

omniauth has no configuration file of its own: each class takes its options in its constructor. The hosts' files - config/packages/omniauth.yaml (Symfony) and config/omniauth.php (Laravel) - are the bridges' and build these classes from their keys.

The conductor's options

new Omniauth(...):

The methods of the core

The packages' methods: omniauth/otp's TotpMethod (leeway 0, period 30, digits 6, algorithm sha1, issuer, server, clock) and omniauth/webauthn's PasskeyMethod (rp: a RelyingParty with id, name, origins, insecure; timeout) - their manuals list every option.

The second-factor rule

new EnrolledSecondFactors(Methods $methods, array $after = EnrolledSecondFactors::AFTER): $after lists the first factors a second one follows, [Factor::Password, Factor::Link, Factor::OAuth] by default (The second-factor rule). new NoSecondFactorLinking(Methods $methods) reads the methods when it is asked, so it can be built before the OAuth method is added to them.

The throttle's limits

new CacheThrottle($cache, array $limits = [], ?ClockInterface $clock = null, string $prefix = 'omniauth.throttle.') counts the tries in any PSR-6 pool (CacheItemPoolInterface) or PSR-16 cache (CacheInterface): a fixed window per scope and key, [tries, seconds]. $limits replaces the defaults scope by scope:

The scopes are the factor's value for a verification (and an enrolment's confirmation), the factor's value and .begin for a beginning. The keys are the conductor's: <identifier in lower case>|<ip> for a first factor (- without an address), identifier:<identifier in lower case> for a first factor's beginning with an address typed, account:<handle> once the account is known. A try is counted before the check; a success resets its scope and key. The window starts at the first try and lasts its seconds; the cache entry expires with it. Keys are hashed (SHA-256, under $prefix), so any identifier is a valid cache key.

use Omniauth\CacheThrottle;
use Symfony\Component\Cache\Adapter\RedisAdapter;

$throttle = new CacheThrottle(new RedisAdapter($redis), ['password' => [10, 300]]);   // 10 tries in 5 minutes

Three tries in five minutes, then the same account from another address (run in the harness on 2026-10-25, on Testing\ArrayCache and a FixedClock):

<?php

require 'vendor/autoload.php';

use Omniauth\ArrayState;
use Omniauth\CacheThrottle;
use Omniauth\Context;
use Omniauth\Method\Methods;
use Omniauth\Omniauth;
use Omniauth\Password\PasswordMethod;
use Omniauth\Testing\ArrayCache;
use Omniauth\Testing\FixedClock;
use Omniauth\Testing\InMemoryStore;
use Omniauth\Testing\TestAccount;

$clock = new FixedClock();
$store = new InMemoryStore(new TestAccount('42', 'ringo', 'ringo@example.org', password_hash('yellow-submarine', PASSWORD_BCRYPT)));
$omniauth = new Omniauth(
    accounts: $store,
    methods: new Methods([new PasswordMethod($store, $store)]),
    state: new ArrayState(),
    throttle: new CacheThrottle(new ArrayCache($clock), ['password' => [3, 300]], $clock),   // 3 tries in 5 minutes
    clock: $clock,
);
$context = new Context(ip: '203.0.113.7');

foreach (['a', 'b', 'c', 'yellow-submarine'] as $password) {
    echo $omniauth->verify('password', $context, ['identifier' => 'ringo', 'password' => $password])->failure?->value ?? 'authenticated', "\n";
}
$clock->advance(300);
echo $omniauth->verify('password', $context, ['identifier' => 'ringo', 'password' => 'yellow-submarine'])->status->value, " after 5 minutes\n";
echo $omniauth->verify('password', new Context(ip: '198.51.100.9'), ['identifier' => 'ringo', 'password' => 'a'])->failure->value, " from another address\n";

bad-credentials
bad-credentials
bad-credentials
throttled
authenticated after 5 minutes
bad-credentials from another address

CacheThrottle reads, then writes: two requests at the same instant may both pass the last try. A host that needs the limit exact under concurrency implements Contract\Throttle on a store that counts atomically (a rate limiter with a lock).

The identity providers

Providers::configured(array $config, ProviderFactory ...$factories) reads, per entry (its key the provider's name):

new Providers(Provider ...$providers) holds providers given as they are; the two combine: new Providers($given, ...Providers::configured($config, $factory)). A second provider of the same name replaces the first. Providers::fromConfig() is deprecated (one release): it makes the Google entries through omniauth/google's factory.

LeagueProvider and FakeProvider take their options in their constructors (Identity providers).

The state

new ArrayState(array &$values = []) keeps the attempt in a PHP array held by reference; ArrayState::session() over $_SESSION (after session_start()). The keys it writes are omniauth.attempt and omniauth.enrolment.<factor>.

Errors

A visitor's mistake is never an exception: a wrong password, an expired code, a forged return from a provider, too many tries all come back as a Result (or a Challenge, an Enrolled) with a Failure and, often, a reason (Concepts). Exceptions are the host's and the application's mistakes, and the one refusal a store throws on purpose.

The exceptions

Every exception class of omniauth implements Omniauth\Exception\OmniauthException (a \Throwable):

Programming errors

Not OmniauthExceptions - a host or an application calling omniauth wrongly:

These come out of Providers::configured() and the conductor as they are (run in the harness on 2026-10-25):

Omniauth\Exception\UnknownMethod: No method is mounted for "totp"; mounted: password.
ValueError: "sms" is not a valid backing value for enum Omniauth\Factor
LogicException: The "password" method has nothing to begin: verify() it directly.
LogicException: The "password" method cannot be turned off.
InvalidArgumentException: The "google" provider has no redirect_uri: its return address (or path) is its configuration's.
InvalidArgumentException: No provider factory makes "github" (type "github"): install its package (omniauth/github) and pass its factory.

and an account the application refuses, through the conductor:

$store = new InMemoryStore(new TestAccount('7', 'pete', 'pete@example.org', password_hash('x', PASSWORD_BCRYPT), refused: 'banned'));
$omniauth = new Omniauth($store, new Methods([new PasswordMethod($store, $store)]), new ArrayState());
$result = $omniauth->verify('password', new Context(ip: '203.0.113.7'), ['identifier' => 'pete', 'password' => 'x']);
echo $result->status->value, ' ', $result->failure->value, ' ', $result->reason, ' ', $result->account?->identifier, "\n";
// failed account-refused banned pete

The failures and their reasons

What a page translates - Result::$failure, and Result::$reason under it:

What to catch where

Testing

Omniauth\Testing\ holds what a host's tests (and a first try) need, with no library:

A host's test drives the conductor with them, here a passkey and an authenticator application stood in for (run in the harness on 2026-10-25):

<?php

require 'vendor/autoload.php';

use Omniauth\ArrayState;
use Omniauth\Context;
use Omniauth\Factor;
use Omniauth\Method\Methods;
use Omniauth\Omniauth;
use Omniauth\Password\PasswordMethod;
use Omniauth\Testing\FixedClock;
use Omniauth\Testing\InMemoryStore;
use Omniauth\Testing\StubMethod;
use Omniauth\Testing\StubSecondFactor;
use Omniauth\Testing\TestAccount;

$store = new InMemoryStore(new TestAccount('1', 'ringo', 'ringo@example.org', password_hash('x', PASSWORD_BCRYPT)));
$omniauth = new Omniauth($store, new Methods([
    new PasswordMethod($store, $store),
    new StubMethod(Factor::Passkey, $store),                  // a passkey, without webauthn-lib
    new StubSecondFactor(Factor::Totp, $store, ['1']),        // an authenticator application set up by account 1
]), new ArrayState(), clock: new FixedClock());

echo $omniauth->verify('passkey', new Context(), ['handle' => '1'])->status->value, " by passkey (QA1: no second factor)\n";
echo $omniauth->verify('password', new Context(), ['identifier' => 'ringo', 'password' => 'x'])->status->value, " by password\n";
echo $omniauth->verify('totp', new Context(), ['code' => '123456'])->status->value, " by totp\n";

authenticated by passkey (QA1: no second factor)
second-factor-required by password
authenticated by totp

The test doubles in detail

TestAccount - public properties, every proof on the account:

InMemoryStore takes TestAccount objects (add() adds one later) and refuses any other object (InvalidArgumentException); emailCodes() and totpSecrets() give the stores of those two contracts over the same accounts. RecordingSender keeps $sent (account and message pairs), last() and count(). FixedClock starts at 2026-10-20 12:00:00 UTC unless given another time; ArrayCache reads its lifetimes on the clock it is given (the system's otherwise). StubMethod refuses a second factor and StubSecondFactor a first one (InvalidArgumentException); StubSecondFactor's code is 123456 unless given another.

Identity providers in tests

Omniauth\OAuth\Testing\FakeProvider stands in for Google and the person consenting there, with no network (Identity providers); a provider package checks itself against the contract with Omniauth\Testing\ProviderContractTests (Conformance suite). The method packages ship their own doubles: omniauth/otp's Testing\AuthenticatorApp (the person's phone), omniauth/webauthn's Testing\SoftwareAuthenticator (a P-256 authenticator answering as a browser) and Testing\InMemoryPasskeys.

In a framework's tests

Under Symfony and Laravel the stores are services: bind the in-memory ones (or the application's on a test database) in the test environment, and replace the Sender with a RecordingSender to read the link or the code a test signs in with. omnibridge's own suites do so (tests/AuthTest.php in omnibridge/symfony and omnibridge/laravel: every method signed in through a kernel or an application, a simulated Google included).

The Docker harness

docker/ runs this package with every omniauth/* method package - from GitHub (branch 1.x), or from the checkouts beside this one when OMNIAUTH_PLUGINS=../.. is set in docker/.env - on PHP 8.4, with scheb/2fa installed beside them as a development dependency (the trusted-device tokens are compared with its encoder's, omniauth/otp's codes with its TOTP authenticator's), and what each method package's tests need beside it (docker/harness/plugins.php: doctrine/dbal and web-auth/webauthn-symfony-bundle for omniauth/webauthn's comparison with the bundle's records). Nothing runs on the host.

cd docker && cp .env.dist .env       # the checkouts of the workspace
docker compose run --rm omniauth test     # every package's tests
docker compose run --rm omniauth bare     # plain PHP: a whole sign-in by hand, and what PHP loaded
docker compose down -v

bare builds everything by hand on the in-memory stores: a password alone; a password, a code by e-mail and "trust this browser", then the same account on that browser with no code; a backup code; a link, then the same link again; a password of 102 bytes hashed by Symfony; six wrong passwords. Tests/BareTest runs it, and loads every class of the package, in PHP processes of their own, and checks that nothing is loaded but omniauth, the PSR interfaces and symfony/password-hasher - not a class of a framework, of scheb/2fa or of an application, though the harness has them installed.

Running a script of your own

The entrypoint also runs php, composer and sh as they are; the harness's autoloader is /harness/vendor/autoload.php. The examples of this manual were run so, a scratch directory mounted read-only:

docker compose run --rm -v "$PWD/scratch:/scratch:ro" omniauth php /scratch/example.php

On 2026-10-25 (PHP 8.4.26, PHPUnit 11.5.57, the four packages from their checkouts), test ran 235 tests, 2490 assertions, green, one skipped; bare printed each attempt's result as JSON (password: authenticated as ringo; two-steps: second-factor-required with email-code and backup-code offered, then authenticated by password + email-code with a trusted device, then by password + trusted-device).

The harness's Composer project lives in the volume omniauth-harness_harness: docker compose down -v removes it, and the next run installs again (over the network: the method packages that have no checkout under OMNIAUTH_PLUGINS come from GitHub).

Writing a method or a provider

omniauth has two extension points: a method (a way to prove a factor, Method\Method) and an identity provider (a server the OAuth method sends the visitor to, OAuth\Provider\Provider). The packages omniauth/otp and omniauth/webauthn are methods; omniauth/google is a provider.

A method

A method checks a proof within an attempt and touches neither request nor response. It implements Method\Method and, as it needs, the other interfaces of Methods:

use Omniauth\Attempt;
use Omniauth\Context;
use Omniauth\Factor;
use Omniauth\Failure;
use Omniauth\Method\SecondFactor;
use Omniauth\Method\Verdict;
use Omniauth\Proof;

/** A code read from a hardware token, checked by the application's own service. */
final class HardwareTokenMethod implements SecondFactor
{
    public function __construct(private readonly TokenChecker $checker) {}

    public function factor(): Factor
    {
        return Factor::Totp;              // the factors are omniauth's enum: a method stands for one of them
    }

    public function enrolled(object $account): bool
    {
        return $this->checker->hasToken($account);
    }

    public function verify(Attempt $attempt, Proof $proof, Context $context): Verdict
    {
        $account = $attempt->account();   // a second factor: the account the first factor found
        if (null === $account) {
            return Verdict::refused(Failure::NoAttempt);
        }

        return $this->checker->check($account, $proof->string('code'))
            ? Verdict::passed($account)
            : Verdict::refused(Failure::BadCode);
    }
}

The rules every method of the core keeps:

• The factor is one of Factor's cases. Methods holds one method per factor: a method of your own replaces the core's for that factor. Factor::role() decides whether it is a first factor (it finds the account: Verdict::passed($account) with the account it found) or a second one (the account is $attempt->account()).
• What a ceremony remembers goes into the attempt, never into the answer: $attempt->keep($factor, $value) at begin(), $attempt->take($factor) at verify() (a challenge serves once), values of scalars and arrays (the attempt is serialised into the session). Nothing kept at verification time is Verdict::expired().
• One answer for "no such account" and "wrong secret": bad-credentials for a first factor, in the same time when the method can (the password checks a hash of nothing).
• Stable failures, stable reasons: a Failure case, and a short reason a page translates (replayed, invalid-assertion); a library's message is for the log.
• No request, no response: what the request says comes in the Context, what the visitor sent in the Proof; what the host must do comes out in the Challenge or the Verdict.
• The conductor does the rest - throttle, events, Accounts::check(), the second-factor rule, SignedIn: a method does not dispatch, throttle or check the account.

A method to set up from the settings implements Enrolling (enrolBegin(), enrolConfirm(), the enrolment being an Attempt with its account identified); one to turn off, Revocable. A second factor the rule must know about implements SecondFactor::enrolled(). A second factor read from the request rather than typed implements Ambient (the conductor tries it by itself and asks it for the cookie's value after trust).

Test a method through the conductor, on the in-memory stores and a FixedClock (Testing).

An identity provider

A provider gives the authorization address of a trip and, for the code that came back, the Identity it vouches for:

use Omniauth\OAuth\Authorization;
use Omniauth\OAuth\Exception\ProviderError;
use Omniauth\OAuth\Identity;
use Omniauth\OAuth\Provider\Provider;

interface Provider
{
    public function name(): string;                                           // its key: the routes' {provider}, Identities' $provider
    public function authorizationUrl(Authorization $authorization): string;   // carries the state, the S256 challenge, the nonce
    /** @throws ProviderError */
    public function identify(string $code, Authorization $authorization): Identity;
}

What omniauth gives the provider, OAuth\Authorization:

What the provider gives back, OAuth\Identity: provider (its own name - the method refuses an identity of another), subject (not empty: InvalidArgumentException), email, emailVerified (true only when the provider says so: Identity::verified($claim) reads a JSON true, "true", 1 or "1"), name, and every claim as the provider said it (claims).

The rules:

• The return address is the configuration's, never the request's: absolute, or a path completed by Authorization::returnAddress(); the same address is sent again at the exchange.
• PKCE and the state are omniauth's: the address carries state and code_challenge with code_challenge_method=S256; the exchange sends code_verifier. An OpenID Connect provider sends the nonce and checks it in the ID token.
• Everything the server refuses or fails to answer is a ProviderError with one of its four reasons - never another exception, never the client's secret in its message.
• Over league/oauth2-client, extend OAuth\Provider\LeagueProvider and override what differs (Over league/oauth2-client): omniauth/google adds the nonce in authorizationOptions() and reads the ID token in identity().

A provider made from a host's configuration comes with a factory:

use Omniauth\OAuth\Provider\Provider;
use Omniauth\OAuth\Provider\ProviderFactory;

final class ForgeFactory implements ProviderFactory
{
    public function create(string $name, array $entry): ?Provider
    {
        if ('forge' !== ($entry['type'] ?? $name)) {
            return null;                  // not this factory's kind: the next factory is asked
        }

        return new ForgeProvider($name, (string) $entry['client_id'], (string) ($entry['client_secret'] ?? ''), (string) $entry['redirect_uri']);
    }
}

Providers::configured() asks each factory in turn and has already left out the entries without a client_id and refused those without a redirect_uri. Under Symfony a factory class of the application is autoconfigured (tag omniauth.oauth_provider_factory); under Laravel, tag its binding omniauth.oauth_provider_factory.

Its conformance suite

A provider package runs Omniauth\Testing\ProviderContractTests on recorded answers, in a Tests/<Name>ContractTest.php: Conformance suite lists what each test checks and the hooks to fill (provider(), consented(), refused(), unanswered(), factory(), entry(), secret(), sendsNonce()). The trait requires phpunit/phpunit (omniauth suggests it). Methods have no shared suite: each package's tests drive its method through the conductor.

Verified, and not

What the tests prove

Run on 2026-10-25 in the harness (docker compose run --rm omniauth test, PHP 8.4.26, PHPUnit 11.5.57), the four packages from their checkouts: 235 tests, 2490 assertions, green - the core 126, omniauth/google 28, omniauth/otp 47, omniauth/webauthn 34. One skipped: ProvidersTest::testTheFormerFromConfigNeedsGooglesPackage, which needs omniauth/google absent (omniauth/google's own tests cover the deprecated path).

The core's tests (every file also linted on PHP 8.2):

• each method's way through and its refusals on the in-memory stores - wrong secret, unknown address answered as a wrong password, expired, used twice, throttled, a banned account, the second factor offered, passed, not offered, its attempt expired;
• QA1 and QA2 through the default rule;
• the trusted-device tokens equal to those scheb/2fa 8.6.1's JwtTokenEncoder writes for the same input, whole seconds and microseconds, each read by the other (recorded, and live with scheb/2fa installed in the harness);
• hashes written by symfony/password-hasher 8.1 ("auto": bcrypt, cost 13), one of a 102-byte password that password_verify() alone refuses;
• docs/installation.md and docs/oauth.md run as written (Tests/DocsTest.php);
• in plain PHP (Tests/BareTest.php), a whole sign-in by hand loading nothing but omniauth, the PSR interfaces and symfony/password-hasher; a sign-in through a fake identity provider loading no OAuth library; every class of the package loading with them alone, LeagueProvider included;
• the identity providers' trip (state, PKCE, nonce, forged and injected returns, the linking rule, a return path on the host of each trip) on the fake provider, and LeagueProvider over a generic league provider with recorded answers;
• the providers' conformance suite (Omniauth\Testing\ProviderContractTests) green for FakeProvider and omniauth/google, on recorded answers.

The examples of this manual were run in the harness on 2026-10-25, and their output pasted as printed: the installation, the identity providers, the sign-in link, events, testing, the throttle's limits, errors, LeagueProvider's address.

The bridges are tested in omnibridge: tests/AuthTest.php of omnibridge/symfony (a kernel signing in through omniauth alone: each method, the second factor, its page and nobody else's, refusals, CSRF, throttle, remember-me, trusted device, a simulated Google, the return address on the host of each request under one container) and of omnibridge/laravel; they were not run for this manual.

What is not verified

• An application's own stores: omnibase fills them (Base\Auth\, step AU4) and tests them in its own suite.
• A cookie written by a running scheb/2fa on an application: the encoder is compared, not a browser's cookie.
• Concurrent tries against CacheThrottle (read then written, not atomic: a host that needs it exact uses a store that counts atomically).
• A real identity provider: Google's answers are recorded from its documentation (omniauth/google's manual).
• The Symfony and Laravel pages were written from omnibridge's code at its 1.x branch; the omniauth.yaml defaults were resolved with Symfony's Config Processor in omnibridge/symfony's image, the Laravel defaults read from Auth\Settings.

Responsibility

omnisense/omniauth and its omniauth/* packages are independent code: omniauth/google is an unofficial client of Google's sign-in, not affiliated with or endorsed by Google, and whoever runs it complies with Google's terms for its APIs. The MIT licence covers this code only.