PHPackages                             wazobia/laravel-auth-guard - PHPackages - PHPackages  [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register)

1. [Directory](/)
2. /
3. [Authentication & Authorization](/categories/authentication)
4. /
5. wazobia/laravel-auth-guard

ActiveLibrary[Authentication & Authorization](/categories/authentication)

wazobia/laravel-auth-guard
==========================

JWT and Project authentication middleware for Laravel with JWKS support

v1.0.3(2mo ago)040MITPHPPHP ^8.0

Since Mar 4Pushed 2mo agoCompare

[ Source](https://github.com/wazobiatech/laravel-jwt-auth)[ Packagist](https://packagist.org/packages/wazobia/laravel-auth-guard)[ Docs](https://github.com/wazobiatech/laravel-jwt-auth)[ RSS](/packages/wazobia-laravel-auth-guard/feed)WikiDiscussions main Synced 1mo ago

READMEChangelogDependencies (18)Versions (4)Used By (0)

Laravel Auth Guard
==================

[](#laravel-auth-guard)

[![Laravel](https://camo.githubusercontent.com/1ef1586422f8fac90eab8078edf7fce9ab4d795dfc6e84d64a45a0fb130bd582/68747470733a2f2f696d672e736869656c64732e696f2f62616467652f4c61726176656c2d392532422532302537432532303130253230253743253230313125323025374325323031322d4646324432303f7374796c653d666f722d7468652d6261646765266c6f676f3d6c61726176656c266c6f676f436f6c6f723d7768697465)](https://camo.githubusercontent.com/1ef1586422f8fac90eab8078edf7fce9ab4d795dfc6e84d64a45a0fb130bd582/68747470733a2f2f696d672e736869656c64732e696f2f62616467652f4c61726176656c2d392532422532302537432532303130253230253743253230313125323025374325323031322d4646324432303f7374796c653d666f722d7468652d6261646765266c6f676f3d6c61726176656c266c6f676f436f6c6f723d7768697465)[![PHP](https://camo.githubusercontent.com/aad484e00fb351cf0422a5593ac12c9e59674716481a53430859d4f1a3221e51/68747470733a2f2f696d672e736869656c64732e696f2f62616467652f5048502d382e302532422d3737374242343f7374796c653d666f722d7468652d6261646765266c6f676f3d706870266c6f676f436f6c6f723d7768697465)](https://camo.githubusercontent.com/aad484e00fb351cf0422a5593ac12c9e59674716481a53430859d4f1a3221e51/68747470733a2f2f696d672e736869656c64732e696f2f62616467652f5048502d382e302532422d3737374242343f7374796c653d666f722d7468652d6261646765266c6f676f3d706870266c6f676f436f6c6f723d7768697465)[![Redis](https://camo.githubusercontent.com/a41c67022a622bfa4bdb336007aba0d9e07ec8de16eb31a3b32f1e71c1646ed2/68747470733a2f2f696d672e736869656c64732e696f2f62616467652f52656469732d52657175697265642d4443333832443f7374796c653d666f722d7468652d6261646765266c6f676f3d7265646973266c6f676f436f6c6f723d7768697465)](https://camo.githubusercontent.com/a41c67022a622bfa4bdb336007aba0d9e07ec8de16eb31a3b32f1e71c1646ed2/68747470733a2f2f696d672e736869656c64732e696f2f62616467652f52656469732d52657175697265642d4443333832443f7374796c653d666f722d7468652d6261646765266c6f676f3d7265646973266c6f676f436f6c6f723d7768697465)[![License](https://camo.githubusercontent.com/9218332452902d9e542a100d0af126fd3174a116456614d2cf093546a13783db/68747470733a2f2f696d672e736869656c64732e696f2f62616467652f4c6963656e73652d4d49542d677265656e2e7376673f7374796c653d666f722d7468652d6261646765)](https://camo.githubusercontent.com/9218332452902d9e542a100d0af126fd3174a116456614d2cf093546a13783db/68747470733a2f2f696d672e736869656c64732e696f2f62616467652f4c6963656e73652d4d49542d677265656e2e7376673f7374796c653d666f722d7468652d6261646765)

**Enterprise-grade JWT and Project authentication middleware for Laravel applications**

[Installation](#installation) • [Configuration](#configuration) • [Usage](#usage) • [GraphQL Support](#graphql-setup-lighthouse) • [Documentation](#documentation)

---

🎯 **Complete Feature Parity with Node.js Implementation**
---------------------------------------------------------

[](#-complete-feature-parity-with-nodejs-implementation)

### **Mercury GraphQL Integration**

[](#mercury-graphql-integration)

- ✅ **ServiceAuthService** - Complete CLIENT\_ID/CLIENT\_SECRET → Mercury GraphQL integration
- ✅ **generateToken()** - Service token generation using Mercury API
- ✅ **getServiceById()** - Dynamic service UUID lookup from Mercury
- ✅ **Proper Service Validation** - Validates service is in `enabled_services[]`

### **Advanced JWKS Management**

[](#advanced-jwks-management)

- ✅ **Per-tenant JWKS caching** - `jwks_cache:{tenantId}` pattern
- ✅ **Service JWKS endpoint** - Separate endpoint for service tokens
- ✅ **Auto-refresh on key miss** - Fetches fresh JWKS when key not found
- ✅ **Signature-based authentication** - Mercury API authentication

### **Redis Connection Management**

[](#redis-connection-management)

- ✅ **Graceful fallback** - Works with or without Redis
- ✅ **Health checking** - Automatic reconnection on failures
- ✅ **Per-tenant secret versioning** - Cached secret version validation

### **Complete GraphQL Directive Suite**

[](#complete-graphql-directive-suite)

- ✅ **@userAuth** - JWT user authentication with optional scopes
- ✅ **@projectAuth** - Platform/project token authentication with scopes
- ✅ **@serviceAuth** - Service-only authentication (CLIENT\_ID/CLIENT\_SECRET tokens only)
- ✅ **@combineAuth** - Dual authentication (User JWT + Platform token required)
- ✅ **@scopes** - Standalone granular permission validation

### **Configuration Management**

[](#configuration-management)

- ✅ **Comprehensive config file** - `config/auth-guard.php`
- ✅ **Environment fallbacks** - Config → env → defaults
- ✅ **Laravel standards** - Proper service provider, middleware registration

🎯 Features
----------

[](#-features)

- **JWT User Authentication** - Secure user authentication with RS512 algorithm and scope validation
- **Platform Token Authentication** - HMAC-based platform/project token validation with tenant isolation
- **Service Authentication** - CLIENT\_ID/CLIENT\_SECRET authentication for service-to-service communication
- **Combined Authentication** - Support for dual authentication (JWT + Platform/Project token)
- **Comprehensive Scope System** - Granular permission validation with scope inheritance and combination
- **JWKS Support** - Automatic public key rotation and caching with per-tenant isolation
- **GraphQL First** - Complete Lighthouse GraphQL integration with dedicated directives
- **Redis-Powered** - Fast token validation, caching, and revocation with Redis
- **Mercury Integration** - Full integration with Mercury GraphQL API for token management
- **Docker-Ready** - Seamless operation in containerized environments
- **Laravel Standards** - Follows Laravel conventions with service provider auto-discovery

---

📋 Table of Contents
-------------------

[](#-table-of-contents)

- [Requirements](#requirements)
- [Installation](#installation)
- [Configuration](#configuration)
    - [Environment Variables](#environment-variables)
    - [Redis Setup](#redis-setup)
    - [Service Provider](#service-provider)
- [GraphQL Setup](#graphql-setup-lighthouse)
- [Usage](#usage)
    - [REST API Routes](#rest-api-routes)
    - [GraphQL Schema](#graphql-schema)
    - [Resolvers](#graphql-resolvers)
- [Testing](#testing)
- [Troubleshooting](#troubleshooting)
- [Advanced Usage](#advanced-usage)
- [Support](#support)

---

⚙️ Requirements
---------------

[](#️-requirements)

RequirementVersionPHP`^8.0`Laravel`^9.0 | ^10.0 | ^11.0 | ^12.0`Redis`Latest`Predis or PhpRedis`Latest`Lighthouse GraphQL`^6.0 | ^7.0` *(optional)*---

📦 Installation
--------------

[](#-installation)

### Step 1: Install the Package

[](#step-1-install-the-package)

```
composer require wazobia/laravel-auth-guard
```

The service provider will be automatically registered via Laravel's package discovery.

### Step 2: Install Redis Client

[](#step-2-install-redis-client)

**Option A: Predis (PHP Redis client)**

```
composer require predis/predis
```

**Option B: PhpRedis Extension (Better Performance)**

```
# Ubuntu/Debian
sudo apt-get install php-redis

# Alpine Linux (Docker)
apk add php81-pecl-redis

# macOS
pecl install redis
```

### Step 3: Publish Configuration

[](#step-3-publish-configuration)

```
php artisan vendor:publish --tag=auth-guard-config
```

This creates `config/auth-guard.php` in your project.

---

🔧 Configuration
---------------

[](#-configuration)

### Environment Variables

[](#environment-variables)

Add these **mandatory** variables to your `.env` file:

```
# Mercury JWKS Service (REQUIRED)
MERCURY_BASE_URL=https://mercury.example.com
SIGNATURE_SHARED_SECRET=your_shared_secret_key

# Service Authentication (REQUIRED)
CLIENT_ID=your-service-client-id
CLIENT_SECRET=your-service-client-secret

# Redis Authentication Database (REQUIRED)
REDIS_AUTH_URL=redis://localhost:6379/5

# JWT Algorithm (REQUIRED)
JWT_ALGORITHM=RS512
```

**Optional Environment Variables:**

```
# Mercury Configuration
MERCURY_TIMEOUT=10
SIGNATURE_ALGORITHM=sha256

# Redis Standard Configuration
REDIS_CLIENT=predis
REDIS_URL=redis://localhost:6379/0
REDIS_HOST=redis
REDIS_PORT=6379
REDIS_PASSWORD=null
REDIS_DB=0

# Cache Settings
CACHE_EXPIRY_TIME=900
AUTH_CACHE_TTL=900
AUTH_CACHE_PREFIX=auth_guard

# Custom Headers
AUTH_JWT_HEADER=Authorization
AUTH_PROJECT_TOKEN_HEADER=x-project-token
```

Cache Settings
==============

[](#cache-settings)

CACHE\_EXPIRY\_TIME=900 AUTH\_CACHE\_TTL=900 AUTH\_CACHE\_PREFIX=auth\_guard AUTH\_CACHE\_DRIVER=redis

JWT Settings
============

[](#jwt-settings)

JWT\_ALGORITHM=RS512 JWT\_LEEWAY=0

Custom Headers (Optional)
=========================

[](#custom-headers-optional)

AUTH\_JWT\_HEADER=Authorization AUTH\_PROJECT\_TOKEN\_HEADER=x-project-token

Logging
=======

[](#logging)

AUTH\_GUARD\_LOGGING=true AUTH\_GUARD\_LOG\_CHANNEL=stack

```

> **💡 Docker Users:** If using Docker Compose, set `REDIS_HOST=redis` (the service name), not `127.0.0.1`

### Redis Setup

Update `config/database.php`:

```php