Laravel Passport Claims Laravel Package

Product Decisions This Supports

• Identity and authorization architecture. With Laravel Passport already issuing JWTs, this package lets you enrich those tokens with application-specific claims (tenant ID, organization, roles, permissions, plan tier, locale, feature flags). That turns the access token into a portable authorization artifact other services can trust without a round trip to the user database.
• Multi-tenancy strategy. Embedding a tenant_id or org_id claim is often the cheapest path to tenant-scoped APIs and service-to-service calls. This package makes it a config-level decision rather than a fork of Passport internals — a meaningful input to "single database vs. schema-per-tenant vs. database-per-tenant" discussions, because tenant context becomes available at the edge.
• Service-to-service and microservice boundaries. If you are splitting a Laravel monolith into services, downstream services need to know who the caller is and what they may do. Propagating claims in the token avoids building a user-lookup service on day one, which materially changes the sequencing of an extraction roadmap.
• Build vs. buy for token customization. The functional scope is narrow (a claim setter hooked into Passport's token issuance). The realistic alternatives are (a) this MIT package, (b) ~50–150 lines of in-house trait, or (c) replacing Passport with a full IdP. This is a genuine build-vs-buy call worth an explicit decision record, not a default "just write it ourselves."
• Third-party and OIDC compatibility. Partners and enterprise buyers increasingly expect standard claims (email, name, roles) in the ID/access token. This package supports satisfying those integration checklists without an identity migration.
• Latency and coupling trade-offs. Claims-in-token is a caching decision: you trade freshness for reduced per-request lookups. That trade-off belongs in the roadmap conversation about authorization performance, not buried in an engineering ticket.
• Roadmap signal for identity investment. Adoption here is a reasonable proxy for "we are staying on Passport." If the roadmap points toward SSO, social login at scale, or enterprise IdP federation, this package is a stopgap and the real decision is IdP selection.

When to Consider This Package

Consider adoption when all of the following hold:

• You are already running Laravel Passport as your OAuth2 server, on a currently supported Laravel version.
• You need a small, stable set of claims (tenant, roles, a few user attributes) — not dynamic, per-request policy evaluation.
• Downstream consumers (your own services, or trusted partners) can tolerate claims that are fixed for the token lifetime. Tokens are typically valid for hours; role changes and de-provisioning will not take effect until expiry or revocation.
• Your team accepts a single-maintainer, ~87-star dependency with a small issue surface. That is a real vendor-risk line item — mitigate with a pinned version and a documented in-house fallback.
• You want the change to be low-blast-radius and reversible. A custom claim setter is easy to strip out if the identity strategy changes.

Look elsewhere when:

• You are on Sanctum, session auth, or a non-Passport IdP — this package is Passport-specific and does nothing for you.
• You need short-lived or revocable claims, immediate permission revocation, or per-request authorization decisions. Bake-in-token claims are the wrong primitive; look at a policy service or introspection endpoint instead.
• You require enterprise identity features — SAML, SCIM provisioning, MFA policy, audit-grade identity logs. Move up to Keycloak, Auth0, Cognito, or Entra ID rather than extending Passport.
• You need custom signing keys, token encryption, or non-standard JWT structures — that is Passport-level work, not a claims helper.
• Your compliance posture requires actively maintained, security-reviewed dependencies with a support contract. MIT + one maintainer does not clear that bar; plan to vendor the code in-house.
• Token payload size is a concern (headers, gateways, mobile clients). Every added claim costs bytes on every request — worth measuring before you grow the claim set.

How to Pitch It (Stakeholders)

To executives: This is a small, free, MIT-licensed utility that lets our existing authentication system carry the context our applications need — which customer, which organization, which permissions — inside the login token itself. The business value is speed and cost avoidance: it unblocks multi-tenant scoping and service-to-service authorization without an identity-platform migration or a new vendor contract. The risk is deliberately contained — the package is narrow, the code is replaceable in-house in days, and the decision is fully reversible.

To engineering: It hooks into Passport's token issuance to add application claims to the JWT, so downstream services can authorize locally instead of calling back to the user store on every request. It is a thin layer over Passport, so the real design questions are ours, not the package's: which claims, how large the token gets, and how we handle staleness. Adopt with a pinned version and an owner; treat the maintainer as a single point of failure and keep a ~100-line in-house implementation as the documented fallback. Do not use it as a substitute for a real authorization service if we expect permissions to change within a token's lifetime.