Hubungkan aplikasi Anda ke login Sassly

Cara kerja

1. Halaman dilindungiUser membuka halaman aplikasi Anda tanpa sesi lokal → aplikasi mengarahkan ke /auth/login.
2. Ke auth.sassly.aiSDK menyimpan state, nonce, dan PKCE di session, lalu redirect ke https://auth.sassly.ai/oauth/authorize.
3. Login (atau SSO)Bila user sudah login di aplikasi Sassly lain di browser yang sama, auth langsung kembali tanpa layar apa pun. Bila belum, user memilih akun Google.
4. CallbackAuth kembali ke /auth/callback membawa code. Aplikasi menukarnya server-to-server menjadi token dan memverifikasi ID token (RS256, JWKS).
5. Tautkan user lokalAkun Sassly (sub, mis. usr_…) dipetakan ke baris user aplikasi lewat kolom sassly_sub. Role, tenant, dan status aktif tetap urusan aplikasi.
6. RevalidasiTiap 5 menit SDK mengecek ulang sesi pusat. Logout, blokir, atau pencabutan sesi di pusat ikut mengeluarkan user dari aplikasi.

Persiapan

• PHP ≥ 8.1 dengan ekstensi curl, openssl, json; session PHP aktif.
• Folder cache yang bisa ditulis user PHP-FPM (untuk cache JWKS).
• Tabel user dengan kolom email dan penanda aktif.
• Data untuk admin Sassly: client_id (huruf kecil, angka, tanda minus, mis. kobe), URL production aplikasi, dan URL callback.

Endpoint discovery: https://auth.sassly.ai/.well-known/openid-configuration · kunci publik: /.well-known/jwks.json.

Aturan wajib

1. Salin SasslyAuthClient.php apa adanya. Jangan diedit per aplikasi; upgrade dengan mengganti seluruh file.
2. Jangan mematikan verifikasi TLS. Untuk sertifikat lokal self-signed, pakai opsi ca_file.
3. Token hanya masuk lewat handleCallback() (server-to-server). Jangan menerima token dari query string, form, atau JavaScript, dan jangan menaruh token di HTML/JS.
4. Tautkan user lewat email hanya bila email_verified === true dan baris lokal sassly_sub IS NULL. Jangan pernah menimpa sassly_sub yang sudah terisi.
5. Callback tidak boleh otomatis redirect ke /auth/login saat error atau saat user ditolak (redirect loop). Tampilkan halaman.
6. Cookie session aplikasi: nama unik per aplikasi, host-only (tanpa domain), HttpOnly, SameSite=Lax, Secure di HTTPS. Bila sebelumnya memakai cookie ber-domain=.sassly.ai, pakai nama baru.
7. Logout hanya lewat POST + CSRF.
8. redirect_uri di config harus identik dengan yang didaftarkan (tanpa normalisasi, termasuk slash akhir).
9. Setiap halaman, endpoint AJAX, dan unduhan file yang dilindungi memanggil sassly_require_login().
10. Client secret disimpan di .env aplikasi: tidak di-commit, tidak ditulis ke log, tidak ditempel ke chat.

1Daftarkan aplikasi

Hubungi admin Sassly dengan client_id, redirect URI, dan URL setelah logout. Admin menjalankan di server auth:

php bin/auth client:create --id=kobe --name="Kobe" --type=confidential \
  --redirect=https://kobe.sassly.ai/auth/callback --post-logout=https://kobe.sassly.ai/

client_secret (awalan sas_cs_) dicetak sekali; admin menaruhnya langsung di .env aplikasi. Redirect URI tambahan (mis. staging) didaftarkan dengan client:add-redirect. Aplikasi mobile memakai --type=public (PKCE tanpa secret, refresh token dirotasi).

2Pasang file

Unduh lalu letakkan di aplikasi (sesuaikan path bila struktur aplikasi berbeda). Jalankan php -l untuk setiap file setelah disalin.

• SasslyAuthClient.phpSDK v1.0.0 → lib/sassly-auth/. Jangan diedit.
• sassly_auth_bootstrap.phpLem SDK ↔ aplikasi → lib/sassly-auth/. Ubah hanya bagian ADAPT.
• sassly_auth_hooks.phpPemetaan user (satu-satunya logika khusus aplikasi) → lib/sassly-auth/.
• auth/login.phpRoute GET /auth/login.
• auth/callback.phpRoute GET /auth/callback (redirect URI terdaftar).
• auth/logout.phpRoute POST /auth/logout (CSRF).
• auth/choose.phpPilih ruang kerja — hanya aplikasi multi-tenant.
• api_bearer_example.phpContoh API dengan access token (opsional).
• migration_users_sassly_sub.sqlQuery cek + kolom sassly_sub.
• env.exampleVariabel konfigurasi.

