Neoistone Laravel Socialite

Neoistone SSO provider for Laravel Socialite.

This package allows Laravel applications to authenticate users through Neoistone SSO using OAuth 2.0 and OpenID Connect.

Features

• OAuth 2.0 Authorization Code flow
• OpenID Connect
• PKCE S256
• OIDC discovery
• UserInfo endpoint
• Stable OIDC sub identity
• openid scope
• profile scope
• email scope
• Laravel Socialite compatible API
• Confidential clients
• Public clients
• HTTPS-first configuration

Requirements

• PHP 8.2+
• Laravel Socialite 5.x
• Laravel 10, 11 or 12
• Neoistone OAuth application

Installation

Install the package with Composer:

composer require neoistone/socialite

Neoistone Developer Console

Create an application from the Neoistone Developer Console.

You will receive:

Client ID
Client Secret

The client secret is displayed only once for confidential applications.

Store it securely.

Configuration

Add the following to .env:

NEOISTONE_CLIENT_ID=nso_xxxxxxxxxxxxxxxxx
NEOISTONE_CLIENT_SECRET=nss_xxxxxxxxxxxxxxxxx
NEOISTONE_REDIRECT_URI=https://example.com/auth/neoistone/callback
NEOISTONE_BASE_URL=https://login.neoistone.com

Add Neoistone to config/services.php:

'neoistone' => [
    'client_id' => env('NEOISTONE_CLIENT_ID'),
    'client_secret' => env('NEOISTONE_CLIENT_SECRET'),
    'redirect' => env('NEOISTONE_REDIRECT_URI'),
],

Provider Registration

For Laravel 11 and newer, register the provider in AppServiceProvider.

<?php

namespace App\Providers;

use Illuminate\Support\Facades\Event;
use Illuminate\Support\ServiceProvider;
use SocialiteProviders\Manager\SocialiteWasCalled;
use Neoistone\Socialite\NeoistoneProvider;

class AppServiceProvider extends ServiceProvider
{
    public function boot(): void
    {
        Event::listen(function (SocialiteWasCalled $event) {
            $event->extendSocialite(
                'neoistone',
                NeoistoneProvider::class
            );
        });
    }
}

Authentication

Create a login route:

use Laravel\Socialite\Facades\Socialite;

Route::get('/auth/neoistone', function () {
    return Socialite::driver('neoistone')
        ->scopes([
            'openid',
            'profile',
            'email',
        ])
        ->redirect();
});

Create the callback route:

Route::get('/auth/neoistone/callback', function () {
    $user = Socialite::driver('neoistone')->user();

    return [
        'id' => $user->getId(),
        'name' => $user->getName(),
        'email' => $user->getEmail(),
    ];
});

User Identity

Neoistone uses the OpenID Connect sub claim as the user's identity.

Example:

{
    "sub": "32dd0705-5457-4250-9093-ad26286e816d",
    "name": "Manikanta",
    "email": "manikanta@example.com",
    "email_verified": true
}

The Socialite user ID is:

$user->getId()

which corresponds directly to:

$user->getSub()

The package does not generate a new UUID for the user.

Applications should store the Neoistone subject in their local user table.

Example:

$user = User::updateOrCreate(
    [
        'neoistone_id' => $neoistone->getId(),
    ],
    [
        'name' => $neoistone->getName(),
        'email' => $neoistone->getEmail(),
    ]
);

Scopes

Supported scopes:

openid
profile
email

Example:

Socialite::driver('neoistone')
    ->scopes([
        'openid',
        'profile',
        'email',
    ])
    ->redirect();

OpenID Connect

The package uses Neoistone OpenID Connect discovery.

Discovery:

https://login.neoistone.com/.well-known/openid-configuration

JWKS:

https://login.neoistone.com/.well-known/jwks.json

The provider obtains the OAuth endpoints from the discovery document.

OAuth Endpoints

The Neoistone authorization server exposes:

Authorization:
https://login.neoistone.com/oauth/authorize

Token:
https://login.neoistone.com/oauth/token

UserInfo:
https://login.neoistone.com/oauth/userinfo

Discovery:
https://login.neoistone.com/.well-known/openid-configuration

JWKS:
https://login.neoistone.com/.well-known/jwks.json

PKCE

Neoistone requires PKCE using:

code_challenge_method=S256

The package handles PKCE internally.

Applications should not manually generate or send the code_challenge or code_verifier.

Confidential Clients

Confidential applications receive a client secret.

Example:

NEOISTONE_CLIENT_ID=nso_xxxxxxxxx
NEOISTONE_CLIENT_SECRET=nss_xxxxxxxxx

The secret must never be committed to source control.

Do not expose it to:

• JavaScript
• Browser code
• Mobile applications
• Public repositories
• Client-side environment variables

Public Clients

Public clients do not receive a client secret.

Examples include:

• SPAs
• Mobile applications
• Desktop applications

PKCE is required.

Security

The package communicates with Neoistone over HTTPS.

Client secrets should be stored using environment variables or a secure secrets manager.

Do not log:

• client secrets
• access tokens
• refresh tokens
• authorization codes
• PKCE code verifiers

Testing

Install development dependencies:

composer install

Run PHPUnit:

vendor/bin/phpunit

Run a specific test:

vendor/bin/phpunit tests/NeoistoneUserTest.php

License

This package is released under the MIT License.

See LICENSE.

Support

Neoistone:

https://neoistone.com

Neoistone Login:

https://login.neoistone.com