OCID Auth

Author: KroderDev

AGENTS.md

@@ -41,4 +41,12 @@ This repository contains the core package for building microservices using Larav
 
 - Keep pull requests small and focused to ease review.
 - Prefer expressive naming and add comments where logic is complex.
-- Any new feature should include corresponding tests.
+- Any new feature should include corresponding tests.
+
+## OIDC Integration (Keycloak-ready)
+
+- Tokens issued by any OpenID Connect provider can be validated via JWKS by setting `OIDC_ENABLED=true` and `OIDC_JWKS_URL` to the JWKS endpoint (for Keycloak: `/realms/{realm}/protocol/openid-connect/certs`). When JWKS is configured, `JWT_PUBLIC_KEY_PATH` becomes optional.
+- Map the authenticated user's identifier with `JWT_USER_IDENTIFIER_CLAIM` (defaults to `id`; set to `sub` when mirroring Keycloak) so permission lookups use the desired claim.
+- Use `OIDC_CLIENT_ID` to limit permission extraction to a specific client application. Override claim paths with `OIDC_CLIENT_ROLES_CLAIM`, `OIDC_PRIMARY_ROLES_CLAIM`, `JWT_ROLES_CLAIM`, or `JWT_PERMISSIONS_CLAIM` when the token payload is customized.
+- Disable redundant gateway lookups when roles and permissions are already embedded in the token by leaving `OIDC_PREFER_GATEWAY_PERMISSIONS=false`; set it to `true` if the gateway remains the authority.
+- Always run `composer test` after updating authentication flows—new coverage exists for the JWT middleware and JWKS resolver.

CHANGELOG.md

@@ -7,6 +7,11 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+### Added
+- JWKS support and configurable claim mapping for OpenID Connect-issued JWTs (Keycloak-ready).
+- New configuration toggles to align `ExternalUser` identifiers and reuse token roles/permissions without gateway calls.
+- PHPUnit coverage for the JWT middleware and JWKS validator.
+
 ### Changed
 - Added type hints to gateway utilities for stronger typing.
 - Sanitized JWT key logging in `GatewayGuard` to avoid exposing sensitive data.

src/Auth/ExternalUser.php

@@ -12,23 +12,56 @@ class ExternalUser extends Authenticatable implements AccessUserInterface
     use HasAccess;
     use Notifiable;
 
-    protected $attributes = [];
+    protected $guarded = [];
+
+    protected array $claims = [];
 
     public function __construct(array $attributes = [])
     {
         parent::__construct([]);
-        $this->attributes = $attributes;
+        $this->fillAttributes($attributes);
+    }
+
+    protected function fillAttributes(array $attributes): void
+    {
+        if (empty($attributes)) {
+            return;
+        }
+
+        $this->claims = $attributes['token_claims'] ?? $attributes;
+
+        if (isset($attributes['token_claims'])) {
+            unset($attributes['token_claims']);
+        }
+
+        $this->forceFill($attributes);
         $this->syncOriginal();
     }
 
+    public function setClaims(array $claims): void
+    {
+        $this->claims = $claims;
+    }
+
+    public function getClaims(): array
+    {
+        return $this->claims;
+    }
+
     public function getAuthIdentifierName()
     {
-        return 'id';
+        return config('microservice.auth.user_identifier_claim', 'id');
     }
 
     public function getAuthIdentifier()
     {
-        return $this->attributes[$this->getAuthIdentifierName()] ?? null;
+        $identifier = parent::getAuthIdentifier();
+
+        if ($identifier === null && $this->getAuthIdentifierName() !== 'sub') {
+            return $this->getAttribute('sub');
+        }
+
+        return $identifier;
     }
 
     public function getAuthPassword()

src/Auth/GatewayGuard.php

