Laravel

Integrasi lengkap untuk aplikasi Laravel dengan sesi web: konfigurasi, route, pengalihan ke Sentra, callback yang memeriksa state, penukaran kode, penautan lewat sentra_id, dan sesi aplikasi.

1. Konfigurasi

Daftarkan aplikasi di konsol dengan Redirect URI https://api.belajar.contoh.id/auth/sso/callback, lalu salin .env dari konsol ke .env aplikasi Anda.

SSO_BASE_URL=https://sso.sentratechnology.com
SSO_API_URL=https://api.sso.sentratechnology.com
SSO_APP_ID=app_9fk2mq7xlr4tzw8nb3vh5cyd
SSO_CLIENT_SECRET=sec_...
SSO_REDIRECT_URI=https://api.belajar.contoh.id/auth/sso/callback

Tambahkan entri sentra di config/services.php:

'sentra' => [
    'base_url'      => env('SSO_BASE_URL'),
    'api_url'       => env('SSO_API_URL'),
    'app_id'        => env('SSO_APP_ID'),
    'client_secret' => env('SSO_CLIENT_SECRET'),
    'redirect_uri'  => env('SSO_REDIRECT_URI'),
],
Biarkan SESSION_SAME_SITE bernilai lax (bawaan Laravel). Dengan strict, browser tidak mengirim cookie sesi saat Sentra mengarahkan pengguna kembali, sehingga state tidak ditemukan dan callback selalu gagal.

2. Kolom sentra_id

Simpan sentra_id di tabel pengguna. Kolom ini unik dan boleh kosong, supaya pengguna lama tetap ada sampai ditautkan. Email dan kata sandi lokal dibuat opsional karena pengguna Sentra tidak membutuhkannya.

php artisan make:migration add_sentra_id_to_users_table
public function up(): void
{
    Schema::table('users', function (Blueprint $table) {
        $table->uuid('sentra_id')->nullable()->unique()->after('id');
        $table->string('email')->nullable()->change();
        $table->string('password')->nullable()->change();
    });
}

Tambahkan sentra_id ke $fillable di model User. Di Laravel 10 ke bawah, change() membutuhkan paket doctrine/dbal.

3. Route

Kedua route memakai middleware web (bawaan routes/web.php) karena state dan code_verifier disimpan di sesi.

use App\Http\Controllers\Auth\SentraController;

Route::get('/auth/sso/redirect', [SentraController::class, 'redirect'])->name('sso.redirect');
Route::get('/auth/sso/callback', [SentraController::class, 'callback'])->name('sso.callback');
Route::post('/logout', [SentraController::class, 'logout'])->middleware('auth')->name('logout');

Tombol masuk cukup berupa tautan ke route pengalihan:

<a href="{{ route('sso.redirect') }}">Masuk dengan Sentra</a>

Isi juga URL masuk aplikasi di konsol dengan https://api.belajar.contoh.id/auth/sso/redirect, supaya pengguna bisa membuka aplikasi Anda dari Akun Sentra. Lihat Buka aplikasi dari Akun.

4. Arahkan pengguna ke Sentra

Buat app/Http/Controllers/Auth/SentraController.php. Method redirect membuat state dan code_verifier PKCE, menyimpannya di sesi, lalu mengarahkan pengguna ke /authorize.

<?php

namespace App\Http\Controllers\Auth;

use App\Http\Controllers\Controller;
use App\Models\User;
use Illuminate\Http\Client\RequestException;
use Illuminate\Http\RedirectResponse;
use Illuminate\Http\Request;
use Illuminate\Support\Facades\Auth;
use Illuminate\Support\Facades\Http;
use Illuminate\Support\Str;

