> ## Documentation Index
> Fetch the complete documentation index at: https://docs.didit.me/llms.txt
> Use this file to discover all available pages before exploring further.

# Panduan Integrasi Autentikasi: Arsitektur dan Go-Live

> Panduan arsitektur integrasi Autentikasi Didit: halaman hosted atau UI sendiri, penyimpanan token, cek backend, sesi, aplikasi native, dan go-live.

Panduan ini menjelaskan bagaimana integrasi Autentikasi Didit di lingkungan produksi tersusun, mulai dari pengalihan pertama hingga daftar periksa peluncuran produksi.
Mulailah dengan [panduan cepat](https://docs.didit.me/id/authentication/quickstart.md) jika Anda belum pernah mengautentikasi seseorang, dan gunakan panduan cepat platform untuk kode setiap SDK.

## Arsitektur

```mermaid theme={null}
sequenceDiagram
    participant App as Your app (browser or mobile)
    participant Hosted as Your Didit sign-in origin
    participant API as Your backend
    participant Webhook as Your webhook endpoint

    App->>Hosted: Open /sign-in (redirect_uri, state, PKCE challenge)
    Note over Hosted: Sign-in method, MFA,<br/>bot protection, verification
    Hosted-->>App: Redirect to redirect_uri with code and state
    App->>Hosted: POST /token/ (code, PKCE verifier)
    Hosted-->>App: Access token (5 min), ID token, refresh token
    App->>API: Request with Authorization: Bearer access token
    Note over API: Verify the signature<br/>with the cached JWKS
    API->>Hosted: GET /session/ before a sensitive action
    Hosted-->>API: Live session, or 401
    Hosted->>Webhook: auth.signup, auth.login, auth.new_device ...
```

Ada empat bagian yang terlibat:

| Bagian | Mengelola |
| - | - |
| Aplikasi Anda | Memulai sign-in, menyimpan PKCE verifier dan `state`, menyimpan token, dan mengirim token akses ke backend Anda. SDK menangani semuanya. |
| Asal autentikasi Anda | `https://<slug>.auth.didit.me` (atau [domain kustom](https://docs.didit.me/id/authentication/branding-and-custom-domain.md#domain-kustom) Anda): halaman yang di-hosting, endpoint token, sesi, penemuan, dan kunci penandatanganan. |
| Backend Anda | Memverifikasi token akses pada setiap permintaan yang dilindungi, memeriksa sesi sebelum tindakan sensitif, dan memutuskan apa yang boleh dilakukan pengguna. |
| Konsol dan webhook Didit | Konfigurasi, pengguna dan sesi mereka, event autentikasi, serta webhook `auth.*` yang dilanggani server Anda. |

Kunci API Didit dan rahasia tidak pernah boleh ada di aplikasi Anda: kunci yang dapat dipublikasikan bersifat publik, dan pertukaran kode dilindungi oleh PKCE sebagai pengganti rahasia klien.

## Halaman yang di-hosting atau layar Anda sendiri

Pilih tempat pengguna mengetik email, kata sandi, atau kode mereka.
Pengaturannya adalah `sign_in_ui` (`hosted` secara default, atau `own`), dan Anda dapat mengubahnya nanti.

| | Halaman yang di-hosting (direkomendasikan) | Layar Anda sendiri |
| - | - | - |
| Yang Anda bangun | Tombol masuk dan halaman callback. | Setiap layar dan setiap langkah perantara. |
| Metode | Semua metode, termasuk tautan ajaib, SSO perusahaan, dan passkey. | Kata sandi, kode email, kode telepon, MFA, dan tantangan perlindungan melalui metode headless SDK. Tautan ajaib hanya berjalan di halaman yang di-hosting. |
| Langkah berikutnya | Ditangani untuk Anda: MFA, pendaftaran MFA, tantangan perlindungan, dan verifikasi saat pendaftaran. | Layar Anda menangani `mfa_required`, `mfa_enrollment_required`, `protection_required`, dan `verification_required`. Lihat [metode masuk](https://docs.didit.me/id/authentication/sign-in-methods.md). |
| Merek | Logo, warna, dan teks Anda dari [branding](https://docs.didit.me/id/authentication/branding-and-custom-domain.md). | Sepenuhnya milik Anda. |
| Pengaturan | URL redirect. | URL redirect, ditambah origin web Anda di **Allowed origins**. |

Passkey terkait dengan origin yang digunakan untuk sign-in aplikasi Anda.
Metode passkey dari SDK hanya berfungsi di halaman yang disajikan dari origin tersebut, jadi pada layar Anda sendiri di domain lain, arahkan pengguna ke halaman yang di-hosting untuk passkey.

## Pilih SDK Anda

| Aplikasi Anda | Paket | Tempat penyimpanan token |
| - | - | - |
| Aplikasi web single-page | [`@didit-protocol/auth`](https://docs.didit.me/id/authentication/quickstarts/javascript) atau [`@didit-protocol/auth-react`](https://docs.didit.me/id/authentication/quickstarts/react) | Penyimpanan web atau memori di browser. Pertahankan Content Security Policy yang ketat. |
| Aplikasi web yang di-render di server | [`@didit-protocol/auth-nextjs`](https://docs.didit.me/id/authentication/quickstarts/nextjs) | Cookie HttpOnly yang diatur oleh server Anda. Halaman tidak pernah melihat token. |
| iOS | [`DiditAuth`](https://docs.didit.me/id/authentication/quickstarts/ios) | Keychain. |
| Android | [`me.didit:didit-auth`](https://docs.didit.me/id/authentication/quickstarts/android) | Penyimpanan yang dilindungi oleh Android Keystore. |
| React Native atau Flutter | [`@didit-protocol/auth-react-native`](https://docs.didit.me/id/authentication/quickstarts/react-native) atau [`didit_auth`](https://docs.didit.me/id/authentication/quickstarts/flutter) | Penyimpanan terlindungi milik platform, melalui modul native. |
| Backend apa pun | [SDK server](https://docs.didit.me/id/integration/server-sdks/overview.md), `verifyToken` dari `@didit-protocol/auth/server`, atau library JWT apa pun | Tidak ada yang perlu disimpan: server memverifikasi token yang diterimanya. |

Tanpa SDK, terapkan sendiri alur kode otorisasi dengan PKCE: [panduan cepat JavaScript](https://docs.didit.me/id/authentication/quickstarts/javascript.md#tanpa-sdk) menunjukkan seluruh kontrak.

## Lindungi backend Anda

Pemeriksaan sesi di frontend hanya mengontrol apa yang Anda tampilkan.
Backend Anda membuat setiap keputusan berdasarkan token yang sudah diverifikasi.

1. **Verifikasi token akses di setiap permintaan.** Periksa tanda tangan ES256 terhadap JWKS penerbit Anda, lalu `iss`, `aud`, `exp` dan `typ: at+jwt`, dan tolak token yang nilai `act`-nya bukan `null`, kecuali rute tersebut menerima [agen AI](https://docs.didit.me/id/authentication/agent-access.md). Lihat [verifikasi token di server Anda](https://docs.didit.me/id/authentication/tokens-and-jwks.md#verifikasi-token-di-server-anda).
2. **Periksa sesi yang aktif sebelum tindakan sensitif.** Token akses tetap berlaku hingga kedaluwarsa, selama maksimal 5 menit. `GET /session/` langsung gagal ketika sesi dicabut, tidak aktif atau kedaluwarsa, ketika pengguna diblokir, atau ketika sesi tidak lagi memenuhi kebijakan MFA Anda. Lihat [memeriksa sesi](https://docs.didit.me/id/authentication/tokens-and-jwks.md#periksa-sesi).
3. **Minta step-up saat tindakan berisiko.** Sebelum pencairan dana, penambahan rekening bank baru, atau perubahan email atau nomor telepon, tanyakan ke Didit apakah orang tersebut harus melakukan verifikasi ulang, dan bertindak hanya berdasarkan step-up yang `approved` dan dibaca langsung oleh backend Anda. Lihat [step-up sebelum tindakan sensitif](https://docs.didit.me/id/authentication/verified-identity.md#step-up-sebelum-tindakan-sensitif).
4. **Ambil `vendor_data` dari token yang sudah diverifikasi**, jangan dari kolom yang dikirim browser, dan gunakan untuk verifikasi serta transaksi milik orang tersebut.

## Sesi

| Peristiwa | Yang terjadi |
| - | - |
| Masuk | Sesi dimulai. Durasinya mengikuti `session_lifetime` Anda (30 hari secara bawaan), dan sesi berakhir lebih awal setelah `idle_timeout` tanpa aktivitas (1 hari secara bawaan). |
| Setiap beberapa menit | SDK menyegarkan token akses, yang berlaku paling lama 5 menit. Token refresh dirotasi: setiap token refresh hanya bisa dipakai sekali. |
| token refresh yang sudah dipakai dikirim lagi | Didit menganggapnya sebagai pencurian dan mengakhiri sesi. Lakukan hanya satu penyegaran pada satu waktu untuk setiap sesi. |
| Masuk di perangkat lain | Dengan `multiple_sessions: false`, sesi pengguna yang lain diakhiri. |
| Reset kata sandi | Setiap sesi diakhiri jika `revoke_on_password_change` aktif (secara bawaan). |
| Keluar | `DELETE /session/` mengakhiri sesi, lalu aplikasi Anda mengarahkan pengguna ke `post_logout_redirect_uri` Anda. |
| Tim Anda bertindak | Konsol dapat mencabut satu sesi, mengeluarkan pengguna dari semua sesi, atau memblokir pengguna. Lihat [panduan konsol](https://docs.didit.me/id/authentication/console.md#upaya-masuk-dan-sesi). |

Ubah durasi di **Authentication > Security and sessions**, atau melalui API di [pengaturan aplikasi](https://docs.didit.me/id/authentication/overview.md#pengaturan-aplikasi).

![Tampilan Active sessions di Didit Business Console, berisi daftar sesi yang sedang aktif beserta perangkat, lokasi, waktu mulai, aktivitas terakhir, waktu berakhir, dan tombol Revoke](https://mintcdn.com/didit-0f962782/RpqZjIB1GnUPdMTN/images/authentication/console-active-sessions.png?fit=max\&auto=format\&n=RpqZjIB1GnUPdMTN\&q=85\&s=098f6be31804b0af7c680e569f341bfb)

Authentication > Sign-ins > Active sessions, dengan Revoke pada setiap sesi.

## Aplikasi native

Didit mengarahkan pengguna kembali ke aplikasi native hanya melalui pengalihan HTTPS. Didit tidak menerima skema URL kustom.

* **iOS:** jadikan pengalihan sebagai domain terkait, dengan `webcredentials` di `apple-app-site-association` Anda.
* **Android:** jadikan pengalihan sebagai App Link, dengan `assetlinks.json` Anda.
* Daftarkan setiap URL pengalihan di bawah **Authentication > Security and sessions**, seperti callback web.

Untuk passkey di aplikasi Anda, daftarkan aplikasi yang berbagi passkey aplikasi Anda dengan `PUT native-apps/` pada [Authentication management API](https://docs.didit.me/id/authentication/set-up-by-api.md).
Didit kemudian mencantumkan aplikasi tersebut di `apple-app-site-association` dan `assetlinks.json` yang disajikannya pada origin yang digunakan untuk login.
`MANAGEMENT_BASE` adalah alamat API manajemen aplikasi Anda, dan kunci API dengan scope `authentication` pada **write** dapat melakukan panggilan tersebut.
Panggilan ini menggantikan kedua daftar, jadi kirim keduanya:

```bash theme={null}
curl --fail-with-body --request PUT "${MANAGEMENT_BASE}native-apps/" \
  -H "x-api-key: $DIDIT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "ios_app_ids": ["ABCDE12345.com.example.app"],
    "android_apps": [
      {
        "package_name": "com.example.app",
        "sha256_cert_fingerprints": ["14:6D:E9:83:C5:73:06:50:D8:EE:B9:95:2F:34:FC:64:16:A0:83:42:E6:1D:BE:A8:8A:04:96:B2:3F:CF:44:E5"]
      }
    ]
  }'
```

| Kolom | Aturan |
| - | - |
| `ios_app_ids` | Hingga 10 entri berisi Team ID dan bundle identifier Anda, misalnya `ABCDE12345.com.example.app`. |
| `android_apps` | Hingga 10 aplikasi, masing-masing dengan `package_name`-nya dan 1 hingga 5 sidik jari SHA-256 sertifikat penandatanganan. |

Panduan cepat [iOS](https://docs.didit.me/id/authentication/quickstarts/ios.md) dan [Android](https://docs.didit.me/id/authentication/quickstarts/android.md) menunjukkan implementasi di sisi aplikasi.

## Hubungkan verifikasi identitas dan pemantauan transaksi

Setiap orang memiliki satu nilai `vendor_data`, di dalam token dan sesi mereka.
Gunakan sebagai `vendor_data` saat Anda [membuat sesi verifikasi](https://docs.didit.me/id/sessions-api/create-session.md) atau [mengirimkan transaksi](https://docs.didit.me/id/transaction-monitoring/transactions.md), dan konsol menampilkan login, verifikasi, dan transaksi untuk orang yang sama.

* Untuk memverifikasi orang saat pendaftaran atau memverifikasi ulang sebelum pencairan dana tanpa membangun alur verifikasi, gunakan [identitas terverifikasi](https://docs.didit.me/id/authentication/verified-identity.md).
* Event login diteruskan secara otomatis ke [aturan event](https://docs.didit.me/id/transaction-monitoring/event-rules.md) dan tampilan deteksi penipuan. Jangan kirim event `auth.login` Anda sendiri untuk login yang sama.
* Login yang berhasil tidak pernah menyetujui verifikasi atau transaksi: tangani keputusan setiap produk secara terpisah.

Lihat [mempertahankan satu orang yang sama di seluruh produk](https://docs.didit.me/id/authentication/overview.md#satu-orang-di-seluruh-produk).

## Menerima event login

Daftarkan [tujuan webhook](https://docs.didit.me/id/integration/webhooks.md) ke tipe `auth.*` yang Anda butuhkan, misalnya `auth.new_device` atau `auth.account_locked`.
Lakukan deduplikasi berdasarkan `auth_event.event_id`, dan verifikasi tanda tangannya seperti pada setiap webhook Didit.
Lihat [event dan webhook](https://docs.didit.me/id/authentication/events-and-webhooks.md) untuk setiap tipe beserta payload-nya.

## Pindahkan pengguna yang sudah ada

Jika pengguna Anda sudah memiliki akun di platform identitas lain atau di database Anda sendiri, [impor mereka](https://docs.didit.me/id/authentication/migration.md) sebelum Anda mengalihkan proses masuk.
Impor hash kata sandi mereka jika sumbernya menyediakannya, pertahankan tautan akun sosial mereka, dan simpan ID pengguna Anda sebagai `external_id`, yang akan menjadi `vendor_data`.
Tidak ada yang berubah bagi mereka sampai Anda mengalihkan aplikasi Anda ke Didit.

## Daftar periksa peluncuran produksi

1. Autentikasi diaktifkan untuk aplikasi Live Anda di halaman **Products**.
2. URL pengalihan produksi `https://` dan origin yang diizinkan sudah didaftarkan pada aplikasi Live. Aplikasi Live tidak menerima alamat `http://`.
3. Setiap metode masuk sosial menggunakan ID klien dan rahasia aplikasi Anda sendiri: kredensial uji Didit hanya berfungsi di sandbox.
4. Konfigurasi produksi Anda memiliki kunci Live yang dapat dipublikasikan (`pk_live_`) dan penerbit Live Anda.
5. Kebijakan MFA, masa berlaku sesi, batas waktu tidak aktif, panjang kata sandi, dan kebijakan pendaftaran sudah sesuai dengan yang Anda inginkan. Lihat [pengaturan aplikasi](https://docs.didit.me/id/authentication/overview.md#pengaturan-aplikasi).
6. [Perlindungan bot](https://docs.didit.me/id/authentication/bot-protection.md) diaktifkan, dengan pemeriksaan kata sandi yang bocor.
7. Backend Anda memverifikasi setiap token akses, dan memanggil `GET /session/` sebelum tindakan sensitif.
8. Merek, teks halaman, serta tautan ke syarat dan ketentuan dan kebijakan privasi Anda sudah diatur. Jika Anda berencana menggunakan [domain kustom](https://docs.didit.me/id/authentication/branding-and-custom-domain.md#domain-kustom), aktifkan sebelum pengguna mulai menambahkan kunci sandi.
9. Tujuan webhook Anda berlangganan tipe `auth.*` yang Anda tangani.
10. Anda telah menguji pendaftaran, masuk kembali, pembatalan, lupa kata sandi, MFA, kedaluwarsa sesi, keluar, dan sesi yang dicabut pada aplikasi Live.

## Pemecahan Masalah

| Gejala | Penyebab dan solusi |
| - | - |
| Setiap rute runtime merespons `404` | Autentikasi nonaktif untuk aplikasi, atau alamat mencampur origin sandbox dan origin produksi. Aktifkan dari halaman **Products**, dan gunakan origin yang ditentukan oleh kunci publishable Anda. |
| Halaman masuk merespons `400` dan meminta Anda mendaftarkan alamat, atau `POST /authorize/` merespons `invalid_redirect_uri` | `redirect_uri` belum terdaftar persis: skema, host, port, path, dan query harus cocok karakter demi karakter. Lihat [URL redirect](https://docs.didit.me/id/authentication/overview.md#url-redirect). |
| Panggilan browser ke origin masuk Anda merespons `403` dengan `origin_not_allowed` | Origin web Anda belum ada di **Allowed origins**. Tambahkan tanpa path dan tanpa garis miring di akhir. |
| `POST /token/` merespons `invalid_grant` | Kode sudah pernah digunakan, lebih dari 60 detik sejak dibuat, atau dikirim dengan PKCE verifier atau `redirect_uri` yang berbeda. Untuk penyegaran token, token refresh sudah pernah digunakan, dan hal itu mengakhiri sesi. Mulai ulang proses masuk. |
| Masuk dengan kata sandi merespons `invalid_credentials` meskipun kata sandinya benar | Email belum diverifikasi, atau akun dikunci atau diblokir. Didit sengaja memberikan respons yang sama. Periksa orang tersebut di **Users**. |
| `GET /session/` merespons `401` | Sesi dicabut, tidak aktif atau kedaluwarsa, orang tersebut diblokir, token diganti melalui penyegaran, atau sesi tidak lagi memenuhi kebijakan MFA Anda. Segarkan token, atau minta orang tersebut masuk lagi. |
| Menambahkan passkey atau authenticator merespons `403 reauthentication_required` | Keduanya memerlukan sesi yang dibuat dalam 5 menit terakhir. Minta orang tersebut masuk lagi terlebih dahulu. |
| Permintaan kode telepon merespons `503 delivery_unavailable` | Kode tidak dapat dikirim. Biarkan orang tersebut mencoba lagi, atau tawarkan metode lain. |
| Panggilan merespons `429` | Anda mencapai batas laju. Coba lagi setelah waktu yang ditunjukkan di `Retry-After`. Lihat [batas laju](https://docs.didit.me/id/authentication/bot-protection.md#batas-laju). |
| Panggilan penyiapan dengan kunci API merespons `409 product_disabled` | Autentikasi nonaktif untuk aplikasi. Seseorang harus mengaktifkannya di konsol. |
| Panggilan merespons `403 plan_required` | Fitur, seperti peran kustom atau tautan pengaturan SSO perusahaan, memerlukan paket Scale atau Enterprise. Aplikasi sandbox mendapatkan fitur ini di paket apa pun. |
| Token gagal setelah Anda mengaktifkan domain kustom | Penerbit dan kunci publishable telah berubah. Salin kunci baru ke aplikasi Anda, lalu perbarui penerbit yang diperiksa backend Anda. |


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.