hytale-community / hytale-auth-laravel

v0.1.0 2026-09-14 18:08 UTC

Requires

• php: ^8.2
• guzzlehttp/guzzle: ^7.9|^8.0
• hytale-community/hytale-auth-php: ^0.1
• illuminate/http: ^11.0|^12.0|^13.0
• illuminate/routing: ^11.0|^12.0|^13.0
• illuminate/session: ^11.0|^12.0|^13.0
• illuminate/support: ^11.0|^12.0|^13.0

Requires (Dev)

• friendsofphp/php-cs-fixer: ^3.95
• orchestra/testbench: ^9.0|^10.0|^11.0
• phpunit/phpunit: ^11.0

MIT

• Grimille

• Authentication
• oauth
• oauth2
• laravel
• oidc
• laravel-auth
• laravel-package
• openid-connect
• hytale
• pkce

Published on Packagist.org on 2026-09-14 18:11 UTC

README

Laravel integration for Sign in with Hytale, built on top of hytale-community/hytale-auth-php.

This package provides the Laravel-specific layer for Hytale authentication:

• service container bindings
• configuration
• session storage for state, nonce and PKCE code_verifier
• redirect handling
• callback handling
• Laravel facade

All OAuth 2.0 / OpenID Connect logic remains in the framework-agnostic core package.

Package: hytale-community/hytale-auth-laravel

Requirements

• PHP 8.2+ (PHP 8.3+ with Laravel 13)
• Laravel 11, 12 or 13
• A Hytale third-party application

Installation

Install the package with Composer:

composer require hytale-community/hytale-auth-laravel

Laravel package discovery automatically registers the service provider and facade.

Configuration

Publish the configuration file:

php artisan vendor:publish --tag=hytale-auth-config

This creates:

config/hytale-auth.php

Then configure your Hytale application in .env:

HYTALE_AUTH_CLIENT_ID=your-client-id
HYTALE_AUTH_CLIENT_SECRET=your-client-secret
HYTALE_AUTH_REDIRECT_URI=https://example.com/auth/hytale/callback

For a public Hytale client, leave the secret empty:

HYTALE_AUTH_CLIENT_SECRET=

The redirect URI must exactly match one of the redirect URIs configured in your Hytale third-party application.

For local development, Hytale allows HTTP redirect URIs on localhost and 127.0.0.1.

Example:

HYTALE_AUTH_REDIRECT_URI=http://localhost:8000/auth/hytale/callback

Scopes

The default configuration requests the Hytale profile scope:

use HytaleCommunity\HytaleAuth\Scope;

'scopes' => [
    Scope::Profile,
],

The core SDK automatically adds openid.

Available scopes are:

Enum	Hytale scope
Scope::OpenId	openid
Scope::Profile	hytale:profile
Scope::SharedSource	account:shared_source
Scope::GameOwnership	account:game_ownership
Scope::ParentalManaged	account:parental_managed
Scope::Offline	offline

Use Scope::Offline only when your Hytale application is allowed to receive refresh tokens and your application actually needs long-lived Hytale access.

Quick start

Create a route that redirects the user to Hytale:

use HytaleCommunity\HytaleAuthLaravel\Facades\HytaleAuth;
use Illuminate\Support\Facades\Route;

Route::get('/auth/hytale', function () {
    return HytaleAuth::redirect();
});

Then create the callback route:

use HytaleCommunity\HytaleAuthLaravel\Facades\HytaleAuth;
use Illuminate\Http\Request;
use Illuminate\Support\Facades\Route;

Route::get('/auth/hytale/callback', function (Request $request) {
    $result = HytaleAuth::callback($request);

    $result->claims->subject;
    $result->claims->profileUuid;
    $result->claims->profileUsername;
});

That is enough to complete a validated Hytale OpenID Connect authentication flow.

What the package handles

When calling:

return HytaleAuth::redirect();

the package:

1. creates the Hytale authorization request
2. generates PKCE values
3. generates state
4. generates nonce
5. stores state, nonce and the PKCE code_verifier in the Laravel session
6. redirects the user to Hytale

When calling:

$result = HytaleAuth::callback($request);

the package:

