Aws Cognito Laravel Package

Getting Started

• Install with composer require ellaisys/aws-cognito and publish the config with php artisan vendor:publish --provider="Ellaisys\Cognito\Providers\CognitoServiceProvider". The published config/aws-cognito.php is the single most important file — it defines the guard, user model overrides, AWS credentials, user pool, client ID/secret, and route behaviour.
• Set the core env vars before anything else: AWS_ACCESS_KEY_ID, AWS_SECRET_ACCESS_KEY, AWS_DEFAULT_REGION, AWS_COGNITO_CLIENT_ID, AWS_COGNITO_CLIENT_SECRET, AWS_COGNITO_USER_POOL_ID. A region/pool mismatch is the most common "it just returns 400" cause.
• Run the package migrations if you are using its token/profile storage, and confirm the auth.php guard is pointed at the Cognito guard the package registers. If your users table differs from the package expectation, override the user model in the config rather than editing vendor code.
• First practical use case: wire up API-based login. Post credentials to the package's login route (or call the underlying auth trait/service directly from your own controller), receive the JWT/access/refresh/id tokens, and protect subsequent routes with the package middleware. This is the shortest path to a working end-to-end flow and validates that credentials, pool, and client secret are all correct.
• Where to look first, in order: the README usage section, config/aws-cognito.php, the registered routes (php artisan route:list filtered to the Cognito prefix), and the auth/management traits. The v2.0.9 architecture and flow diagrams in the repo documentation are worth reading before you build custom flows — they map the token lifecycle and management operations more clearly than the prose docs.

Implementation Patterns

• Guard + middleware for API auth. Configure the Cognito guard and apply the package's auth middleware to protected route groups. Treat the package as the token verifier and identity resolver; keep your own authorization (policies/gates) on top. Don't duplicate token validation in controllers.
• Service/trait calls over HTTP for internal flows. For registration, confirmation, password reset, and refresh, call the package's traits/services directly from your own controllers or jobs instead of round-tripping through the package's HTTP routes. This keeps flows testable and lets you shape responses for your frontend.
• Refresh strategy. Access tokens are short-lived. Store the refresh token server-side (or in an HttpOnly cookie for SPAs) and implement a dedicated refresh endpoint that calls the package's refresh action and rotates the stored tokens. Never ask the client to hold the client secret.
• User management from the backend. Use the package's management actions (create/disable/delete user, add to group, list users) inside admin controllers or Artisan/queue jobs. v2.0.9 added console command coverage for these actions, so the same operations are now exercised by the package's test suite — a good signal that the management surface is safer to build on, but still wrap them in your own try/catch and audit logging.
• Custom controllers, package routes off. Most production apps disable the package's built-in routes and implement their own thin controllers calling the services. Use the package routes for prototyping, then replace them so you control status codes, response shape, rate limiting, and throttling.
• Testing. v2.0.9 brings the package's own coverage above 50% with additional auth and management test cases and API route/endpoint testing. Mirror that in your app: fake the Cognito client in unit tests, and keep a small number of integration tests against a dedicated test user pool. Don't let your CI hit a shared production pool.
• Group/role mapping. Map Cognito groups to Laravel roles at login time rather than querying Cognito on every request. Cache the mapping on the user record and refresh it on token refresh.

Gotchas and Tips

• Config caching bites. After changing any AWS_COGNITO_* env var, run php artisan config:clear. Stale config cache is the number one cause of "wrong pool" behaviour in local dev.
• Exceptions are not uniform. Cognito returns different error codes for "user not confirmed", "password reset required", "invalid credentials", and "user disabled". Branch on the package's exception types/codes rather than catching a single generic exception, or you'll leak confusing messages to users.
• MFA and challenge flows are stateful. If you support MFA or NEW_PASSWORD_REQUIRED, you must carry the session/challenge state between requests. Model this explicitly (cache or signed token) instead of assuming login is a single request/response.
• Token verification edge cases. Clock skew, expired tokens, and tokens from a different app client all fail similarly. Log the decoded token claims (never the raw token) when debugging, and confirm aud/client_id and iss match your pool.
• Local development. There is no offline Cognito emulator worth relying on. Use a separate dev user pool and seeded test users, and gate integration tests behind an env flag so unit tests stay fast and hermetic.
• Extension points. Prefer overriding the user model, guard, and route prefix via config over subclassing internals. The package's public surface (config keys, service/trait methods, middleware aliases) is stable across 2.0.x; internal classes are not. Pin to ^2.0 and read the changelog before minor bumps — 2.0.9 itself is additive (tests, docs, diagrams, console coverage) and introduces no breaking changes.
• Debugging tip. When a call fails cryptically, drop down to the raw AWS SDK response in a tinker session using the same credentials from config. If the SDK call fails too, it's credentials/pool configuration; if the SDK succeeds and the package fails, it's package config or model binding.
• Docs are improving but thin in places. The v2.0.9 flow diagrams are the best reference for token lifecycle and management operations; cross-check behaviour against the package tests (now more comprehensive) when the README is ambiguous.