ratespecial / logto-laravel
Logto.io OIDC support for Laravel
Requires
- php: ^8.3
- firebase/php-jwt: ^7.0
Requires (Dev)
- illuminate/console: ^12|^13
- illuminate/support: ^12|^13
- laravel/pint: ^1.0
- orchestra/testbench: ^10|^11
- phpstan/phpstan: ^2.1.54
- phpunit/phpunit: ^11
Suggests
None
Provides
None
Conflicts
None
Replaces
None
README
Logto.io (OAuth/OIDC) support for Laravel. This package contributes three independent features:
logto-api-resourceguard — a Laravel auth guard that validates Logto-issued JWT access tokens and JIT-provisions users.- MCP protected-resource controller — an RFC 9728
/.well-known/oauth-protected-resourceendpoint that letslaravel/mcpuse Logto as its identity provider instead of Passport or Sanctum. - Web sign-in (opt-in) — an OIDC Authorization Code + PKCE flow so Blade/server-rendered apps can sign users in through Logto with a normal Laravel session guard.
Requirements: PHP ^8.3, Laravel 12 or 13 (what the test suite runs against), a Logto tenant.
Table of Contents
- Installation
- Configuration
- High-level Architecture
- JIT User Provisioning
- Feature 1 — The
logto-api-resourceGuard - Feature 2 — MCP Protected Resource Controller
- Feature 3 — Web sign-in (Authorization Code + PKCE)
- Testing your app
- Development
- License
Installation
composer require ratespecial/logto-laravel
The service provider is auto-registered via Laravel's package discovery.
Configuration
The package reads all of its settings from config/logto.php (merged automatically via mergeConfigFrom, not publishable), which is driven by LOGTO_* environment variables. Nothing needs to be added to config/services.php. Set these in your host app's .env:
LOGTO_ENDPOINT=https://your-tenant.logto.app LOGTO_API_RESOURCE=https://api.example.com LOGTO_CACHE_TTL=600 LOGTO_SUBJECT_COLUMN=logto_sub # MCP feature (off by default) LOGTO_MCP_ROUTES=true LOGTO_MCP_SCOPES="mcp:use" # Web sign-in feature (off by default) LOGTO_WEB_ROUTES=true LOGTO_WEB_APP_ID=your-traditional-web-app-id LOGTO_WEB_APP_SECRET=your-app-secret
| Env var | Config key | Default | Purpose |
|---|---|---|---|
LOGTO_ENDPOINT |
logto.endpoint |
— | Your Logto tenant URL. Required. |
LOGTO_API_RESOURCE |
logto.api-resource |
app.url |
JWT audience this API accepts. |
LOGTO_CACHE_TTL |
logto.cache-ttl |
600 |
TTL (seconds) for cached OIDC discovery + JWKS. |
LOGTO_SUBJECT_COLUMN |
logto.subject-column |
logto_sub |
User-model column that stores the JWT sub claim. |
LOGTO_LINK_UNCLAIMED_BY_EMAIL |
logto.link-unclaimed-by-email |
false |
Let a new sub claim an existing user whose subject is null and whose email matches. See Migrating Logto tenants. |
LOGTO_PROVISION_WITHOUT_EMAIL |
logto.provision-without-email |
false |
Save a user row even when there is no email. See Tokens without an email. |
LOGTO_MCP_ROUTES |
logto.mcp.routes |
false |
Enables the RFC 9728 discovery routes. |
LOGTO_MCP_SCOPES |
logto.mcp.scopes-supported |
mcp:use |
Space-delimited scopes advertised in the discovery metadata. |
LOGTO_MCP_PROTECTED_RESOURCE_MIDDLEWARE |
logto.mcp.protected-resource-middleware |
'' |
Comma-delimited middleware applied to the discovery route. |
LOGTO_WEB_ROUTES |
logto.web.routes |
false |
Enables the web sign-in routes. |
LOGTO_WEB_APP_ID |
logto.web.app-id |
'' |
App ID of the Logto Traditional Web application. |
LOGTO_WEB_APP_SECRET |
logto.web.app-secret |
'' |
App secret of that application. |
LOGTO_WEB_PREFIX |
logto.web.prefix |
logto |
URL prefix for the routes. |
LOGTO_WEB_GUARD |
logto.web.guard |
web |
Session guard users are logged in to. |
LOGTO_WEB_MIDDLEWARE |
logto.web.middleware |
web |
Comma-delimited middleware for the routes. Must include sessions. |
LOGTO_WEB_OIDC_SCOPES |
logto.web.oidc-scopes |
openid profile email |
Space-delimited OIDC scopes. Control which user claims the ID token carries; grant no access. |
LOGTO_WEB_RESOURCE |
logto.web.resource |
— | Optional API resource to also request an access token for. Needs resource or required scopes. See Limiting who can sign in. |
LOGTO_WEB_RESOURCE_SCOPES |
logto.web.resource-scopes |
— | Optional space-delimited permissions on LOGTO_WEB_RESOURCE to request. Holding any one is enough. |
LOGTO_WEB_REQUIRED_SCOPES |
logto.web.required-scopes |
— | Optional space-delimited permissions on LOGTO_WEB_RESOURCE the user must all hold. Requested automatically. |
LOGTO_WEB_REDIRECT_AFTER_LOGIN |
logto.web.redirect-after-login |
/ |
Fallback destination when there is no intended URL. |
LOGTO_WEB_REDIRECT_AFTER_LOGOUT |
logto.web.redirect-after-logout |
/ |
Where Logto sends the browser after sign-out. |
The JWT-claim → user-model attribute mapping defaults to email and name. Override logto.model-attributes by setting it at runtime, for example config(['logto.model-attributes' => [...]]) in a service provider's register().
High-level Architecture
flowchart LR
subgraph App[Laravel Host App]
Routes[Routes / MCP servers]
User[(users table)]
end
subgraph Lib[ratespecial/logto-laravel]
Guard[LogtoApiResourceGuard]
Resolver[UserResolver]
WebCtrl[WebAuthController]
Validator[LogtoTokenValidator]
Discovery[OidcDiscoveryService]
MCPCtrl[OauthProtectedResourceController]
end
Logto[(Logto tenant)]
Routes -- auth:logto --> Guard
Guard --> Validator --> Discovery
Discovery -- JWKS + OIDC config --> Logto
Guard --> Resolver
WebCtrl --> Resolver
Resolver -- firstOrNew + forceFill / setOAuthScopes --> User
Routes -- /logto/sign-in --> WebCtrl
Routes -- .well-known/oauth-protected-resource --> MCPCtrl
MCPCtrl --> Discovery
Loading
JIT User Provisioning
This package uses just-in-time (JIT) user provisioning: there is no separate registration flow. The first time a given Logto identity (sub claim) presents a valid access token to your API, the guard resolves the user with firstOrNew keyed by logto.subject-column and inserts a new row. On every subsequent request, the same row is found and updated with any mapped claim attributes (email, name, etc.). Mapped attributes are written with forceFill, so they're persisted even if your user model doesn't list them in $fillable — the values come from a validated JWT, not request input.
Users without an email are not stored — see Tokens without an email.
The subject must be assigned at least one permission to the API resource in Logto. If they don't, the guard will reject them and the user will not be provisioned.
⚠️ Any token Logto has signed for your configured
LOGTO_API_RESOURCEaudience will result in a user record being created automatically the first time it's seen. There is no manual approval step. If you need to restrict who can sign in, enforce that in Logto (sign-in experience, roles, organization membership, or by minting tokens with specific scopes) — not in this package. You can also listen forUserProvisionedEventto audit or post-process new accounts.
Migrating Logto tenants
When moving to a new Logto tenant, every user gets a new sub. To let existing users keep their records, set the old subject column to NULL and enable LOGTO_LINK_UNCLAIMED_BY_EMAIL=true. When no user matches a token's sub, the guard looks for a user with a null subject whose email column (the column mapped from the email claim in logto.model-attributes) exactly matches the token's email claim, and writes the new sub onto that record. No UserProvisionedEvent is dispatched for a linked record.
⚠️ Anyone who can obtain a token from the new tenant carrying a victim's email will take over that victim's unclaimed record. Make sure the new tenant only issues verified emails, and turn this off once users have migrated. Access tokens must include the
If a new sub arrives with an email that another row already holds, and your users table has a unique index on that email column, the insert would fail. The resolver turns this into Ratespecial\Logto\Exceptions\DuplicateUserEmailException, which carries subject, email, existingUserKey and existingUserUnclaimed. When the existing row's subject is null, enabling LOGTO_LINK_UNCLAIMED_BY_EMAIL resolves it. Otherwise the email belongs to another Logto subject and needs manual cleanup. The web sign-in shows a 403 SignInException; on the API guard the exception propagates, so map it with $exceptions->render(...) if you want a specific response.
Feature 1 — The logto-api-resource Guard
The guard:
- Reads the bearer token from the incoming request.
- Validates signature, issuer (
iss), and audience (aud) against Logto's OIDC discovery document and JWKS — both cached forLOGTO_CACHE_TTLseconds. - JIT-provisions a user via
firstOrNewkeyed onlogto.subject-column, thenforceFills and saves it. Attributes are mapped from JWT claims usinglogto.model-attributesand persist regardless of the model's$fillable. - Attaches the
scopeclaim to the in-memory user. A globalGate::beforehook then makescan:<scope>middleware and$user->can('<scope>')work transparently. - Dispatches
Ratespecial\Logto\Events\UserProvisionedEventthe first time a givensubis seen.
Request flow
sequenceDiagram
participant Client
participant App as Laravel App
participant Guard as LogtoApiResourceGuard
participant Validator as LogtoTokenValidator
participant Discovery as OidcDiscoveryService (cached)
participant Logto
participant DB
Client->>App: GET /api/... (Bearer <jwt>)
App->>Guard: auth:logto middleware
Guard->>Validator: validate(token)
Validator->>Discovery: getJwks() / issuer
alt cache miss
Discovery->>Logto: GET /.well-known/openid-configuration
Discovery->>Logto: GET jwks_uri
end
Discovery-->>Validator: keys + issuer
Validator-->>Guard: claims (sub, scope, ...)
Guard->>DB: firstOrNew(logto_sub = claims.sub) + forceFill
Guard-->>App: authenticated User with scopes
App-->>Client: 200 (or 401 if invalid)
Loading
Migrations
The user model must have a column matching logto.subject-column (default logto_sub). Two migration groups are publishable — pick the one that fits your project:
# Fresh project — full users table with the subject column included php artisan vendor:publish --tag=logto-migrations-users # OR — existing users table; just add the logto_sub column php artisan vendor:publish --tag=logto-migrations-logto-sub php artisan migrate
If you want a different column name, publish the migration, rename the column, and set LOGTO_SUBJECT_COLUMN to match.
User model
Your user model must use the HasOAuthScopes trait and implement the OAuthScopable contract so the guard can write scopes to it and the Gate::before hook can read them back.
namespace App\Models; use Illuminate\Foundation\Auth\User as Authenticatable; use Ratespecial\Logto\Contracts\OAuthScopable; use Ratespecial\Logto\HasOAuthScopes; class User extends Authenticatable implements OAuthScopable { use HasOAuthScopes; protected $fillable = ['name', 'email', 'logto_sub']; }
Guard registration
The service provider auto-merges an auth.guards.logto entry, but you still need to point its provider at one of your auth.providers.* entries. In config/auth.php:
'guards' => [ 'logto' => [ 'driver' => 'logto-api-resource', 'provider' => 'users', ], ], 'providers' => [ 'users' => [ 'driver' => 'eloquent', 'model' => App\Models\User::class, ], ],
Protecting routes
use Illuminate\Support\Facades\Route; use App\Http\Controllers\OrderController; // Authenticate only Route::get('/api/me', fn () => auth('logto')->user()) ->middleware('auth:logto'); // Authenticate + require a Logto OAuth scope Route::get('/api/orders', [OrderController::class, 'index']) ->middleware(['auth:logto', 'can:orders:read']);
can:orders:read works because the service provider installs a Gate::before hook that delegates ability checks to $user->hasOAuthScope($ability). The same is true of programmatic checks like $user->can('orders:read') or Gate::allows('orders:read').
Reacting to new users
use Illuminate\Support\Facades\Event; use Ratespecial\Logto\Events\UserProvisionedEvent; Event::listen(function (UserProvisionedEvent $event) { // $event->user is the freshly-created Authenticatable // Send a welcome email, kick off onboarding, etc. });
The event is not dispatched for users that are linked rather than created, or for transient users (below).
Tokens without an email
A user row is only inserted when the token carries an email. If no existing row matches the sub and the email claim is empty, the guard still authenticates the request but returns an unsaved (transient) user with the subject and scopes set. auth:logto and can: work, nothing is written to the database, and no UserProvisionedEvent fires. This suits machine-to-machine (client_credentials) tokens, which have no human behind them. A row that already matches the sub is still loaded, updated and saved as normal.
Because your code may receive a user with no primary key, don't rely on $user->id/relations for such requests. Set LOGTO_PROVISION_WITHOUT_EMAIL=true to always store a row.
Logto access tokens only contain
The rule only applies when the email claim is mapped in logto.model-attributes (the default). If you remove that mapping, users are saved regardless.
Feature 2 — MCP Protected Resource Controller
laravel/mcp ships with first-class support for Laravel Passport. This package adds a parallel discovery endpoint so MCP clients (e.g. Claude Code) can authenticate against your Logto tenant instead.
It exposes RFC 9728 metadata at:
GET /.well-known/oauth-protected-resourceGET /.well-known/oauth-protected-resource/{path?}(namedmcp.oauth.protected-resource.nested)
laravel/mcp's AddWwwAuthenticateHeader middleware builds the WWW-Authenticate URL from the nested route name, so simply registering these routes wires the discovery handshake end-to-end. These endpoints must not sit behind authentication middleware — they're public discovery documents.
Note on the OAuth model. This integration does not use Dynamic Client Registration (DCR) or Client ID Metadata (CIMD). The MCP client uses a pre-registered OAuth client ID that you create up-front in Logto as a Third-party app. The client and its allowed redirect URIs must exist in Logto before the user adds the MCP server to their client.
Discovery handshake
sequenceDiagram
participant MCPClient as MCP Client (e.g. Claude Code)
participant App as Laravel App (laravel/mcp + this lib)
participant Logto
MCPClient->>App: POST /mcp (no token)
App-->>MCPClient: 401 + WWW-Authenticate: resource_metadata=".../.well-known/oauth-protected-resource/mcp"
MCPClient->>App: GET /.well-known/oauth-protected-resource/mcp
App-->>MCPClient: { resource, authorization_servers: [Logto issuer], scopes_supported }
MCPClient->>Logto: OAuth dance (authorize / token)
Logto-->>MCPClient: access_token (aud = LOGTO_API_RESOURCE)
MCPClient->>App: POST /mcp (Bearer <jwt>)
App->>App: auth:logto guard validates token
App-->>MCPClient: 200 MCP response
Loading
Logto configuration
Before any MCP client can connect, set up the OAuth client in Logto:
- In the Logto admin console, create a new Third-party app for each MCP client you want to support (e.g. one for Claude Code, one for Cursor, etc.).
- Set the application type to Single Page App.
- The generated App ID is what the MCP client will use as its OAuth Client ID.
- Under the third-party app's Redirect URIs, pre-register every loopback callback URL the client will use, including the exact port — e.g.
http://localhost:55910/callback. Logto will reject the OAuth flow if the callback URI doesn't match an entry here, so the port has to be picked up-front and reused when the MCP server is added on the client side. - Grant the third-party app permission to request your API resource (the value of
LOGTO_API_RESOURCE) and any scopes fromLOGTO_MCP_SCOPES.
Enable the discovery routes
LOGTO_MCP_ROUTES=true LOGTO_MCP_SCOPES="mcp:use"
When logto.mcp.routes is true, the service provider loads routes/mcp-routes.php, which registers both /.well-known/oauth-protected-resource endpoints. The advertised scopes_supported array comes from LOGTO_MCP_SCOPES (space-delimited).
Protecting an Mcp::web server with the Logto guard
In routes/ai.php:
use Laravel\Mcp\Facades\Mcp; use App\Mcp\Servers\MyServer; Mcp::web('/mcp', MyServer::class) ->middleware(['auth:logto', 'can:mcp:use']);
auth:logtoruns the bearer token throughLogtoApiResourceGuard.can:mcp:useenforces a Logto OAuth scope via the sameGate::beforehook the guard installs —mcp:usehere is whatever scope you defined in Logto and advertised inLOGTO_MCP_SCOPES.- On a missing or invalid token,
laravel/mcp'sAddWwwAuthenticateHeaderinjects theWWW-Authenticateheader pointing at this library's nested discovery route. No extra wiring required.
Adding the MCP server to Claude Code
Because the OAuth client and its callback URI are pre-registered in Logto, the user has to pass both the Client ID (the Logto third-party App ID) and the callback port (matching one of the redirect URIs registered in Logto) when they add the MCP server:
claude mcp add \
--transport http \
--client-id your-3rdparty-app-id \
--callback-port 55910 \
yourservice https://domain.com/mcp
The discovery handshake then kicks in automatically — Claude Code hits /mcp, gets a 401 with the WWW-Authenticate header, fetches /.well-known/oauth-protected-resource/mcp, and runs the OAuth flow against the Logto issuer returned in the metadata using the supplied client ID and callback port.
Feature 3 — Web sign-in (Authorization Code + PKCE)
For Blade/server-rendered apps (for example an admin portal). The package adds three routes that send the browser to Logto, handle the callback and log the user in to a normal Laravel session guard, so auth middleware, Auth::user() and @auth keep working. The user is resolved exactly like the API guard does: lookup by logto.subject-column, optional link by email, claim mapping and UserProvisionedEvent.
All three routes are handled by Ratespecial\Logto\Controllers\WebAuthController:
| Route | Name | Controller method | Purpose |
|---|---|---|---|
GET /{prefix}/sign-in |
logto.sign-in |
signIn() |
Stores state, nonce and PKCE verifier in the session and redirects to Logto. |
GET /{prefix}/callback |
logto.callback |
callback() |
Verifies state, exchanges the code (client secret via HTTP Basic), validates the ID token (signature, iss, aud = app ID, exp, nonce; iat/nbf/exp allow 60 s of clock skew, as for API tokens), optionally checks API resource scopes, logs the user in, regenerates the session and redirects to the intended URL. |
POST /{prefix}/sign-out |
logto.sign-out |
signOut() |
Logs out, invalidates the session and redirects to Logto's end_session_endpoint (falling back to a local redirect). |
sequenceDiagram
participant Browser
participant App as Laravel App
participant Logto
Browser->>App: GET /admin (guest)
App-->>Browser: 302 /logto/sign-in (auth middleware, url.intended saved)
Browser->>App: GET /logto/sign-in
App-->>Browser: 302 Logto /oidc/auth (state, nonce, PKCE challenge)
Browser->>Logto: Sign in
Logto-->>Browser: 302 /logto/callback?code&state
Browser->>App: GET /logto/callback
App->>Logto: POST /oidc/token (code + verifier, Basic auth)
Logto-->>App: id_token
App->>App: validate ID token, resolve user, Auth::login()
App-->>Browser: 302 intended URL
Loading
How the routes are registered
LogtoServiceProvider::boot() calls routes(), which loads routes/web-routes.php only when logto.web.routes is true. That file wraps the three routes in the configured middleware and prefix:
Route::middleware(array_filter(explode(',', (string) config('logto.web.middleware')))) ->prefix(config('logto.web.prefix')) ->group(function () { Route::get('sign-in', [WebAuthController::class, 'signIn'])->name('logto.sign-in'); Route::get('callback', [WebAuthController::class, 'callback'])->name('logto.callback'); Route::post('sign-out', [WebAuthController::class, 'signOut'])->name('logto.sign-out'); });
| Env var | Config key | Default | Effect on the routes |
|---|---|---|---|
LOGTO_WEB_ROUTES |
logto.web.routes |
false |
Registers the routes at all. When false, none of them exist. |
LOGTO_WEB_PREFIX |
logto.web.prefix |
logto |
URL prefix, giving /logto/sign-in, /logto/callback and /logto/sign-out. |
LOGTO_WEB_MIDDLEWARE |
logto.web.middleware |
web |
Comma-delimited middleware applied to the group. It must start a session, because state, nonce and verifier are stored there. |
The controller's dependency, LogtoWebClient, is bound in the provider's register() from the rest of logto.web.* (app ID, secret, scopes, resource). Resolving it throws a RuntimeException when:
- the app ID or secret is missing,
LOGTO_WEB_RESOURCE_SCOPESorLOGTO_WEB_REQUIRED_SCOPESis set withoutLOGTO_WEB_RESOURCE, orLOGTO_WEB_RESOURCEis set with neither of them, so no permission would ever be requested and every sign-in would be refused.
It is resolved when the controller is built, so a misconfiguration shows up on the first request to any of these routes, not at boot.
If you use php artisan config:cache or route:cache, run them again after changing these variables.
Logto configuration (Traditional Web app)
- In the Logto console create an application of type Traditional web.
- Redirect URI:
<APP_URL>/<prefix>/callback, for examplehttps://admin.example.com/logto/callback. Logto requires an exact match, includinghttps. - Post sign-out redirect URI: the absolute URL of
LOGTO_WEB_REDIRECT_AFTER_LOGOUT, for examplehttps://admin.example.com/. - Copy the App ID and App secret into
LOGTO_WEB_APP_ID/LOGTO_WEB_APP_SECRET. - Make sure
LOGTO_ENDPOINTis set, and that the user migration has been run.
Enable the routes
LOGTO_WEB_ROUTES=true LOGTO_WEB_APP_ID=... LOGTO_WEB_APP_SECRET=... # Optional: LOGTO_WEB_PREFIX, LOGTO_WEB_GUARD, LOGTO_WEB_REDIRECT_AFTER_LOGIN, LOGTO_WEB_REDIRECT_AFTER_LOGOUT
The guard named by LOGTO_WEB_GUARD (default web) must be a session guard whose provider's model has the subject column. The user model does not need HasOAuthScopes unless you use LOGTO_WEB_RESOURCE. A user whose ID token has no email is rejected (not logged in transiently) unless LOGTO_PROVISION_WITHOUT_EMAIL=true.
Protecting pages
Use ordinary auth middleware and send guests to the sign-in route. In bootstrap/app.php:
->withMiddleware(function (Middleware $middleware): void { $middleware->redirectGuestsTo(fn () => route('logto.sign-in')); })
Laravel stores the requested URL as url.intended, and the callback redirects back to it. To sign out, see Signing out.
redirectGuestsTo applies to every guest redirect. JSON/API requests still get a 401 because Laravel only redirects requests that expect HTML, so API-only routes using auth:logto are unaffected. If you have several HTML areas with different sign-in pages, pass a closure that inspects $request instead.
Signing out
Sign-out links in your app go to this package's route first, never straight to Logto. The route ends the Laravel session, then sends the browser to Logto to end the Logto session, and Logto sends it back to your app.
sequenceDiagram
participant Browser
participant App as Laravel App
participant Logto
Browser->>App: POST /logto/sign-out (form with @csrf)
App->>App: guard logout(), invalidate session, regenerate CSRF token
App-->>Browser: 302 Logto end_session_endpoint (client_id, post_logout_redirect_uri)
Browser->>Logto: GET /oidc/session/end
Logto->>Logto: end the Logto session
Logto-->>Browser: 302 post_logout_redirect_uri
Browser->>App: GET LOGTO_WEB_REDIRECT_AFTER_LOGOUT (now a guest)
Loading
The order matters:
- Logto can't clear your session. The Laravel session is a cookie on your domain. Sending the link to Logto first would end the Logto session but leave the user signed in to your app.
- Sign-out changes state, so it is a POST with a CSRF token. A
GETsign-out link can be triggered by an<img>on another site, by link prefetching, or by chat apps previewing the URL. The route only acceptsPOST.
This is OpenID Connect RP-Initiated Logout: the relying party (RP, your app, which relies on Logto to authenticate users) starts the logout at the OpenID Provider (OP, Logto). See the spec.
The package ships a <x-logto::sign-out> Blade component that renders the form for you:
@auth <x-logto::sign-out /> @endauth
It renders a POST form to logto.sign-out with @csrf and a plain Sign out button. Attributes go on the <form>, and the slot replaces the default button, so you can style it however you like:
<x-logto::sign-out class="inline"> <button type="submit" class="btn btn-link">Log out</button> </x-logto::sign-out>
To make it look like a link, style the button. Don't swap it for an <a href>.
Inside a dropdown menu, a <form> can break the menu's markup. Render a hidden form once in the layout, then point any button at it with the HTML form attribute:
<x-logto::sign-out id="logto-sign-out" hidden /> <ul class="dropdown-menu"> <li><button type="submit" form="logto-sign-out" class="dropdown-item">Sign out</button></li> </ul>
To change the component's markup, publish it to resources/views/vendor/logto:
php artisan vendor:publish --tag=logto-views
Without the component, the equivalent form is:
<form method="POST" action="{{ route('logto.sign-out') }}"> @csrf <button type="submit">Sign out</button> </form>
Things to set up:
- Register the absolute URL of
LOGTO_WEB_REDIRECT_AFTER_LOGOUTas a Post sign-out redirect URI on the Logto application (see Logto configuration). Logto only redirects to registered URIs. Otherwise the user ends up on a Logto page instead of back in your app. - If Logto's discovery document has no
end_session_endpoint, the route skips Logto and redirects straight toLOGTO_WEB_REDIRECT_AFTER_LOGOUT.
Limitations:
- The request to Logto sends
client_idbut notid_token_hint. The spec recommends the hint but doesn't require it. - Signing out of a different Logto app, or ending the Logto session some other way, does not end the Laravel session. That needs OIDC back-channel logout, which this package doesn't implement yet. The Laravel session lasts until it expires.
Behind a load balancer
The redirect_uri is built with route('logto.callback'), so Laravel must know the original scheme and host. Behind a load balancer configure trusted proxies so X-Forwarded-Proto/Host are honoured, otherwise the URI will be http://... and Logto will reject it:
$middleware->trustProxies(at: '*', headers: Request::HEADER_X_FORWARDED_AWS_ELB);
Also make sure APP_URL is correct, since the sign-out redirect uses url().
Errors
The callback throws Ratespecial\Logto\Exceptions\SignInException (an HttpException with status 403 and a message that is safe to show) when state is missing or doesn't match, Logto returns an error, the code exchange or ID token validation fails, the user has no email, or the API resource scope check fails. Laravel renders it as a 403 page. To customise, register a renderer:
$exceptions->render(fn (SignInException $e) => redirect('/')->withErrors(['logto' => $e->getMessage()]));
A misconfigured tenant (unreachable discovery document, missing app ID/secret) throws the usual exception, like the API guard.
Many failures also carry a developer-facing $e->detail, such as which scopes were missing, why the ID token was rejected, or the token endpoint's OAuth error. With APP_DEBUG=true the detail is appended to the message, so it shows on the 403 page. Otherwise the message stays generic. $e->detail is always available to a custom renderer. Laravel doesn't log HttpExceptions, so failures an administrator has to fix are reported separately as a RuntimeException: the token endpoint being unreachable or rejecting the code, no access token being returned for the resource, or Logto returning an opaque access token instead of a JWT (usually LOGTO_WEB_RESOURCE doesn't match an API resource indicator in Logto).
Limiting who can sign in
There are three levels of access control. Each one builds on the previous, so start with the simplest that fits. (See docs/tokens.md for the difference between the ID token and access token involved.)
| Level | Set | Who gets a session |
|---|---|---|
| 1 | Nothing (default) | Anyone who can sign in to the Logto app |
| 2 | LOGTO_WEB_RESOURCE + LOGTO_WEB_RESOURCE_SCOPES |
Users holding at least one of the listed permissions |
| 3 | LOGTO_WEB_RESOURCE + LOGTO_WEB_REQUIRED_SCOPES |
Users holding every listed permission |
Two kinds of scope are involved, and they do different jobs:
- OIDC scopes (
LOGTO_WEB_OIDC_SCOPES) control which claims about the user appear in the ID token, such asemailandname. They don't grant any access. - Resource scopes (
LOGTO_WEB_RESOURCE_SCOPES,LOGTO_WEB_REQUIRED_SCOPES) are permissions on an API resource, granted to users through Logto roles. They appear in the access token.
Logto only puts a permission in the access token when the sign-in request asks for it by name. The package therefore requests the union of all three variables, so nothing needs to be listed twice.
The check only runs during the callback. Changing a user's roles in Logto takes effect at their next sign-in; an existing Laravel session keeps working until it ends.
The permissions granted at sign-in are kept in the Laravel session and put back on the user each time the guard loads them, so can:<scope> middleware and $user->can('<scope>') keep working on later requests. Like the check itself, they are a snapshot: a role removed in Logto stops applying at the user's next sign-in. Logging out of the guard clears them.
1. Anyone who can sign in (default)
Without LOGTO_WEB_RESOURCE, LogtoWebClient::requiresResource() returns false and WebAuthController::withApiScope() never runs. The callback uses only the ID token: no access token is requested and no scopes are checked. Every Logto user who can sign in to the Traditional Web app gets a Laravel session, and is provisioned on their first sign-in.
LOGTO_WEB_ROUTES=true LOGTO_WEB_APP_ID=your-traditional-web-app-id LOGTO_WEB_APP_SECRET=your-app-secret
To restrict access at this level, either limit who can sign in through Logto's sign-in experience, or gate on your own data after sign-in:
// app/Providers/AppServiceProvider.php, in boot() Gate::define('access-admin', fn (User $user) => $user->is_admin); // routes/web.php Route::middleware(['auth', 'can:access-admin'])->group(function () { Route::get('/admin', AdminController::class); });
The package's Gate::before hook returns null for abilities the user has no OAuth scope for, so your own gates still run.
2. Require any of a set of permissions
Set LOGTO_WEB_RESOURCE to an API resource defined in Logto, and list the permissions to request in LOGTO_WEB_RESOURCE_SCOPES. The authorization request then includes a resource parameter and those permissions, Logto returns a JWT access token for that resource alongside the ID token, and withApiScope():
- Validates the access token with the resource as the audience.
- Requires its
subto match the ID token'ssub. - Refuses sign-in when its
scopeis empty, meaning the user holds none of the requested permissions.
In Logto, permissions are granted through roles, so this is how roles control who can sign in.
LOGTO_WEB_ROUTES=true LOGTO_WEB_APP_ID=your-traditional-web-app-id LOGTO_WEB_APP_SECRET=your-app-secret LOGTO_WEB_RESOURCE=https://admin.example.com LOGTO_WEB_RESOURCE_SCOPES="admin:viewer admin:editor"
Here a user with either admin:viewer or admin:editor gets in. That suits apps where several roles should have access, each granting a different permission.
In the Logto console:
- Under API resources, create a resource whose identifier matches
LOGTO_WEB_RESOURCE. - Add the permissions to it, for example
admin:viewerandadmin:editor. - Under Roles, create roles with those permissions and assign them to the users who should get in.
A user without a matching role signs in to Logto successfully, but the callback throws a SignInException ("You do not have access to this application") and no Laravel session is created.
3. Require specific permissions
Level 2 accepts any of the listed permissions. To require particular ones, list them in LOGTO_WEB_REQUIRED_SCOPES (space-delimited). The user must hold every one, matched exactly, and may hold others too. Required scopes are requested automatically, so they don't need repeating in LOGTO_WEB_RESOURCE_SCOPES:
LOGTO_WEB_ROUTES=true LOGTO_WEB_APP_ID=your-traditional-web-app-id LOGTO_WEB_APP_SECRET=your-app-secret LOGTO_WEB_RESOURCE=https://admin.example.com LOGTO_WEB_REQUIRED_SCOPES="admin:access orders:admin"
Here a user whose roles grant only admin:access is refused. One who holds both admin:access and orders:admin gets in.
The two lists can be combined. With the settings below, every user must hold admin:access, and orders:admin is also requested so it reaches the user model for those who have it:
LOGTO_WEB_RESOURCE=https://admin.example.com LOGTO_WEB_RESOURCE_SCOPES="orders:admin" LOGTO_WEB_REQUIRED_SCOPES="admin:access"
The request sent to Logto is then scope=openid profile email orders:admin admin:access.
At levels 2 and 3 the access token's scopes are set on the user (when the model is OAuthScopable) for the callback request only. They are not stored in the session, so can:<scope> won't see them on later page requests. To authorize individual pages by permission, use your own gates as in level 1.
Testing your app
While the app is running unit tests (app()->runningUnitTests()), the package replaces OidcDiscoveryService with Testing\FakeOidcDiscoveryService. That service serves a fake discovery document and JWKS from memory, so a Bearer token in a test never makes a request to Logto. It does not use Http::fake(), so your own Http assertions are unaffected. LOGTO_ENDPOINT isn't needed in tests: the fake falls back to https://logto.test.
To call the real tenant from tests, turn the fake off:
LOGTO_TESTING_FAKE=false
The fake serves a generated public key. To exercise the full guard path (signature, issuer, audience, the empty-scope rejection, JIT provisioning), add InteractsWithLogto to your TestCase and send a real, signed token:
use Ratespecial\Logto\Testing\InteractsWithLogto; abstract class TestCase extends BaseTestCase { use InteractsWithLogto; } // In a test $this->actingAsLogto(['user:read'], ['sub' => 'alice', 'email' => 'alice@example.com']) ->getJson('/api/me') ->assertOk(); // Or build the token yourself; claims override the defaults (iss, aud, sub, iat, exp) $this->withToken($this->logtoToken(['aud' => 'https://other.example.com', 'scope' => 'user:read'])) ->getJson('/api/me') ->assertUnauthorized();
If a test only needs an authenticated user and not the token path, actingAs($user, 'logto') still works.
Development
QA is wired through Composer scripts:
composer qa # fix-style → phpstan → test composer test # PHPUnit (orchestra/testbench, in-memory SQLite) composer check-style # Laravel Pint --test composer phpstan # PHPStan level 6
License
MIT.