1. retrieves the temporary OAuth values from the Laravel session
2. removes them from the session
3. validates the returned state
4. exchanges the authorization code using PKCE
5. validates the Hytale ID token
6. validates the token signature against Hytale JWKS
7. validates issuer, audience, expiration and nonce
8. returns an AuthenticationResult

The temporary OAuth session values are consumed once and cannot be reused for another callback.

Authentication result

The callback returns the core SDK's AuthenticationResult.

Validated Hytale identity claims are available through:

$result->claims->subject;
$result->claims->profileUuid;
$result->claims->profileUsername;
$result->claims->sharedSource;
$result->claims->gameOwnership;
$result->claims->parentalManaged;

Tokens are available through:

$result->tokens->accessToken;
$result->tokens->idToken;
$result->tokens->expiresIn;
$result->tokens->refreshToken;
$result->tokens->tokenType;

Hytale identity

The OpenID Connect sub claim should normally be used as the external Hytale account identifier for your application:

$result->claims->subject;

The sub value is:

• stable for your Hytale application
• application-specific
• different from the public Hytale profile UUID

The selected Hytale profile is available separately:

$result->claims->profileUuid;
$result->claims->profileUsername;

A typical application may therefore store:

hytale_sub
hytale_profile_uuid
hytale_username
hytale_verified_at

Do not use the username as a permanent identity key. Usernames may change.

Example Laravel login flow

The package intentionally does not create users or call Auth::login() automatically.

A typical application callback can look like this:

use App\Models\User;
use HytaleCommunity\HytaleAuthLaravel\Facades\HytaleAuth;
use Illuminate\Http\Request;
use Illuminate\Support\Facades\Auth;

public function callback(Request $request)
{
    $result = HytaleAuth::callback($request);

    $claims = $result->claims;

    $user = User::query()
        ->where('hytale_sub', $claims->subject)
        ->first();

    if ($user === null) {
        $user = User::create([
            'hytale_sub' => $claims->subject,
            'hytale_profile_uuid' => $claims->profileUuid,
            'hytale_username' => $claims->profileUsername,
            'hytale_verified_at' => now(),
        ]);
    } else {
        $user->update([
            'hytale_profile_uuid' => $claims->profileUuid,
            'hytale_username' => $claims->profileUsername,
            'hytale_verified_at' => now(),
        ]);
    }

    Auth::login($user);

    return redirect('/');
}

The application remains responsible for:

• user persistence
• account creation
• Laravel authentication
• cookies
• post-login redirects
• authorization rules

Using a controller

For real applications, using a controller is usually preferable to closures:

namespace App\Http\Controllers;

use HytaleCommunity\HytaleAuthLaravel\Facades\HytaleAuth;
use Illuminate\Http\RedirectResponse;
use Illuminate\Http\Request;

final class HytaleAuthController
{
    public function redirect(): RedirectResponse
    {
        return HytaleAuth::redirect();
    }

    public function callback(Request $request)
    {
        $result = HytaleAuth::callback($request);

        // Create or authenticate your local user...
    }
}

Routes:

use App\Http\Controllers\HytaleAuthController;
use Illuminate\Support\Facades\Route;

Route::get('/auth/hytale', [
    HytaleAuthController::class,
    'redirect',
]);

Route::get('/auth/hytale/callback', [
    HytaleAuthController::class,
    'callback',
]);

Accessing the core client

The underlying HytaleClient can be accessed when advanced functionality is needed:

$client = HytaleAuth::client();

For example, UserInfo:

$userInfo = HytaleAuth::client()->userInfo(
    $accessToken,
);

Refresh tokens:

$newTokens = HytaleAuth::client()->refresh(
    $refreshToken,
);

Token revocation:

HytaleAuth::client()->revoke(
    $refreshToken,
);

These methods are provided by hytale-community/hytale-auth-php.

Refresh tokens

Most applications using Hytale only for login do not need refresh tokens.

If your application only needs a verified Hytale identity, the selected Hytale profile and the Hytale username, you can authenticate the user once, create your own Laravel session and discard the Hytale OAuth tokens.

Use refresh tokens only when your application must access Hytale again later without requiring the user to sign in interactively.

If needed, add the offline scope:

use HytaleCommunity\HytaleAuth\Scope;

'scopes' => [
    Scope::Profile,
    Scope::Offline,
],

