Masuk dengan HRTG

Penyedia OpenID Connect standar, dengan setiap proses masuk berupa persetujuan biometrik di ponsel milik pengguna sendiri. Library yang sudah Anda pakai tetap berfungsi; tidak ada SDK yang perlu dipasang.

Beta

Terakhir diperbarui 2 Oktober 2026

Masuk dengan HRTG sedang dalam uji beta. Akses terbatas untuk penguji beta: ajukan akses sebelum Anda mulai membangun, dan perlu diingat bahwa detail di halaman ini masih dapat berubah.

Sekilas

Issuer: https://api.hrtg.me
Discovery: https://api.hrtg.me/.well-known/openid-configuration
Alur: Kode otorisasi dengan PKCE (S256)
Scope: openid wajib; email, profile
ID token: RS256 secara bawaan; EdDSA jika diminta
Autentikasi klien: client_secret_basic, client_secret_post atau private_key_jwt; untuk aplikasi tanpa client secret, tidak ada autentikasi klien dan PKCE wajib
Kode otorisasi: 60 detik, sekali pakai
Access token: 5 menit, hanya untuk membaca /oidc/userinfo

Cara kerjanya

1
Aplikasi Anda mengarahkan pengguna ke HRTG
Permintaan kode otorisasi standar dengan PKCE. Library Anda yang menyusunnya.
2
HRTG menanyakan siapa yang masuk
Tidak ada kata sandi dan tidak ada cookie login di HRTG. Browser pengguna menampilkan kode empat karakter.
3
Pengguna menyetujui di ponselnya
Dengan Face ID atau sidik jari, setelah memastikan kode di ponsel sama dengan kode di browser.
4
Aplikasi Anda menerima ID token
Library Anda menukar kode dan memverifikasi token. Anda membuat sesi Anda sendiri.

Ponsel Anda akan menampilkan kode ini

R4TX

Jika tidak cocok, tolak di ponsel Anda. Orang lain yang memulai proses masuk ini.

Contoh

Anda menerima identitas, tidak pernah isi brankas. ID token dan userinfo memuat siapa pengguna itu, dan hanya klaim yang Anda minta. Apa pun yang disimpan pengguna di brankas HRTG miliknya tidak akan pernah tersedia bagi aplikasi Anda.

Satu perbedaan praktis dari penyedia lain: lama langkah di tengah bergantung pada orangnya. Pengguna harus mengambil ponselnya terlebih dahulu. Beberapa pola yang mungkin biasa Anda pakai tidak tersedia, jadi mulailah dari Pastikan HRTG cocok untuk aplikasi Anda.

Pastikan HRTG cocok untuk aplikasi Anda

Baca bagian ini sebelum Anda merancang cara aplikasi Anda menangani sesi.

Tidak tersedia	Alasannya	Sebagai gantinya
Perpanjangan senyap (silent renewal) / refresh lewat iframe tersembunyi	Tidak ada cookie login yang bisa kami periksa tanpa bertanya kepada pengguna	Kelola sesi Anda sendiri dan atur masa berlakunya sesuai kebutuhan Anda
Refresh token	Kami hanya menerbitkan kode otorisasi	Mulai proses masuk baru saat sesi Anda berakhir
Single sign-on antaraplikasi	Setiap proses masuk adalah persetujuan baru di ponsel pengguna	Pengguna perlu menyetujui sekali untuk setiap aplikasi
Mengeluarkan pengguna dari semua aplikasi sekaligus	Kami tidak punya cara untuk menjangkau sesi Anda ataupun sesi aplikasi lain	Setiap aplikasi mengurus proses keluarnya sendiri

Jika produk Anda bergantung pada perpanjangan senyap atau pada kemampuan mengeluarkan pengguna dari semua aplikasi sekaligus, HRTG bukan penyedia yang tepat untuk produk tersebut.

Aplikasi yang hanya berjalan di browser: alur masuk tetap berfungsi, tetapi matikan automaticSilentRenew, checkSessionInterval dan apa pun yang berbasis iframe. Semuanya mengandalkan kemampuan yang tidak kami miliki dan akan terus mencoba ulang tanpa henti.

Sama sekali tidak didukung: implicit flow, hybrid flow, client credentials, password grant, device code.

Ajukan pendaftaran klien

Pendaftaran dilakukan berdasarkan permintaan. Kirimkan detail di bawah ini dan kami akan menerbitkan kredensial Anda. Setiap pendaftaran ditinjau langsung oleh seseorang di tim kami, karena kesalahan pada redirect URI adalah satu hal yang bisa mengubah endpoint proses masuk menjadi celah keamanan.

