README

NC Connect OAuth2 Provider for Laravel Socialite.

About

NcConnect is a Laravel Socialite provider for NC Connect, the authentication platform of the Government of New Caledonia. It implements the OpenID Connect protocol over the NC Connect V3 (Keycloak) infrastructure.

Features

OAuth2 / OpenID Connect authentication flow
Nonce validation on id_token (replay attack protection)
User profile with identity claims (name, email, birthdate, gender, etc.)
Typed accessors on the User object for NC Connect specific claims
Token refresh support (V3 tokens expire after 30 minutes)
Logout with post-redirect URI (RP-Initiated Logout)
Configurable authentication method (client_secret_basic or client_secret_post)
Automatic environment switching (production / development)

Requirements

PHP 8.2+
Laravel 10+
A registered NC Connect client (contact connect@gouv.nc)

Installation

composer require gecka/socialite-ncconnect

Configuration

Add to config/services.php:

'ncconnect' => [
    'client_id' => env('NCCONNECT_CLIENT_ID'),
    'client_secret' => env('NCCONNECT_CLIENT_SECRET'),
    'redirect' => env('NCCONNECT_REDIRECT_URI'),
    'force_dev' => env('NCCONNECT_FORCE_DEV'),
    'logout_redirect' => env('NCCONNECT_LOGOUT_REDIRECT'),
    'auth_method' => env('NCCONNECT_AUTH_METHOD', 'client_secret_basic'),
],

Register the provider

Laravel 11+ — in app/Providers/AppServiceProvider.php:

use Illuminate\Support\Facades\Event;
use SocialiteProviders\Manager\SocialiteWasCalled;
use SocialiteProviders\NcConnect\NcConnectExtendSocialite;

public function boot(): void
{
    Event::listen(SocialiteWasCalled::class, NcConnectExtendSocialite::class.'@handle');
}

Laravel 10 — in app/Providers/EventServiceProvider.php:

protected $listen = [
    \SocialiteProviders\Manager\SocialiteWasCalled::class => [
        \SocialiteProviders\NcConnect\NcConnectExtendSocialite::class.'@handle',
    ],
];

Usage

Authentication

// Redirect to NC Connect
return Socialite::driver('ncconnect')->redirect();

// Handle callback
$user = Socialite::driver('ncconnect')->user();

Refreshing tokens

Access tokens expire after 30 minutes in V3. Use the built-in refreshToken() method:

$token = Socialite::driver('ncconnect')->refreshToken($refreshToken);

$token->token;        // new access token
$token->refreshToken; // new refresh token
$token->expiresIn;    // expiry in seconds

Logout

The generateLogoutURL() method builds an RP-Initiated Logout URL.

// Basic logout (uses logout_redirect from config)
$logoutUrl = Socialite::driver('ncconnect')->generateLogoutURL();

// With id_token_hint (recommended — enables seamless logout)
$logoutUrl = Socialite::driver('ncconnect')->generateLogoutURL($idTokenHint);

// With a custom post-logout redirect URI
$logoutUrl = Socialite::driver('ncconnect')->generateLogoutURL($idTokenHint, 'https://example.com/logged-out');

// Without arguments and no logout_redirect config: returns the bare logout endpoint

The id_token_hint is available on the User object after authentication:

$user = Socialite::driver('ncconnect')->user();
$user->tokenId; // store this for logout

User object

The returned User object extends the Socialite base user with typed accessors for NC Connect claims:

Accessor	Return type	Description
`$user->id`	`string`	Unique identifier (sub)
`$user->email`	`?string`	Email address
`$user->isEmailVerified()`	`bool`	Whether the email is verified
`$user->getVerifiedLevel()`	`int`	Verification level (0 = unverified, 1 = declarative, 2 = digital)
`$user->getPreferredUsername()`	`string`	Display name
`$user->getGivenName()`	`string`	All given names
`$user->getFirstName()`	`string`	First given name only
`$user->getFamilyName()`	`string`	Family name
`$user->getBirthdate()`	`string`	Date of birth (YYYY-MM-DD)
`$user->getGender()`	`string`	Gender (male/female)
`$user->getBirthplace()`	`string`	Place of birth
`$user->tokenId`	`?string`	ID token hint (for logout)
`$user->token`	`string`	Access token
`$user->refreshToken`	`?string`	Refresh token
`$user->expiresIn`	`int`	Token expiry in seconds

All attributes are also accessible via $user->getRaw() for the full userinfo response.

Scopes

Default: openid, identite_pivot, profile, email

Available: openid, profile, email, birth, identite_pivot

Authentication methods

Method	Config value	Description
Client Secret Basic	`client_secret_basic` (default)	Credentials sent as Basic auth header
Client Secret Post	`client_secret_post`	Credentials sent in POST body

Configuration reference

Env variable	Description	Default
`NCCONNECT_CLIENT_ID`	OAuth2 client ID	—
`NCCONNECT_CLIENT_SECRET`	OAuth2 client secret	—
`NCCONNECT_REDIRECT_URI`	Callback URL after login	—
`NCCONNECT_LOGOUT_REDIRECT`	Redirect URL after logout	—
`NCCONNECT_FORCE_DEV`	Force dev endpoints in production	—
`NCCONNECT_AUTH_METHOD`	Authentication method	`client_secret_basic`

Upgrading

Migrating from NC Connect V2 to V3 (Keycloak)? See UPGRADE.md.

License

This project is released under the MIT License.

Authors

Adil Kachbat contact@akachbat.com
Laurent Dinclaux laurent@gecka.nc — Gecka

Built with 🥥 and ☕ by Gecka — Kanaky-New Caledonia 🇳🇨

gecka / socialite-ncconnect

Maintainers

Package info

Statistics

Security