@@ -65,6 +65,9 @@ public function user(): ?AuthenticatableContract
         if ($data) {
             $model = $this->userModel;
             $user = new $model($data);
+            if (method_exists($user, 'setClaims')) {
+                $user->setClaims($data);
+            }
             if ($this->loadAccess && $user instanceof AccessUserInterface) {
                 $user->loadAccess($data['roles'] ?? [], $data['permissions'] ?? []);
             }
@@ -157,6 +160,9 @@ public function attempt(array $credentials = [], $remember = false): bool
         $userData = $response['user'] ?? $this->client->me($token);
         $model = $this->userModel;
         $user = new $model($userData);
+        if (method_exists($user, 'setClaims')) {
+            $user->setClaims($userData);
+        }
         if ($this->loadAccess && $user instanceof AccessUserInterface) {
             $user->loadAccess($userData['roles'] ?? [], $userData['permissions'] ?? []);
         }
@@ -183,6 +189,10 @@ public function loginWithToken(string $token, array $userData = [], bool $rememb
         $model = $this->userModel;
         $user = new $model($userData);
 
+        if (method_exists($user, 'setClaims')) {
+            $user->setClaims($userData);
+        }
+
         if ($this->loadAccess && $user instanceof AccessUserInterface) {
             $user->loadAccess($userData['roles'] ?? [], $userData['permissions'] ?? []);
         }

src/Http/Middleware/LoadAccess.php

@@ -33,6 +33,15 @@ public function handle(Request $request, Closure $next): Response
         }
 
         if ($user instanceof AccessUserInterface) {
+            $oidcConfig = config('microservice.auth.oidc', []);
+            $preferGateway = (bool) ($oidcConfig['prefer_gateway_permissions'] ?? false);
+
+            if (($oidcConfig['enabled'] ?? false) && ! $preferGateway) {
+                if (! empty($user->getRoleNames()) || ! empty($user->getPermissions())) {
+                    return $next($request);
+                }
+            }
+
             try {
                 $access = app(PermissionsClient::class)->getAccessFor($user);
                 $user->loadAccess(

src/Http/Middleware/ValidateJwt.php

@@ -4,6 +4,7 @@
 
 use Closure;
 use Illuminate\Http\Request;
+use Illuminate\Support\Arr;
 use Illuminate\Support\Facades\Auth;
 use Kroderdev\LaravelMicroserviceCore\Auth\ExternalUser;
 use Kroderdev\LaravelMicroserviceCore\Services\JwtValidator;
@@ -34,16 +35,20 @@ public function handle(Request $request, Closure $next): Response
 
         try {
             $decoded = $this->validator->decode($token);
+            $claims = $this->toArray($decoded);
+
+            $attributes = $this->buildUserAttributes($claims);
+
+            $user = new ExternalUser($attributes);
+            $user->setClaims($claims);
+
+            $roles = $this->extractRoles($claims);
+            $permissions = $this->extractPermissions($claims, $roles);
+
+            $user->loadAccess($roles, $permissions);
 
-            // Auth from JWT
-            $user = new ExternalUser(['sub' => $decoded->sub]);
-            $user->loadAccess(
-                $decoded->roles ?? [],
-                $decoded->permissions ?? []
-            );
             Auth::setUser($user);
             $request->setUserResolver(fn () => $user);
-
         } catch (\Throwable $e) {
             if ($request->expectsJson()) {
                 return response()->json(['error' => 'Invalid token', 'message' => $e->getMessage()], Response::HTTP_UNAUTHORIZED);
@@ -54,4 +59,177 @@ public function handle(Request $request, Closure $next): Response
 
         return $next($request);
     }
+
+    protected function toArray(mixed $value): array
+    {
+        if ($value instanceof \stdClass) {
+            $value = (array) $value;
+        }
+
+        if (! is_array($value)) {
+            return [];
+        }
+
+        foreach ($value as $key => $item) {
+            if ($item instanceof \stdClass || is_array($item)) {
+                $value[$key] = $this->toArray($item);
+            }
+        }
+
+        return $value;
+    }
+
+    protected function buildUserAttributes(array $claims): array
+    {
+        $attributes = $claims;
+        $identifierClaim = config('microservice.auth.user_identifier_claim', 'id');
+
+        if (! isset($attributes[$identifierClaim]) && isset($attributes['sub'])) {
+            $attributes[$identifierClaim] = $attributes['sub'];
+        }
+
+        if ($identifierClaim === 'id' && isset($attributes['sub'])) {
+            $attributes['id'] = $attributes['sub'];
+        }
+
+        return $attributes;
+    }
+
+    protected function extractRoles(array $claims): array
+    {
+        $roles = $this->resolveClaim($claims, config('microservice.auth.roles_claim'));
+
+        if (! empty($roles)) {
+            return $roles;
+        }
+
+        $primaryRoles = $this->resolveClaim(
+            $claims,
+            config('microservice.auth.oidc.primary_roles_claim', 'realm_access.roles')
+        );
+
+        return $primaryRoles;
+    }
+
+    protected function extractPermissions(array $claims, array $roles): array
+    {
+        $permissions = $this->resolveClaim($claims, config('microservice.auth.permissions_claim'));
+
+        if (! empty($permissions)) {
+            return $permissions;
+        }
+
+        $oidcConfig = config('microservice.auth.oidc', []);
+        $permissions = [];
+
+        if (($oidcConfig['map_client_roles_to_permissions'] ?? true)) {
+            $clientClaim = $this->clientRolesPath($oidcConfig);
+            $paths = array_unique(array_filter([
+                $clientClaim,
+                'resource_access.*.roles',
+            ]));
+            $permissions = $this->resolveClaim($claims, $paths);
+
+            if (empty($permissions) && isset($claims['resource_access']) && is_array($claims['resource_access'])) {
+                $permissions = $this->collectResourceRoles($claims['resource_access'], $oidcConfig['client_id'] ?? null);
+            }
+        }
+
+        if (empty($permissions) && ($oidcConfig['map_primary_roles_to_permissions'] ?? false)) {
+            $permissions = $this->resolveClaim(
+                $claims,
+                $oidcConfig['primary_roles_claim'] ?? 'realm_access.roles'
+            );
+        }
+
+        if (empty($permissions)) {
+            return $roles;
+        }
+
+        return $permissions;
+    }
+
+    protected function collectResourceRoles(array $resourceAccess, ?string $clientId): array
+    {
+        $roles = [];
+
+        if ($clientId && isset($resourceAccess[$clientId]['roles'])) {
+            $roles = $resourceAccess[$clientId]['roles'];
+        } else {
+            foreach ($resourceAccess as $data) {
+                if (! is_array($data) || empty($data['roles'])) {
+                    continue;
+                }
+                $roles = array_merge($roles, (array) $data['roles']);
+            }
+        }
+
+        return $this->normalizeAccessValues($roles);
+    }
+
+    protected function clientRolesPath(array $config): ?string
+    {
+        $path = $config['client_roles_claim'] ?? 'resource_access.*.roles';
+        $clientId = $config['client_id'] ?? null;
+
+        if ($clientId) {
+            if (str_contains($path, '%s')) {
+                return sprintf($path, $clientId);
+            }
+
+            if (str_contains($path, '{client}')) {
+                return str_replace('{client}', $clientId, $path);
+            }
+        }
+
+        if (! $clientId && (str_contains($path, '%s') || str_contains($path, '{client}'))) {
+            return 'resource_access.*.roles';
+        }
+
+        return $path;
+    }
+
+    protected function resolveClaim(array $claims, string|array|null $path): array
+    {
+        if (empty($path)) {
+            return [];
+        }
+
+        $paths = (array) $path;
+        $values = [];
+
+        foreach ($paths as $claimPath) {
+            if (! $claimPath) {
+                continue;
+            }
+
+            $value = Arr::get($claims, $claimPath);
+            $values = array_merge($values, $this->normalizeAccessValues($value));
+        }
+
+        $values = array_values(array_unique($values));
+
+        return $values;
+    }
+
+    protected function normalizeAccessValues(mixed $value): array
+    {
+        if ($value === null) {
+            return [];
+        }
+
+        if (! is_array($value)) {
+            $value = [$value];
+        }
+
+        $items = [];
+
+        array_walk_recursive($value, function ($item) use (&$items) {
+            if (is_string($item) && $item !== '') {
+                $items[] = $item;
+            }
+        });
+
+        return $items;
+    }
 }