- How do I install and configure werk365/jwtauthroles in a Laravel app?
- Install it with Composer, publish the package config, register the guard driver, and add a guard entry in config/auth.php pointing at either a static PEM public key or the JWKS endpoint. It is a Laravel-native guard plus user provider, so it hooks into the framework's existing guard/provider model and the Auth::extend seam. A senior Laravel developer can get a working proof of concept in about a day.
- Which Laravel and PHP versions does this package support?
- The only release landed in February 2023, which puts it in the Laravel 9/10 era, so the safe zone is Laravel 9 or 10 on PHP 8.1 or 8.2. There is no visible CI matrix, and Laravel 11 and 12 changed service provider and skeleton conventions, so do not assume forward compatibility. Pin exact versions and verify against your actual runtime matrix before committing.
- Does werk365/jwtauthroles work with identity providers other than FusionAuth?
- It is designed for JWTs issued by an external identity provider and was tested with FusionAuth, but it is not an IdP-agnostic OIDC solution. The value proposition is role extraction from a token, so another provider will work only if its claim names, issuer and audience values, and signing setup match what the package expects. Confirm the claim mapping against a real token from your provider before relying on it.
- How are roles extracted from the JWT and used for authorization in Laravel?
- The package reads roles from the token and exposes them to Laravel's authorization system so you can guard routes or actions with role checks. Whether that surfaces as Gate abilities, a trait on the user model, or a raw claim array is something you should verify in the source before designing around it. Because it feeds the standard Gate/Policy layer, it stays composable with policies you already have.
- Should I use a static PEM public key or the JWKS endpoint?
- Use the JWKS endpoint for anything beyond a throwaway spike, because it accommodates signing-key rotation without redeploying a new PEM. A static PEM is simpler for a local proof of concept but will cause an authentication outage the moment the IdP rotates its key. Check how JWKS keys are cached, what the TTL is, and what happens on a kid cache miss.
- Does the package validate the iss and aud claims and restrict the signing algorithm?
- Signature verification alone is not enough, and the package documentation does not make strong guarantees here, so audit the validation path yourself. Confirm the algorithm is allow-listed to RS256 with no none or HS256 confusion, that the kid header is handled safely, and that iss, aud, exp and nbf are all checked with explicit clock leeway. This is where subtle defects become authentication bypasses, so treat the review as a gate rather than a formality.
- How do I test JWT authentication and role checks in CI without network access?
- Write integration tests using a fixed test key so your CI pipeline never calls the JWKS endpoint over the network. Mint tokens in the test suite with that key, including cases for expired tokens, wrong audience, wrong issuer, and missing roles. Also exercise the JWKS code path offline with a stubbed key set so caching and refresh behaviour is covered.
- Does the package persist users to the database or hydrate them purely from claims?
- It is a user provider that hydrates a user from the token, but whether it writes to Eloquent or builds the user entirely from claims should be verified in the source before you design around it. If you need first-login provisioning, such as creating a local user record the first time a token is seen, confirm the package handles that or add it yourself. This decision affects how you join JWTs to existing application data and permissions.
- Is werk365/jwtauthroles still maintained, and what should I do instead?
- The maintenance signal is poor: around 15 stars, zero dependents, a single release in February 2023, and a maintainer that appears to be an agency publishing an internal tool, with no visible CI or security disclosure process. Assume you own the code and pin exact versions. The most important integration decision is to register it behind your own named guard in AuthServiceProvider so call sites depend on the guard name, not the package namespace, which lets you later replace it with roughly 150 lines of firebase/php-jwt plus a cached JWKS fetcher without touching call sites.
- How do I handle signing key rotation with JWKS caching?
- Rehearse key rotation in staging: rotate the signing key at the IdP and confirm there is no authentication outage, including the window before the cache refreshes. Understand the cache TTL and what the package does when it sees an unknown kid, since a cache that never refreshes will reject valid tokens after rotation. Only promote to a production guard once that rotation drill passes.