Next.js
Integrasi lengkap untuk Next.js (App Router). Semua langkah berjalan di server, lewat Route Handler, sehingga Client secret tidak pernah sampai ke browser.
1. Konfigurasi
Daftarkan aplikasi di konsol dengan Redirect URI https://belajar.contoh.id/auth/sso/callback, lalu simpan .env dari konsol di .env.local. Tambahkan SESSION_SECRET (string acak panjang) untuk menandatangani cookie sesi aplikasi.
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://belajar.contoh.id/auth/sso/callback
SESSION_SECRET=ganti-dengan-string-acak-panjangNEXT_PUBLIC_ pada variabel ini. Variabel dengan awalan itu ikut dikirim ke browser.Modul di bawah memakai paket server-only, supaya build gagal jika modul itu tidak sengaja diimpor dari Client Component:
npm install server-only2. Modul Sentra
lib/sentra.ts membuat URL /authorize dengan state dan PKCE, dan menukar kode dari server. Kodenya sama dengan Mulai cepat.
// lib/sentra.ts
import "server-only";
import { createHash, randomBytes } from "node:crypto";
export type SentraUser = {
sentra_id: string;
name: string;
picture: string | null;
credential: string;
roles: string[];
user_types: string[];
};
export function startSignIn() {
const state = randomBytes(24).toString("base64url");
const verifier = randomBytes(32).toString("base64url");
const challenge = createHash("sha256").update(verifier).digest("base64url");
const url = new URL("/authorize", process.env.SSO_BASE_URL);
url.search = new URLSearchParams({
response_type: "code",
client_id: process.env.SSO_APP_ID!,
redirect_uri: process.env.SSO_REDIRECT_URI!,
state,
code_challenge: challenge,
code_challenge_method: "S256",
}).toString();
return { url: url.toString(), state, verifier };
}
export async function exchangeCode(code: string, verifier: string): Promise<SentraUser> {
const basic = Buffer.from(`${process.env.SSO_APP_ID}:${process.env.SSO_CLIENT_SECRET}`).toString("base64");
const res = await fetch(`${process.env.SSO_API_URL}/oauth/token`, {
method: "POST",
headers: { Authorization: `Basic ${basic}` },
body: new URLSearchParams({
grant_type: "authorization_code",
code,
redirect_uri: process.env.SSO_REDIRECT_URI!,
code_verifier: verifier,
}),
});
if (!res.ok) throw new Error(`Sentra token exchange failed: ${res.status}`);
const { user } = (await res.json()) as { user: SentraUser };
return user;
}3. Route pengalihan
Route ini menyimpan state dan code_verifier di cookie httpOnly berumur 10 menit, lalu mengarahkan pengguna ke Sentra.
// app/auth/sso/redirect/route.ts
import { cookies } from "next/headers";
import { redirect } from "next/navigation";
import { startSignIn } from "@/lib/sentra";
export async function GET() {
const { url, state, verifier } = startSignIn();
(await cookies()).set("sentra_flow", `${state}.${verifier}`, {
httpOnly: true,
secure: process.env.NODE_ENV === "production",
sameSite: "lax",
path: "/",
maxAge: 600,
});
redirect(url);
}Tombol masuk berupa tautan biasa ke route ini. Gunakan <a>, bukan <Link>, karena <Link> bisa memanggil route ini lebih dulu saat prefetch.
<a href="/auth/sso/redirect">Masuk dengan Sentra</a>sameSite: "lax". Dengan strict, browser tidak mengirim cookie saat Sentra mengarahkan pengguna kembali, sehingga pemeriksaan state selalu gagal.Isi juga URL masuk aplikasi di konsol dengan https://belajar.contoh.id/auth/sso/redirect. Lihat Buka aplikasi dari Akun.
4. Callback
Callback memeriksa state, menangani penolakan, menukar kode, lalu membuat sesi aplikasi. Kode harus ditukar dalam 60 detik dan hanya bisa dipakai sekali.
// app/auth/sso/callback/route.ts
import { timingSafeEqual } from "node:crypto";
import { cookies } from "next/headers";
import { redirect } from "next/navigation";
import type { NextRequest } from "next/server";
import { exchangeCode, type SentraUser } from "@/lib/sentra";
import { createSession } from "@/lib/session";
import { findOrCreateUser } from "@/lib/users";
function sameText(a: string, b: string) {
const x = Buffer.from(a);
const y = Buffer.from(b);
return x.length === y.length && timingSafeEqual(x, y);
}
export async function GET(request: NextRequest) {
const params = request.nextUrl.searchParams;
const store = await cookies();
const [state, verifier] = (store.get("sentra_flow")?.value ?? "").split(".");
store.delete("sentra_flow");
if (!state || !verifier || !sameText(state, params.get("state") ?? "")) {
return new Response("Permintaan masuk tidak valid.", { status: 403 });
}
const error = params.get("error");
if (error) redirect(`/login?error=${encodeURIComponent(error)}`);
let user: SentraUser;
try {
user = await exchangeCode(params.get("code") ?? "", verifier);
} catch {
redirect("/login?error=sentra");
}
const account = await findOrCreateUser(user);
if (!account) redirect("/login?error=not_registered");
await createSession(account.id);
redirect("/");
}error=access_denied dan state yang sama. Galat lainnya ada di Kode galat.5. Tautkan lewat sentra_id
Cari pengguna lokal hanya berdasarkan sentra_id, jangan berdasarkan email, username, atau credential. Contoh dengan Prisma, dengan kolom sentraId yang unik dan boleh kosong:
// lib/users.ts
import "server-only";
import { db } from "@/lib/db";
import type { SentraUser } from "@/lib/sentra";
export async function findOrCreateUser(user: SentraUser) {
return db.user.upsert({
where: { sentraId: user.sentra_id },
update: { name: user.name },
create: { sentraId: user.sentra_id, name: user.name },
});
}// lib/users.ts
import "server-only";
import { db } from "@/lib/db";
import type { SentraUser } from "@/lib/sentra";
export async function findOrCreateUser(user: SentraUser) {
return db.user.findUnique({ where: { sentraId: user.sentra_id } });
}Pengguna lama bisa ditautkan sebelum masuk pertama kali dengan sentra_id dari hasil impor. Lihat Impor pengguna. user.roles berisi peran dari katalog aplikasi Anda; aplikasi Anda yang memutuskan apa artinya.
6. Sesi aplikasi
Sentra tidak memberikan refresh token, jadi sesi sepenuhnya milik aplikasi Anda. Jika Anda sudah memakai pustaka sesi, panggil saja dari callback. Contoh minimal tanpa pustaka, dengan cookie yang ditandatangani:
// lib/session.ts
import "server-only";
import { createHmac, timingSafeEqual } from "node:crypto";
import { cookies } from "next/headers";
const COOKIE = "app_session";
const MAX_AGE = 60 * 60 * 8; // 8 jam, Anda yang menentukan
function sign(value: string) {
return createHmac("sha256", process.env.SESSION_SECRET!).update(value).digest("base64url");
}
export async function createSession(userId: string) {
const value = `${userId}.${Math.floor(Date.now() / 1000) + MAX_AGE}`;
(await cookies()).set(COOKIE, `${value}.${sign(value)}`, {
httpOnly: true,
secure: process.env.NODE_ENV === "production",
sameSite: "lax",
path: "/",
maxAge: MAX_AGE,
});
}
export async function getSessionUserId(): Promise<string | null> {
const [userId, exp, mac] = ((await cookies()).get(COOKIE)?.value ?? "").split(".");
if (!userId || !exp || !mac) return null;
const expected = Buffer.from(sign(`${userId}.${exp}`));
const given = Buffer.from(mac);
if (expected.length !== given.length || !timingSafeEqual(expected, given)) return null;
return Number(exp) > Date.now() / 1000 ? userId : null;
}
export async function endSession() {
(await cookies()).delete(COOKIE);
}Baca sesi di Server Component atau Route Handler dengan await getSessionUserId().
7. Keluar
// app/auth/logout/route.ts
import { NextResponse, type NextRequest } from "next/server";
import { endSession } from "@/lib/session";
export async function POST(request: NextRequest) {
await endSession();
return NextResponse.redirect(new URL("/", request.url), 303);
}Ini hanya mengakhiri sesi aplikasi Anda. Sesi Sentra tetap berjalan, jadi masuk lagi tidak meminta kata sandi. Kirim prompt=login ke /authorize jika Anda ingin pengguna memasukkan kata sandi lagi. Parameter lengkapnya ada di Endpoint.