nsru/vanilla-oidc

Zero-boilerplate OIDC client for vanilla PHP using Authorization Code + Client Secret flow

1.0.0 2026-04-30 00:39 UTC

Requires

• php: >=8.1
• ext-curl: *
• ext-json: *
• ext-openssl: *

Requires (Dev)

• phpunit/phpunit: ^10.0

MIT

README

Zero-boilerplate OIDC client for vanilla PHP. ใช้ Authorization Code + Client Secret flow รองรับทุก OIDC provider (Authentik, Keycloak, Google, ฯลฯ) ไม่ต้องพึ่ง framework

Requirements

• PHP 8.1+
• ext-curl, ext-json, ext-openssl

Installation

composer require nsru/vanilla-oidc

How It Works

[User คลิก Login]
      │
      ▼
  login.php  ──→  [OIDC Provider]  ──→  callback.php  ──→  session
                  (Authentik ฯลฯ)                              │
                                                               ▼
                                                    ทุกหน้าที่ใช้ requireAuth()

1. login.php redirect ผู้ใช้ไป OIDC provider พร้อม state
2. Provider ส่ง ?code=xxx&state=xxx กลับมาที่ callback.php
3. callback.php แลก code เป็น token ด้วย client secret แล้วเก็บใน session
4. หน้าที่ต้อง login เรียก $auth->requireAuth() — redirect อัตโนมัติถ้ายังไม่ login

Quick Start

1. Generate ไฟล์ด้วยคำสั่งเดียว

php vendor/bin/oidc-install

ได้ไฟล์พร้อมใช้ใน auth-oidc/:

auth-oidc/
├── bootstrap.php          ← config หลัก แก้ค่า OIDC ที่นี่
├── login.php              ← ผู้ใช้คลิก "Login" ชี้มาที่นี่
├── callback.php           ← ใส่เป็น Redirect URI ใน OIDC provider
├── logout.php             ← ผู้ใช้คลิก "Logout" ชี้มาที่นี่
└── example-protected.php  ← ตัวอย่างหน้าที่ต้อง login ก่อนเข้า

Overwrite ไฟล์เดิม: php vendor/bin/oidc-install --force

2. แก้ค่าใน auth-oidc/bootstrap.php

$auth = new OidcClient([
    'issuer'        => 'https://auth.example.com/application/o/myapp/',
    'client_id'     => 'your-client-id',
    'client_secret' => 'your-client-secret',
    'redirect_uri'  => 'https://yourapp.com/auth-oidc/callback.php',
]);

3. ป้องกันหน้าที่ต้อง login

<?php
require 'auth-oidc/bootstrap.php';

$auth->requireAuth(); // redirect ไป login ถ้ายังไม่ได้ login

$user = $auth->getUser();
echo "Hello, " . $user->getName();
echo "Email: "  . $user->getEmail();

Configuration

Key	Required	Default	Description
issuer	✅	—	OIDC Issuer URL (ไม่มี trailing slash)
client_id	✅	—	Client ID จาก OIDC provider
client_secret	✅	—	Client Secret จาก OIDC provider
redirect_uri	✅	—	URL เต็มของ callback.php
scopes	—	['openid','profile','email']	OIDC scopes
session_prefix	—	'oidc_'	Prefix ของ session keys

API Reference

OidcClient

$auth->login(?string $redirectAfter = null): void

Redirect ผู้ใช้ไป OIDC provider บันทึก $redirectAfter ไว้ใน session เพื่อ redirect กลับหลัง login สำเร็จ

$auth->handleCallback(): UserInfo

ต้องเรียกที่ callback.php — ตรวจสอบ state, แลก code เป็น token, fetch user info, เก็บใน session Throws AuthException ถ้า state ไม่ตรงหรือ provider ส่ง error

$auth->requireAuth(?string $redirectAfter = null): void

Redirect ไป login ถ้ายังไม่ authenticated ถ้าไม่ส่ง $redirectAfter จะ redirect กลับ URL ปัจจุบัน

$auth->isAuthenticated(): bool

ตรวจสอบ session + token expiry รัน token refresh อัตโนมัติถ้า access token หมดอายุและมี refresh token

$auth->getUser(): UserInfo

ดึงข้อมูล user จาก session Throws AuthException ถ้ายังไม่ login

$auth->getAccessToken(): string

ดึง access token string สำหรับเรียก API อื่น Throws AuthException ถ้ายังไม่ login

$auth->logout(?string $redirectAfter = null): void

ล้าง session แล้ว redirect ไป OIDC end-session endpoint (ถ้ามี) พร้อม id_token_hint

UserInfo

$user->getSub(): string           // unique user ID (ไม่มีวันเปลี่ยน)
$user->getEmail(): ?string
$user->getName(): ?string         // full name
$user->getGivenName(): ?string    // ชื่อ
$user->getFamilyName(): ?string   // นามสกุล
$user->getPreferredUsername(): ?string
$user->get(string $claim): mixed  // custom claim ใดก็ได้
$user->toArray(): array           // ทุก claims

Error Handling

use Nsru\VanillaOidc\Exception\AuthException;   // login/state errors
use Nsru\VanillaOidc\Exception\TokenException;  // token exchange errors
use Nsru\VanillaOidc\Exception\OidcException;   // base class / network errors

try {
    $auth->handleCallback();
    header('Location: /dashboard.php');
    exit;
} catch (AuthException $e) {
    http_response_code(401);
    echo htmlspecialchars($e->getMessage());
} catch (OidcException $e) {
    http_response_code(502);
    echo htmlspecialchars($e->getMessage());
}

Authentik Setup

1. สร้าง Provider → OAuth2/OpenID Provider

   • Client type: Confidential
   • Redirect URI: https://yourapp.com/auth-oidc/callback.php

2. issuer URL หาได้จาก: Application → Provider → OpenID Configuration URL ตัด /.well-known/openid-configuration ออก เหลือแค่ base URL

$auth = new OidcClient([
    'issuer'        => 'https://authentik.example.com/application/o/myapp/',
    'client_id'     => 'xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx',
    'client_secret' => 'xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx',
    'redirect_uri'  => 'https://yourapp.com/auth-oidc/callback.php',
]);

Local Development

ทดสอบโดยไม่ต้อง publish ขึ้น Packagist — ใช้ path repository:

{
    "repositories": [
        { "type": "path", "url": "../packagist.nsru.vanilla-oidc" }
    ],
    "require": {
        "nsru/vanilla-oidc": "*"
    }
}

composer install
php vendor/bin/oidc-install

Composer จะ symlink package มาให้ แก้โค้ด package เห็นผลทันทีโดยไม่ต้อง reinstall

License

MIT