Detail	Yang perlu dikirim
Nama aplikasi	Nama yang dilihat pengguna saat menyetujui di ponselnya. Gunakan nama yang mereka kenal untuk produk Anda
Situs web	Host Anda, tanpa `https://` dan tanpa path: `acme.example`
Redirect URI	Setiap URI yang Anda perlukan, persis seperti yang dikirim library Anda. Lihat Daftarkan redirect URI secara persis
Yang perlu Anda ketahui tentang pengguna	Nama, alamat email, atau tidak satu pun
Tempat aplikasi Anda berjalan	Di browser atau di ponsel: public. Di server Anda sendiri: confidential. Untuk `private_key_jwt`, sertakan set kunci publik Anda
Aplikasi terkait	Aplikasi lain yang harus mengenali orang yang sama sebagai satu akun. Putuskan sekarang: ini tidak dapat diubah setelah ada yang masuk
Logo	Persegi, minimal 192×192. Opsional: kami menampilkan monogram jika Anda tidak punya logo

Kirimkan detailnya lewat email ke hello@hrtg.me. Tautan itu membuka pesan dengan kolom-kolom yang siap Anda isi.

Yang Anda terima

Sebuah client ID, misalnya acme-portal.
Sebuah client secret, tetapi hanya jika aplikasi Anda berjalan di server Anda sendiri. Kami menampilkannya sekali dan tidak akan pernah lagi: kami hanya menyimpan hash-nya dan tidak dapat memulihkannya. Segera simpan di pengelola rahasia (secret manager), jangan pernah di repositori Anda.

Daftarkan redirect URI secara persis

Inilah kesalahan yang paling sering terjadi.

https://acme.example/callback dan https://acme.example/callback/ adalah URI yang berbeda. Begitu pula …/callback dan …/callback?next=/home. Kirimkan string persis yang akan dipakai library Anda, termasuk garis miring di akhirnya.

HTTPS wajib.
http://localhost dan http://127.0.0.1 diizinkan di port mana pun, untuk pengembangan lokal dan untuk aplikasi native.
Wildcard tidak pernah diterima. Daftarkan setiap URI yang Anda perlukan, hingga sepuluh.

Daftarkan URI pengembangan dan URI produksi Anda sekaligus agar Anda tidak terhambat nanti.

Konfigurasikan library Anda

Next.js dengan Auth.js (NextAuth)

auth.ts

// auth.ts
import NextAuth from 'next-auth'

export const { handlers, auth, signIn, signOut } = NextAuth({
  providers: [
    {
      id: 'hrtg',
      name: 'HRTG',
      type: 'oidc',
      issuer: 'https://api.hrtg.me',
      clientId: process.env.HRTG_CLIENT_ID,
      clientSecret: process.env.HRTG_CLIENT_SECRET, // omit for a browser-only app
      checks: ['pkce', 'state'],
      authorization: { params: { scope: 'openid email' } },
    },
  ],
})

Tombol masuk

<button onClick={() => signIn('hrtg')}>Sign in with HRTG</button>

Redirect URI Anda adalah https://your-app.example/api/auth/callback/hrtg. Daftarkan string itu persis seperti tertulis.

Library lainnya

Setiap library yang sesuai standar membutuhkan beberapa nilai yang sama. Arahkan library ke discovery URL di Sekilas dan library akan mengonfigurasi dirinya sendiri, lalu atur client ID, client secret jika Anda punya, redirect URI, dan scope yang Anda perlukan.

Pengaturan yang sering keliru di library

PKCE harus aktif untuk aplikasi apa pun yang tidak memiliki client secret: aplikasi browser dan aplikasi seluler. Aplikasi sisi server yang memegang client secret boleh menonaktifkannya, meskipun kami menyarankan tetap mengaktifkannya. Jika aplikasi browser mendapat invalid_request saat masuk, hampir pasti inilah penyebabnya.

Biarkan algoritma ID token tetap RS256. Kami juga menyediakan EdDSA, tetapi library Spring Security dan Microsoft tidak dapat memverifikasinya dan gagal dengan pesan error yang tidak menyebutkan penyebabnya.

Aplikasi sisi server memilih cara membuktikan identitasnya. client_secret_basic dan client_secret_post sama-sama bekerja dengan client secret Anda. private_key_jwt justru menandatangani assertion singkat dengan kunci Anda sendiri (RS256, ES256 atau EdDSA), sehingga tidak ada shared secret sama sekali; kirimkan set kunci publik Anda saat pendaftaran. Isi aud pada assertion dengan issuer kami, https://api.hrtg.me. URL token endpoint juga diterima, tetapi issuer mencegah assertion Anda diputar ulang di server lain.

Gunakan sub sebagai kunci akun

Yang Anda minta	Yang Anda terima
`openid`	`sub`: pengenal tetap untuk orang ini, khusus di aplikasi Anda
`profile`	`name`
`email`	`email`, dan `email_verified` (selalu `true`: kami tidak menyimpan alamat yang belum terverifikasi)

