Cognito sign-in on a remote dev server
New to Nearhost? Install it and add a server first.
This guide gets Amazon Cognito sign-in working at https://local.myapp.com while your Laravel app runs on another machine. The worked example uses Laravel Socialite with the community socialiteproviders/cognito provider and Cognito’s managed login pages. The Cognito and Nearhost steps are the same for any stack.
The symptom
Section titled “The symptom”Cognito sends the browser back to your app at a callback URL you list on the app client. Every callback URL has to use HTTPS, with one exception: http://localhost, which Cognito allows for testing. When the app runs on your laptop, that exception is all you need.
When the app runs on a server or a VM, localhost in your browser is not where the app is. You can forward a port with ssh -L and use http://localhost:8080, and for one app that works. It stops being enough when:
- You run more than one app. Browsers do not separate cookies by port, so two apps on
localhostcan overwrite each other’s session cookies. - The app shares cookies across subdomains. An app that sets cookies for
myapp.com, or talks to an API on another subdomain, only behaves as it does on staging when it runs under that domain. - You want local dev to match staging. Staging’s callback is HTTPS on your domain. With
http://localhost, the scheme, the host and the cookie rules all differ from what you deploy. - The page uses browser APIs that need a secure context, such as service workers or the clipboard. Browsers count
http://localhostas secure, so these work there, but on any other name, such as the server’s own address, they need HTTPS.
A tunnel such as ngrok gives you HTTPS, but each new tunnel name is one more callback URL to add, and the app still builds its links from its own idea of where it lives. It also puts the app on the public internet while you work on it.
Nearhost serves the remote app on your laptop at a name you choose, with a trusted certificate, over SSH. The browser sees one stable HTTPS origin, and that is the origin you list on the Cognito app client.
Pick a name
Section titled “Pick a name”Use a name under a domain you own, such as local.myapp.com. It needs no DNS record: Nearhost points it at your laptop through /etc/hosts while the project is enabled. When the project is disabled, the name resolves as it normally would.
A real-domain name keeps the callback URL shaped like the one on staging and in production. Cognito’s documentation asks for HTTPS but does not say whether it accepts .test names, so this guide uses a domain you own.
Add the project
Section titled “Add the project”On the command line, give the name with --alias:
nearhost add --server mini '~/code/myapp' --alias local.myapp.comAdded myapp on mini at https://local.myapp.comStart it with `nearhost up`.A name that does not end in .test needs your approval, because it can hide the real site. Typing it with --alias counts as approval.
To keep the name with the project, put it in a .nearhostrc in the project’s root:
version: 1alias: local.myapp.comRun nearhost add without --alias, and it asks before using the name, since you did not type it:
$ nearhost add --server mini '~/code/myapp'Approving a name puts it in your hosts file on this machine, has Nearhost's local CA sign a certificate for it, and makes your browser send that site's cookies to this project.local.myapp.com on port 8080 (a real domain): approve? [y/N]See Add a project for the rest of the add flow, and Main name for how the name is approved and written to the hosts file.
Set up Cognito
Section titled “Set up Cognito”Use a user pool for development, separate from production’s. Its users, app clients and settings are its own.
- The pool needs a domain for its sign-in pages. In the Amazon Cognito console, open the user pool, then Domain under Branding. If there is no domain, choose Actions, then Create Cognito domain, and pick a prefix. The domain looks like
https://myapp-dev.auth.eu-west-2.amazoncognito.com. Either branding version, Managed login or Hosted UI (classic), works for this guide. - Open App clients and create an app client with the application type Traditional web application. That type gives the client a secret, which Socialite needs. You cannot add a secret to an existing client later, so if yours has none, create a new one. When it asks for a Return URL, enter
https://local.myapp.com/auth/cognito/callback. - Open the app client, then the Login pages tab. Under Managed login pages configuration, choose Edit.
- Check that Allowed callback URLs has
https://local.myapp.com/auth/cognito/callback. It must match the URL your app sends exactly:https, the host, the path, no trailing slash. - Add
https://local.myapp.com/to Allowed sign-out URLs. Cognito only sends people back after sign-out to a URL on this list. - Under Identity providers, keep the user pool’s own sign-in, or whichever providers your users sign in with. Under OAuth grant types, choose Authorization code grant. Under OpenID Connect scopes, choose
openid,emailandprofile. Save the changes.
Then set APP_URL in the app’s .env to the new name, and copy the domain and the app client’s ID and secret below it. The last two lines build on APP_URL, so they have to come after it:
APP_URL=https://local.myapp.com
COGNITO_HOST=https://myapp-dev.auth.eu-west-2.amazoncognito.comCOGNITO_CLIENT_ID=your-client-idCOGNITO_CLIENT_SECRET=your-client-secretCOGNITO_CALLBACK_URL="${APP_URL}/auth/cognito/callback"COGNITO_SIGN_OUT_URL="${APP_URL}/"These are the names in the provider’s README. COGNITO_HOST is the full domain with https:// and no trailing slash.
Set up the app
Section titled “Set up the app”Install the provider, which brings in Socialite:
composer require socialiteproviders/cognitoAdd the Cognito entry to config/services.php:
'cognito' => [ 'host' => env('COGNITO_HOST'), 'client_id' => env('COGNITO_CLIENT_ID'), 'client_secret' => env('COGNITO_CLIENT_SECRET'), 'redirect' => env('COGNITO_CALLBACK_URL'), 'logout_uri' => env('COGNITO_SIGN_OUT_URL'),],The README’s version also has a scope line. The provider does not read it, so this guide sets scopes in code instead.
Register the provider in the boot method of app/Providers/AppServiceProvider.php (Laravel 11 and later):
use Illuminate\Support\Facades\Event;use SocialiteProviders\Cognito\Provider;use SocialiteProviders\Manager\SocialiteWasCalled;
public function boot(): void{ Event::listen(function (SocialiteWasCalled $event) { $event->extendSocialite('cognito', Provider::class); });}Then add the routes to routes/web.php. The provider asks for openid and profile by default; scopes() adds email to them:
use Illuminate\Http\Request;use Illuminate\Support\Facades\Auth;use Illuminate\Support\Facades\Route;use Laravel\Socialite\Socialite;
Route::get('/auth/cognito/redirect', function () { return Socialite::driver('cognito')->scopes(['email'])->redirect();});
Route::get('/auth/cognito/callback', function () { $cognitoUser = Socialite::driver('cognito')->user();
// Find or create your user from $cognitoUser, then Auth::login($user).
return redirect('/dashboard');});
Route::post('/auth/cognito/logout', function (Request $request) { Auth::logout();
$request->session()->invalidate(); $request->session()->regenerateToken();
return redirect(Socialite::driver('cognito')->logoutCognitoUser());});logoutCognitoUser() sends the browser to Cognito’s sign-out page with COGNITO_SIGN_OUT_URL, and Cognito sends it back there.
With APP_URL set to https://local.myapp.com, the callback and sign-out URLs follow it. If you have cached the config, run php artisan config:clear.
Nearhost’s proxy ends HTTPS on your laptop and passes plain HTTP to the server, with X-Forwarded-Proto: https. Laravel ignores that header until it trusts the proxy, so it thinks the request was http://. The callback is unaffected while COGNITO_CALLBACK_URL is a full URL, because Socialite uses it as it is. A path such as /auth/cognito/callback would be built from the request instead, as http://, and Cognito would refuse it. What goes wrong either way is everything Laravel builds from the request: route() and url() links, the redirect to /dashboard after sign-in, and asset() URLs.
The fix is one line in the withMiddleware closure in bootstrap/app.php:
$middleware->trustProxies(at: '*');The WorkOS guide explains it, and what to list instead of '*' if the file also runs in production behind a known load balancer.
If the page loads its scripts from Vite at http://localhost:5173, that port needs a loopback route so your browser can reach it. See Dev servers and hot reload. If public/hot says http://[::1]:5173 instead, the forward answers there too from Nearhost 0.7.0. With an older Nearhost, see Vite on [::1].
On another stack the idea is the same. Use any OpenID Connect client with the pool’s domain and the app client’s ID and secret. Set the app’s public URL and its callback URL to https://local.myapp.com, and tell the framework to trust X-Forwarded-Proto from the proxy, so it builds https:// links and the callback URL it sends to Cognito matches the one you listed.
Check it works
Section titled “Check it works”Start the project with nearhost up, or from the interface, and open https://local.myapp.com/auth/cognito/redirect. You should land on Cognito’s sign-in page, and after signing in come back to https://local.myapp.com/auth/cognito/callback and on to the dashboard.
When it does not:
- Cognito shows an error page instead of the sign-in page. Usually the callback URL your app sent is not in Allowed callback URLs on the app client whose ID you use. Compare them character by character:
https, the host,/auth/cognito/callback, no trailing slash. Check thatCOGNITO_CALLBACK_URLandAPP_URLare what you expect. - You come back with
error=invalid_scopein the address. The app asked for a scope the app client does not allow. Addopenid,emailandprofileunder OpenID Connect scopes, or ask for fewer. - The callback fails with
InvalidStateException. Socialite keeps a state value in the session when you start sign-in, and refuses the callback when the session does not come back with it. Start sign-in athttps://local.myapp.com, not at another address for the same app, and leaveSESSION_DOMAINunset (null) or set it tolocal.myapp.com. A cookie set for another domain never reaches this one. - Links, the redirect after sign-in, or asset URLs use
http://. Laravel does not trust the proxy yet. AddtrustProxiesas above. Nearhost redirectshttp://to HTTPS, so a link may still seem to work, buthttp://scripts and styles on an HTTPS page are blocked as mixed content. Look for those warnings in the console. - Sign-out does not come back to
https://local.myapp.com/. Cognito only redirects to a URL in Allowed sign-out URLs. Check thatCOGNITO_SIGN_OUT_URLis on that list exactly, trailing slash included.
When you still need ngrok
Section titled “When you still need ngrok”Nearhost is local-only. The name works in your browser on your laptop, and nowhere else.
Cognito itself does not need to reach your app. The browser carries the sign-in there and back, and your server calls Cognito, not the other way round. Cognito’s hooks into sign-up and sign-in are Lambda triggers, which run in AWS, not webhooks sent to your app. Use a public tunnel when:
- Something in AWS calls your app. A Lambda trigger, or anything else running in AWS, cannot reach your laptop or your dev server. If a trigger calls your app’s API, point it at a tunnel.
- Someone outside needs the link. A colleague or a client cannot open
local.myapp.comfrom their machine.
You can run both: Nearhost for your own browser, and a tunnel just for whatever AWS has to call.