Hytale refresh tokens rotate on every successful refresh.

Always replace the previous refresh token with the new one:

$newTokens = HytaleAuth::client()->refresh(
    $storedRefreshToken,
);

$storedRefreshToken = $newTokens->refreshToken;

Do not reuse an old rotated refresh token.

Configuration reference

The default configuration file is:

<?php

declare(strict_types=1);

use HytaleCommunity\HytaleAuth\Scope;

return [

    'client_id' => env('HYTALE_AUTH_CLIENT_ID'),

    'client_secret' => env('HYTALE_AUTH_CLIENT_SECRET'),

    'redirect_uri' => env('HYTALE_AUTH_REDIRECT_URI'),

    'scopes' => [
        Scope::Profile,
    ],

    'session' => [
        'prefix' => 'hytale_auth',
    ],

];

The session prefix can be customized:

'session' => [
    'prefix' => 'my_hytale_login',
],

Dependency injection

The core Hytale client is registered in Laravel's service container.

You may inject it directly:

use HytaleCommunity\HytaleAuth\HytaleClient;

final class SomeService
{
    public function __construct(
        private readonly HytaleClient $hytale,
    ) {
    }
}

The Laravel manager can also be injected:

use HytaleCommunity\HytaleAuthLaravel\HytaleAuthManager;

final class HytaleLoginController
{
    public function __construct(
        private readonly HytaleAuthManager $hytale,
    ) {
    }
}

The facade is optional.

Error handling

OAuth errors returned by Hytale are provided by the core SDK:

use HytaleCommunity\HytaleAuth\Exception\OAuthException;
use HytaleCommunity\HytaleAuthLaravel\Facades\HytaleAuth;

try {
    $result = HytaleAuth::callback($request);
} catch (OAuthException $exception) {
    $exception->error;
    $exception->errorDescription;
}

Hytale may return errors including:

access_denied
invalid_scope
invalid_request
invalid_grant
invalid_client
unauthorized_client

The Laravel package may also throw when the temporary authentication session is missing or invalid.

This usually means the flow expired, the session was lost, or the callback was replayed.

Security

The package stores these values in the Laravel session during authentication:

• OAuth state
• OpenID Connect nonce
• PKCE code_verifier

They are removed when processing the callback.

Never expose a confidential Hytale client secret to frontend code.

Never use a Hytale username as the primary account identity.

Never parse Hytale access tokens. They are opaque.

Always use the validated identity claims returned by the SDK.

Redirect URIs must exactly match the values configured in your Hytale third-party application.

What this package does not do

This package intentionally does not:

• create Laravel users
• provide user migrations
• modify your User model
• call Auth::login()
• create Laravel sessions after authentication
• define mandatory routes
• persist Hytale tokens
• provide a custom guard
• provide Socialite integration
• impose logout behavior

Its responsibility ends once a validated AuthenticationResult has been returned.

This keeps the integration reusable and avoids making assumptions about your application's authentication architecture.

Architecture

The package is a thin Laravel adapter around:

hytale-community/hytale-auth-php

The core package handles:

OAuth 2.0
OpenID Connect
PKCE
state validation
nonce validation
token exchange
Discovery
JWKS
RS256 ID token validation
UserInfo
refresh tokens
token revocation

The Laravel package handles:

configuration
service container bindings
session persistence
redirect responses
callback integration
Laravel facade

This separation keeps the OAuth/OIDC implementation independent from Laravel.

Testing

Install dependencies:

composer install

Run the test suite:

composer test

The package uses Orchestra Testbench to test its Laravel integration.

OAuth/OIDC cryptographic behavior is tested in the core hytale-auth-php package and is intentionally not duplicated here.

Local development

When developing the package alongside a Laravel application, you can use a Composer path repository.

Example:

{
  "repositories": [
    {
      "type": "path",
      "url": "../hytale-auth-laravel",
      "options": {
        "symlink": true
      }
    }
  ]
}

Then:

composer require hytale-community/hytale-auth-laravel:@dev

This makes it possible to test changes directly inside a Laravel application before publishing a new version.

Related package

Framework-agnostic PHP SDK:

composer require hytale-community/hytale-auth-php

Packagist:

https://packagist.org/packages/hytale-community/hytale-auth-php

License

MIT