PHPackages                             mozhuilungdsuo/iam-client - 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. mozhuilungdsuo/iam-client

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

mozhuilungdsuo/iam-client
=========================

Laravel client package for the Nagaland IAM platform.

v1.0.6(1mo ago)070↓50%MITPHPPHP ^8.4

Since Jun 11Pushed 1mo agoCompare

[ Source](https://github.com/mozhuilungdsuo/iam-client)[ Packagist](https://packagist.org/packages/mozhuilungdsuo/iam-client)[ Docs](https://github.com/mozhuilungdsuo/iam-client)[ RSS](/packages/mozhuilungdsuo-iam-client/feed)WikiDiscussions main Synced 1w ago

READMEChangelog (7)Dependencies (26)Versions (8)Used By (0)

Nagaland IAM Client
===================

[](#nagaland-iam-client)

Laravel client package for applications that authenticate through the Nagaland IAM authorization server.

The package provides:

- OAuth2 authorization-code login with PKCE
- IAM callback/logout routes
- local user synchronization by IAM user id
- role and permission middleware
- cached role/permission lookup
- permission synchronization from the client application to IAM
- a facade for checking the current IAM user, roles, and permissions

Requirements
------------

[](#requirements)

- PHP 8.4+
- Laravel 13
- A running Nagaland IAM server
- An OAuth client registered in IAM for this application

Install
-------

[](#install)

install the package:

```
composer require mozhuilungdsuo/iam-client
```

Laravel auto-discovers the service provider and facade.

Publish Package Files
---------------------

[](#publish-package-files)

```
php artisan vendor:publish --tag=nagaland-iam-config
php artisan vendor:publish --tag=nagaland-iam-migrations
php artisan migrate
```

The migrations add `iam_user_id` and `is_iam_active` to the local `users` table. Synced IAM users are created with `is_iam_active = false` by default; the consuming client application decides when to activate them. The local application still has a user record for sessions and Laravel auth, but IAM remains the source of truth for identities, roles, and permissions.

Environment
-----------

[](#environment)

Add these values to the consuming application's `.env`:

```
APP_URL=http://localhost:8001

SESSION_DRIVER=database
SESSION_COOKIE=my_app_iam_client_session

IAM_DRIVER=oauth
IAM_URL=http://localhost:8000
IAM_CLIENT_ID=iam_client_id_from_iam
IAM_CLIENT_SECRET=plain_secret_shown_once_by_iam
IAM_REDIRECT_URI="${APP_URL}/iam/callback"
IAM_POST_LOGOUT_REDIRECT_URI="${APP_URL}"
IAM_APPLICATION_CODE=crs
IAM_CACHE_TTL=3600
IAM_VERIFY_ID_TOKEN=true
IAM_ID_TOKEN_LEEWAY=60
```

Use a unique `SESSION_COOKIE` for each local Laravel app. Browsers share cookies by hostname, not by port, so `localhost:8000` and `localhost:8001` will overwrite each other if both use Laravel's default `laravel-session` cookie.

By default, the package requests these OAuth scopes during login:

```
openid profile email roles permissions govt_employee_details

```

You can change the requested scopes in `config/nagaland-iam.php`:

```
'scopes' => [
    'openid',
    'profile',
    'email',
    'roles',
    'permissions',
    'govt_employee_details',
],
```

`IAM_VERIFY_ID_TOKEN=true` makes the package verify the OIDC `id_token` signature through the IAM server JWKS endpoint, then check issuer, audience, expiry, and subject before syncing the local user.

During login the package verifies:

- the `id_token` is signed with `RS256`
- the signing key exists in `/.well-known/jwks.json`
- `iss` matches `IAM_URL`
- `aud` matches `IAM_CLIENT_ID`
- `exp`, `nbf`, and `iat` are valid within `IAM_ID_TOKEN_LEEWAY`
- `sub` matches the user returned by `/oauth/userinfo`

After changing `.env`, clear cached config:

```
php artisan optimize:clear
```

IAM Server Setup
----------------

[](#iam-server-setup)

Before creating client applications, prepare the IAM server:

```
cd nagaland-iam
php artisan migrate
php artisan iam:oidc-keys
```

The migration adds per-client OAuth scope allowlists. The key command creates the RS256 key pair used for OIDC `id_token` signing and the JWKS endpoint.

In the IAM server admin panel:

1. Create or select an application, for example `crs`.
2. Create an OAuth client for that application.
3. Add this redirect URI:

```
http://localhost:8001/iam/callback

```

4. Add this post logout redirect URI:

```
http://localhost:8001

```

5. Enable these allowed scopes on the OAuth client:

```
openid profile email roles permissions govt_employee_details

```

6. Copy the generated `client_id` and plain client secret into the client app `.env`.
7. Assign users to the application and give them roles/permissions.

For production, run Laravel's scheduler so expired OAuth records are pruned:

```
php artisan schedule:work
```

Or configure cron to run:

```
php artisan schedule:run
```

For local development, keep hostnames consistent. Prefer `localhost` everywhere or `127.0.0.1` everywhere; do not mix them.

Routes
------

[](#routes)

The package registers these routes by default under the `iam` prefix:

```
GET  /iam/login
GET  /iam/callback
POST /iam/logout
GET  /iam/role-definitions

```

You can change the prefix or disable route registration in `config/nagaland-iam.php`:

```
'routes' => [
    'enabled' => true,
    'prefix' => 'iam',
    'middleware' => ['web'],
],
```

Redirect Guests To IAM
----------------------

[](#redirect-guests-to-iam)

In a Laravel 13 app, redirect unauthenticated users to the package login route from `bootstrap/app.php`:

```
use Illuminate\Foundation\Configuration\Middleware;
use Illuminate\Http\Request;

->withMiddleware(function (Middleware $middleware): void {
    $middleware->redirectGuestsTo(fn (Request $request): string => route('iam.login'));
})
```

Then visiting an auth-protected page like `/dashboard` will start IAM login automatically.

Protect Routes
--------------

[](#protect-routes)

Use normal Laravel auth middleware plus IAM role/permission middleware:

```
Route::middleware(['auth', 'iam.permission:crs.birth.create'])->group(function (): void {
    Route::post('/birth-records', StoreBirthRecordController::class);
});

Route::middleware(['auth', 'iam.role:CRS.Registrar'])->group(function (): void {
    Route::get('/registrar', RegistrarDashboardController::class);
});
```

For routes that must specifically require an active IAM session:

```
Route::middleware(['iam.auth'])->get('/iam-only', IamOnlyController::class);
```

`iam.auth` only checks the local Laravel session for a stored IAM token. It does not call IAM on every request.

Define Permissions
------------------

[](#define-permissions)

Create `config/iam-permissions.php` in the consuming app:

```