class SentraController extends Controller
{
    public function redirect(Request $request): RedirectResponse
    {
        $state = Str::random(40);
        $verifier = Str::random(64);
        $challenge = rtrim(strtr(base64_encode(hash('sha256', $verifier, true)), '+/', '-_'), '=');

        $request->session()->put(['sentra_state' => $state, 'sentra_verifier' => $verifier]);

        $url = config('services.sentra.base_url').'/authorize?'.http_build_query([
            'response_type'         => 'code',
            'client_id'             => config('services.sentra.app_id'),
            'redirect_uri'          => config('services.sentra.redirect_uri'),
            'state'                 => $state,
            'code_challenge'        => $challenge,
            'code_challenge_method' => 'S256',
        ]);

        return redirect()->away($url);
    }

5. Callback: periksa state, tukar kode

Sentra kembali ke Redirect URI dengan code dan state, atau dengan error dan state jika pengguna menolak. Periksa state lebih dulu, lalu tukar code dari server dalam 60 detik.

    public function callback(Request $request): RedirectResponse
    {
        $state = $request->session()->pull('sentra_state');
        abort_unless($state && hash_equals($state, (string) $request->query('state')), 403);
        $verifier = $request->session()->pull('sentra_verifier');

        if ($request->filled('error')) {
            return redirect()->route('login')->withErrors(['sso' => 'Masuk dengan Sentra dibatalkan.']);
        }

        try {
            $response = Http::asForm()
                ->withBasicAuth(config('services.sentra.app_id'), config('services.sentra.client_secret'))
                ->post(config('services.sentra.api_url').'/oauth/token', [
                    'grant_type'    => 'authorization_code',
                    'code'          => $request->query('code'),
                    'redirect_uri'  => config('services.sentra.redirect_uri'),
                    'code_verifier' => $verifier,
                ])
                ->throw();
        } catch (RequestException $e) {
            report($e);

            return redirect()->route('login')->withErrors(['sso' => 'Masuk dengan Sentra gagal. Coba lagi.']);
        }

        $user = $response->json('user');
Kode hanya bisa dipakai sekali. Jika penukaran gagal, jangan ulangi dengan kode yang sama; arahkan pengguna untuk masuk lagi. Arti setiap galat ada di Kode galat.

6. Tautkan lewat sentra_id dan buat sesi

Cari pengguna lokal hanya berdasarkan sentra_id. Jangan menautkan otomatis berdasarkan email, username, atau credential. Contoh ini membuat pengguna baru jika belum ada:

        $account = User::updateOrCreate(
            ['sentra_id' => $user['sentra_id']],
            ['name' => $user['name']],
        );

        Auth::login($account);
        $request->session()->regenerate();

        return redirect()->intended('/dashboard');
    }

    public function logout(Request $request): RedirectResponse
    {
        Auth::logout();
        $request->session()->invalidate();
        $request->session()->regenerateToken();

        return redirect('/');
    }
}

Hanya menerima pengguna yang sudah terdaftar di aplikasi Anda? Ganti updateOrCreate dengan pencarian biasa:

$account = User::firstWhere('sentra_id', $user['sentra_id']);

if (! $account) {
    return redirect()->route('login')->withErrors(['sso' => 'Akun belum terdaftar di aplikasi ini.']);
}

$account->update(['name' => $user['name']]);

Pengguna lama bisa ditautkan sebelum masuk pertama kali dengan sentra_id dari hasil impor. Lihat Impor pengguna.

7. Peran

$user['roles'] berisi kunci peran dari katalog Peran aplikasi Anda yang diberikan admin Sentra kepada pengguna ini. Anggap sebagai informasi: aplikasi Anda yang memutuskan apa artinya.

if (array_intersect($user['roles'], ['editor', 'penulis']) === []) {
    return redirect()->route('login')->withErrors(['sso' => 'Anda belum punya akses ke aplikasi ini.']);
}

8. Keluar

Route logout hanya mengakhiri sesi aplikasi Anda. Sesi Sentra tetap berjalan, jadi menekan Masuk dengan Sentra lagi akan langsung masuk tanpa kata sandi. Gunakan prompt=login di /authorize jika Anda ingin pengguna memasukkan kata sandi lagi. Parameter lengkapnya ada di Endpoint.