Anda juga mendapatkan auth_time: saat pengguna benar-benar menyetujui di ponselnya, bukan saat token diterbitkan.

Orang yang sama mendapatkan sub yang berbeda di setiap aplikasi. sub di aplikasi Anda tidak dapat dicocokkan dengan catatan aplikasi lain, begitu pula sebaliknya. Ini memang disengaja.

Bagi aplikasi Anda, nilainya tidak pernah berubah, termasuk saat pengguna mengganti ponsel atau memulihkan akunnya.

Simpan sub. Jangan gunakan alamat email sebagai kunci akun. Orang bisa mengganti email, dan jika itu kunci Anda, akun mereka akan terlantar.

Jika Anda menjalankan beberapa aplikasi yang perlu mengenali orang yang sama sebagai satu akun, sebutkan hal itu dalam pendaftaran Anda (lihat Ajukan pendaftaran klien). Ini tidak dapat diubah setelah ada yang masuk.

Kelola sesi sendiri dan keluar secara lokal

Setelah Anda memverifikasi ID token, buat sesi Anda sendiri dan kelola sesi itu sendiri. Hanya itu seluruh integrasinya.

Access token yang kami terbitkan berlaku lima menit dan hanya dapat membaca satu endpoint, yaitu /oidc/userinfo yang standar. Token ini bukan kunci untuk API HRTG. Tidak ada API HRTG yang bisa dipanggil aplikasi. Baca semua yang Anda perlukan saat proses masuk, dan selesai.

Keluar hanya berlaku di aplikasi Anda. Hapus sesi Anda. Pengguna tetap masuk di aplikasi lainnya, dan kami tidak punya cara untuk menjangkau aplikasi tersebut.

Beri callback waktu yang cukup

Seseorang harus mengambil ponselnya, jadi lamanya proses masuk bergantung pada orang itu. Jangan pasang batas waktu yang singkat pada rute callback Anda.

Proses masuk yang tampak macet saat pengujian sebenarnya sedang menunggu seseorang menyetujuinya di ponsel.

Sebelum peluncuran

Pastikan HRTG cocok untuk aplikasi Anda
Ajukan pendaftaran klien
Daftarkan redirect URI secara persis
Konfigurasikan library Anda
Gunakan sub sebagai kunci akun
Kelola sesi sendiri dan keluar secara lokal
Beri callback waktu yang cukup

Saat terjadi masalah

Token endpoint kami mengembalikan invalid_grant yang sama untuk setiap masalah pada kode: salah, kedaluwarsa, dipakai ulang, atau dikirim dengan verifier atau redirect URI yang tidak cocok. Membedakannya akan membantu penyerang menebak, jadi pesannya tidak akan mempersempit kemungkinan. Client secret yang salah atau tidak ada dilaporkan terpisah, sebagai invalid_client. Sebagai gantinya, periksa daftar berikut:

Yang Anda lihat	Hampir selalu
Halaman error di situs HRTG sendiri, tanpa diarahkan kembali	Client ID Anda tidak dikenal, atau redirect URI tidak cocok persis. Kami tidak akan mengarahkan ke URI yang tidak dapat kami verifikasi
`invalid_grant` saat menukar kode	`code_verifier` tidak cocok dengan proses masuknya (atau dikirim untuk proses masuk yang tidak memakai PKCE); atau redirect URI yang Anda kirim saat menukar kode berbeda dari yang Anda kirim saat masuk; atau kode sudah berumur lebih dari 60 detik
`invalid_client`	Client secret salah, atau aplikasi sisi server sama sekali tidak mengirim client secret
`login_required`, seketika	Anda mengirim `prompt=none`. Ini tidak akan pernah berhasil di sini
`invalid_scope`	Anda tidak menyertakan `openid`. Scope lain yang tidak terdaftar untuk aplikasi Anda diabaikan, bukan ditolak; `scope` dalam respons token mencantumkan apa yang Anda dapatkan
Proses masuk “macet” saat pengujian	Seseorang harus menyetujuinya di ponsel. Prosesnya tidak macet

Kode kedaluwarsa dalam 60 detik dan hanya berlaku sekali. Menyerahkan kode yang sama dua kali terlihat persis seperti serangan, jadi kami langsung mencabut sesinya. Jika penukaran gagal, mulai proses masuk baru alih-alih mencoba ulang dengan kode yang sama.

Mendapatkan bantuan

Hubungi kami di hello@hrtg.me dengan menyertakan client ID Anda dan perkiraan waktu masalah itu terjadi. Untuk perubahan pada pendaftaran, caranya sama: redirect URI baru, scope baru, atau client secret yang dirotasi.