Download the PHP package mozhuilungdsuo/iam-client without Composer

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

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

Install

install the package:

Laravel auto-discovers the service provider and facade.

Publish Package Files

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

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

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:

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

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:

IAM Server Setup

Before creating client applications, prepare the IAM server:

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:

4. Add this post logout redirect URI:

5. Enable these allowed scopes on the OAuth client:

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:

Or configure cron to run:

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

Routes

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

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

Redirect Guests To IAM

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

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

Protect Routes

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

For routes that must specifically require an active IAM session:

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

Define Permissions

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

Sync them to IAM:

Define Roles

Publish or create config/iam-roles.php in the consuming app:

The package exposes these definitions at:

IAM can use that endpoint to fetch role codes, names, descriptions, and suggested permission codes while creating roles for the application. The endpoint accepts requests that include the configured IAM_CLIENT_ID in the X-IAM-Client-Id header.

The package also registers Laravel gates for each permission code in config/iam-permissions.php, so you can use:

Facade Usage

NagalandIam::user() returns the local Laravel user. NagalandIam::iamUser() returns the full IAM userinfo payload stored during login.

When the govt_employee_details scope is granted, NagalandIam::govtEmpProfile() returns:

It returns null when IAM did not send a government employee profile.

Commands

Local Run Example

Run the IAM server:

Run the client app:

Open:

The browser should redirect to IAM, then back to:

and finally to the client dashboard.

Troubleshooting

• 404 on /oauth/authorize: make sure the IAM server is running, not the client app, on the URL in IAM_URL.
• 400 on /iam/callback: clear cookies and confirm both apps use unique SESSION_COOKIE names.
• Login loops: keep APP_URL, IAM_URL, and OAuth redirect URI on the same hostname style, for example all localhost.
• 403 on roles or permissions: make sure the OAuth client allows roles and permissions, then log out and log in again.
• Missing government employee profile data: make sure the OAuth client allows govt_employee_details and the package requests that scope, then log out and log in again.
• Missing id_token or JWKS errors: run php artisan iam:oidc-keys on the IAM server.
• Invalid OAuth client credentials: rotate or recreate the IAM OAuth client secret and update IAM_CLIENT_SECRET.
• redirect_uri is not registered: add the exact IAM_REDIRECT_URI value to the OAuth client in IAM.