Bootstrap Sassly di-include dari bootstrap aplikasi, sebelum output apa pun. Route template me-require bootstrap aplikasi lewat __DIR__ . '/../../bootstrap.php' — sesuaikan path itu (komentar ADAPT).

3Konfigurasi .env

SASSLY_AUTH_ISSUER=https://auth.sassly.ai
SASSLY_AUTH_CLIENT_ID=kobe
# Dicetak sekali oleh admin saat client:create (jangan di-commit)
SASSLY_AUTH_CLIENT_SECRET=
# Harus identik dengan redirect URI terdaftar
SASSLY_AUTH_REDIRECT_URI=https://kobe.sassly.ai/auth/callback
SASSLY_AUTH_POST_LOGOUT_REDIRECT_URI=https://kobe.sassly.ai/
# Bisa ditulis user PHP-FPM
SASSLY_AUTH_CACHE_DIR=/var/www/kobe/storage/cache/sassly-auth
SASSLY_AUTH_REVALIDATE_INTERVAL=300
# Unik per aplikasi, host-only, belum pernah dipakai dengan Domain=.sassly.ai
APP_SESSION_NAME=kobe_sid

Lokal (auth di http://127.0.0.1:8701): tambahkan SASSLY_AUTH_ALLOW_INSECURE_HTTP=1; untuk sertifikat self-signed pakai SASSLY_AUTH_CA_FILE. Tulis komentar di baris sendiri — sebagian loader .env menganggap # … setelah nilai sebagai bagian nilai.

Di sassly_auth_bootstrap.php, hanya bagian ADAPT yang diubah:

• sassly_auth_config() membaca dari sistem config aplikasi. PHP-FPM tidak melihat env shell — nilai harus sampai lewat loader .env aplikasi atau env[…] pool.
• sassly_session_name() mengembalikan nama session unik aplikasi.
• sassly_paths() berisi URL route auth yang sebenarnya.

Ganti session_start() aplikasi dengan sassly_session_start(), atau samakan parameter cookie-nya persis.

4Database

1. Jalankan query cek di migration_users_sassly_sub.sql. Email ganda di dalam satu tenant harus dibereskan dulu.
2. Tambahkan kolom penaut lewat mekanisme migrasi aplikasi:

ALTER TABLE users
    ADD COLUMN sassly_sub VARCHAR(36) CHARACTER SET ascii COLLATE ascii_bin NULL DEFAULT NULL;

-- (a) satu orang = satu baris user:
CREATE UNIQUE INDEX uq_users_sassly_sub ON users (sassly_sub);
-- (b) orang yang sama bisa punya baris di beberapa tenant (pakai halaman pilih ruang kerja):
-- CREATE INDEX ix_users_sassly_sub ON users (sassly_sub);

5Hooks aplikasi

File sassly_auth_hooks.php adalah satu-satunya tempat logika khusus aplikasi:

function sassly_find_or_link_users(array $identity): array
{
    $pdo = sassly_app_pdo();
    $sub = (string) $identity['sub'];
    $email = is_string($identity['email'] ?? null) ? strtolower(trim($identity['email'])) : '';

    if ($email !== '' && ($identity['email_verified'] ?? false) === true) {
        $pdo->prepare('UPDATE users SET sassly_sub = ? WHERE LOWER(email) = ? AND sassly_sub IS NULL')
            ->execute([$sub, $email]);
    }
    $st = $pdo->prepare('SELECT * FROM users WHERE sassly_sub = ? AND is_active = 1 ORDER BY id');
    $st->execute([$sub]);
    return $st->fetchAll(PDO::FETCH_ASSOC);
}

6Route login

• login.php — membuat state/nonce/PKCE lalu redirect ke auth. Bila sudah login, langsung ke return_to.
• callback.php — verifikasi, pemetaan user, lalu salah satu: login, halaman pilih ruang kerja, atau halaman 403 "Akun belum terdaftar" (tidak memulai sesi; tombol "Keluar / ganti akun" memakai id_token yang ditolak sebagai hint).
• logout.php — POST + CSRF → prepareLogout() → hancurkan session aplikasi → redirect ke logout auth (mengakhiri sesi pusat di browser itu).
• choose.php — hanya aplikasi multi-tenant; hapus bila tidak dipakai, beserta cabang count($users) > 1 di callback.

7Lindungi halaman & AJAX

// Di guard aplikasi (awal setiap halaman / endpoint AJAX / unduhan yang dilindungi):
$user = sassly_require_login();   // baris user lokal yang aktif, atau request berakhir di sini

sassly_require_login() sudah menangani: redirect ke login untuk halaman (GET menyimpan return_to), 401 JSON untuk AJAX (X-Requested-With: XMLHttpRequest atau Accept: application/json), dan 403 untuk user yang dinonaktifkan di aplikasi. Frontend menangani 401 di wrapper fetch global:

if (res.status === 401) {
    window.location = '/auth/login?return_to=' + encodeURIComponent(location.pathname + location.search);
}

Tombol keluar berupa form POST:

<form method="post" action="/auth/logout">
    <input type="hidden" name="csrf" value="<?= sassly_e(sassly_csrf_token()) ?>">
    <button type="submit">Keluar</button>
</form>

8API dengan access token (opsional)

Untuk endpoint yang dipanggil app mobile Sassly Suites atau aplikasi lain. Access token berlaku 15 menit, aud = sassly-api. Petakan user lewat sassly_sub saja (tanpa penautan email). Contoh lengkap: api_bearer_example.php.

$token = SasslyAuthClient::bearerTokenFromRequest();
try {
    $claims = sassly_auth()->verifyAccessToken((string) $token, 'sassly-api');
} catch (SasslyAuthException $e) {
    http_response_code($e->reason === 'insufficient_scope' ? 403 : 401);
    exit;
}
// $claims['sub'] → SELECT * FROM users WHERE sassly_sub = ? AND is_active = 1

Memanggil API Sassly lain dari aplikasi web: sassly_auth()->accessToken() mengembalikan access token yang masih berlaku (diperbarui otomatis).

9Pindah dari login lama

Simpan login lama di balik saklar config (AUTH_MODE=legacy|sassly) sampai integrasi terverifikasi di staging, lalu hapus kode dan secret Google OAuth lama aplikasi. Halaman login lama diarahkan ke /auth/login.

10Verifikasi

• Halaman dilindungi → login → kembali ke halaman semula.
• Sudah login di aplikasi Sassly lain → masuk tanpa layar login.
• Akun tidak terdaftar → 403 "Akun belum terdaftar"; "Keluar / ganti akun" berfungsi.
• User dinonaktifkan di DB aplikasi → request berikutnya 403, tanpa redirect loop.
• Baris yang tertaut ke sub lain tidak diambil alih.
• Akun dengan email_verified=false tidak tertaut otomatis; setelah sassly_sub diisi manual, akun itu bisa masuk.
• Browser yang masih menyimpan cookie session lama aplikasi tetap bisa login.
• Multi-tenant (bila ada) → halaman pilih ruang kerja.
• Logout → kembali ke halaman depan aplikasi; aplikasi lain keluar ≤ revalidate_interval.
• AJAX setelah sesi berakhir → 401 → frontend ke login.
• /auth/login?return_to=//evil.com → mendarat di /.
• GET logout dan POST tanpa CSRF ditolak.
• Tidak ada warning/notice PHP di log; tidak ada token di HTML/JS; cookie session tanpa Domain.

API SDK

Semua kegagalan berupa SasslyAuthException dengan ->reason, ->oauthError, dan ->returnTo — artinya ada di Troubleshooting.

Kontrak protokol (v1)

Endpoint

Waktu

Token endpoint

POST /oauth/token   Authorization: Basic base64(urlencode(client_id) ":" urlencode(client_secret))

grant_type=authorization_code&code=…&redirect_uri=…&code_verifier=…
→ {"access_token":"…","token_type":"Bearer","expires_in":900,"id_token":"…","refresh_token":"rt_…","scope":"openid email profile"}

grant_type=refresh_token&refresh_token=rt_…
→ {"access_token":"…","token_type":"Bearer","expires_in":900,"scope":"openid email profile"}
   (client confidential tidak menerima refresh token baru; client public menerima token baru setiap kali)

ID token & access token

Header JWT: {"alg":"RS256","typ":"JWT"|"at+jwt","kid":"…"}. Kunci RSA 2048; kunci baru diterbitkan di JWKS minimal 2 jam sebelum dipakai menandatangani.

Logout & identitas

• Dengan id_token_hint yang cocok dengan sesi di browser: logout langsung. Tanpa hint yang cocok: auth meminta konfirmasi.
• Yang dicabut: sesi pusat di browser itu + semua refresh token sesi itu. Aplikasi lain di browser yang sama keluar pada revalidasi berikutnya.
• Akun Google yang dihapus lalu dibuat ulang dengan email sama mendapat sub baru — jangan ditautkan otomatis ke baris yang sudah tertaut ke sub lama.
• Auth tidak menyimpan role, tenant, atau status aktif per aplikasi.

Troubleshooting

Berdasarkan SasslyAuthException->reason

Berdasarkan gejala

Untuk Claude Code

Skill sassly-auth-integration berisi SDK, template, kontrak, dan troubleshooting di atas, sehingga Claude Code bisa mengaudit aplikasi, menyusun rencana, dan memasang integrasi. Pasang lalu minta: "integrasikan login auth.sassly.ai ke aplikasi ini".

curl -fsSLO https://auth.sassly.ai/assets/sdk/sassly-auth-integration.zip
unzip -o sassly-auth-integration.zip -d ~/.claude/skills/