Authorization

The package integrates with Laravel's Gate, enabling Blade directives to check roles and permissions.

@can('posts.create')
    <!-- user can create posts -->
@endcan

@cannot('permission:posts.delete')
    <!-- no delete rights -->
@endcannot

@canany(['role:admin', 'permission:posts.update'])
    <!-- admin or user with update permission -->
@endcanany

Use hasRole and hasPermissionTo methods on the authenticated user for programmatic checks:

if (auth()->user()->hasRole('admin')) {
    // ...
}

JWT Tokens and the Gateway Guard

Authentication is handled via JWT tokens validated by the JWT Authentication middleware or by the session-based Gateway Guard.

Refer to the linked pages for configuration details.

OIDC Tokens (Keycloak example)

When integrating with an OpenID Connect provider—such as Keycloak—enable JWKS support and claim mapping so the middleware can decode tokens and expose roles/permissions consistently:

• Set OIDC_ENABLED=true and point OIDC_JWKS_URL to the provider's JWKS endpoint (e.g. https://id.example.com/realms/<realm>/protocol/openid-connect/certs). The validator automatically honours key rotation.
• Align the user identifier with JWT_USER_IDENTIFIER_CLAIM. Using sub is recommended so permission lookups and audit logs reference the provider's subject.
• Populate the claims consumed by the middleware:
  • Primary roles are read from realm_access.roles by default.
  • Client roles are collected from resource_access.{client}.roles when OIDC_CLIENT_ID is provided; otherwise all client roles are flattened. Override via OIDC_CLIENT_ROLES_CLAIM or JWT_PERMISSIONS_CLAIM if your IdP uses custom mappers.
• Leave OIDC_PREFER_GATEWAY_PERMISSIONS=false to trust the token contents; set it to true when the API gateway remains the single source of truth and should always be queried by LoadAccess.
• Add custom protocol mappers in your IdP if you need explicit roles or permissions arrays in the token—JWT_ROLES_CLAIM and JWT_PERMISSIONS_CLAIM can then point to those flat claims.

After configuration, auth()->user()->hasRole() and hasPermissionTo() will reflect the role sets embedded in the OIDC token without extra network hops.