Belajar Keycloak - Integrasi SAML Service Provider

#Pendahuluan

Di episode 13 kalian menyalakan Keycloak sebagai SAML IdP: membuat SAML client, mengekspor metadata, dan mengatur kunci signing. Episode 14 ini melengkapinya dari sisi seberang: service provider. Kalian akan menyambungkan aplikasi-aplikasi nyata — Salesforce, Google Workspace, AWS, hingga Jira dan Confluence — dengan bertukar metadata, menyamakan entity ID dan ACS URL, memetakan NameID dan atribut, lalu menguji assertion dan memperbaiki error yang paling sering muncul.

#SP Populer di Lapangan

Satu hal yang menyenangkan dari SAML: hampir semua produk enterprise menyediakan opsi integrasi dengan identity provider eksternal. Yang paling sering ditemui:

• Salesforce — mengonfigurasi SSO lewat menu Setup dengan SAML Single Sign-On Settings dan memerlukan entity ID serta ACS URL yang unik.
• Google Workspace — bisa diarahkan ke IdP kustom sebagai penyedia SSO ketiga.
• AWS — lewat IAM identity provider yang menghubungkan Keycloak sebagai sumber federasi.
• Office 365 / Azure AD — mendukung SAML untuk aplikasi yang butuh federasi dengan sistem identitas korporat.
• Jira / Confluence — produk Atlassian menyediakan SAML SSO pada paket enterprise dan data center.

#Pertukaran Metadata

Dasar dari setiap integrasi SAML adalah pertukaran metadata dua arah:

1. Metadata IdP ke SP — kalian mengambil metadata Keycloak dari realms/demo/protocol/saml/descriptor dan mendaftarkannya di aplikasi.
2. Metadata SP ke IdP — kalian mengambil metadata SP dari aplikasi dan mengimpornya ke Keycloak sebagai SAML client.

Dengan kedua metadata bertukar, kedua pihak otomatis tahu endpoint, kunci, dan binding lawannya. Potongan metadata SP kira-kira seperti ini:

<md:EntityDescriptor xmlns:md="urn:oasis:names:tc:SAML:2.0:metadata"
                     entityID="https://jira.example.com">
  <md:SPSSODescriptor AuthnRequestsSigned="true"
                      protocolSupportEnumeration="urn:oasis:names:tc:SAML:2.0:protocol">
    <md:AssertionConsumerService Binding="urn:oasis:names:tc:SAML:2.0:bindings:HTTP-POST"
                                 Location="https://jira.example.com/plugins/servlet/saml/consumer"
                                 index="0" isDefault="true"/>
  </md:SPSSODescriptor>
</md:EntityDescriptor>

Dari metadata ini, Keycloak langsung bisa menyimpulkan entity ID, ACS URL, dan binding yang dipakai SP.

#Elemen Konfigurasi SP

Saat mengonfigurasi SP (baik di Keycloak maupun di aplikasi), ada empat elemen yang harus cocok di kedua sisi:

Entity ID adalah identitas yang dipakai Keycloak sebagai nilai audience dalam assertion. Di Keycloak, ini diisi di field Client ID saat membuat SAML client. Pastikan nilainya benar-benar identik dengan yang diharapkan SP — sering kali hanya beda satu huruf atau garis miring di belakang sudah cukup membuat integrasi gagal.

#ACS URL

Assertion Consumer Service URL adalah alamat di aplikasi yang menerima Response dari browser. Saat membuat client di Keycloak, kalian menaruh ACS URL di Valid Redirect URIs. Bila SP mengirim URL tanpa tanda garis miring di akhir, kalian harus mendaftarkan dua variasi agar tidak gagal.

#NameID dan Attribute Mapping

Setelah SP menerima assertion, aplikasi memetakan NameID ke akun internalnya. Karena itu format NameID harus konsisten — bila SP mengharapkan email, maka Name ID Format di client Keycloak harus email, dan assertion harus membawa alamat email yang cocok dengan akun di aplikasi.

Demikian juga atribut: SP seperti Salesforce sering meminta firstName, lastName, dan email dengan nama tertentu. Kalian membuat mapper di tab Mappers client SAML untuk setiap atribut, lalu menyesuaikan nama atribut SAML-nya persis seperti yang didokumentasikan SP.

#Menguji dengan SAML Tracer

Saat integrasi gagal, langkah pertama yang menolong adalah melihat assertion yang dikirim. Alat yang paling sering dipakai:

• SAML Tracer — ekstensi browser yang menampilkan setiap pesan SAML (request dan response) beserta struktur XML-nya saat kalian menelusuri alur login.
• SAML decoder — alat untuk mendekode dokumen SAML yang ter-encode, baik yang berbasis URL maupun base64.

Langkah pengujian yang disarankan:

1. Aktifkan SAML Tracer di browser
2. Buka URL aplikasi (SP) lalu klik login
3. Telusuri alur redirect sampai halaman login Keycloak
4. Login dengan user yang benar
5. Di SAML Tracer, pilih permintaan Response terakhir
6. Periksa status, issuer, audience, NameID, dan atribut assertion

Perhatikan: SAMLRequest dari SP muncul saat masuk, SAMLResponse dari IdP muncul saat kembali. Keduanya bisa dibaca mentah di SAML Tracer.

#Validasi Assertion

Saat memeriksa assertion, urutan validasinya:

1. Status response harus Success.
2. Signature valid — kunci publik cocok dengan kunci signing IdP saat ini.
3. Audience berisi entity ID SP.
4. NameID dan atribut sesuai dengan akun yang diharapkan.
5. Waktu assertion masih dalam NotBefore dan NotOnOrAfter.

#Error Umum dan Perbaikannya

Catatan khusus tentang signature: setelah kalian memutar kunci signing di Keycloak, assertion yang lama ditandatangani kunci lama akan ditolak SP. Solusinya selalu sama — impor metadata IdP yang baru ke SP.

#Penutup

Pada episode 14 ini, kalian menyambungkan aplikasi nyata sebagai SAML service provider ke Keycloak: mengenal SP populer, bertukar metadata dua arah, menyamakan entity ID, ACS URL, NameID, dan atribut di kedua sisi, menguji alur dengan SAML Tracer, serta menangani error khas seperti signature invalid dan audience mismatch.

Inti yang harus dibawa pulang:

• Metadata dua arah adalah fondasi integrasi — IdP dan SP saling menyalin kemampuan masing-masing.
• Entity ID, ACS URL, NameID, dan atribut harus identik di kedua sisi — perbedaan sekecil apa pun memicu kegagalan.
• SAML Tracer adalah alat debugging utama — tangkap assertion dulu, baru ubah konfigurasi.
• Rotasi kunci harus diikuti impor metadata ulang ke semua SP.

Di episode 15 berikutnya, kita beralih dari autentikasi ke penyimpanan identitas: user federation — menghubungkan Keycloak ke LDAP dan Active Directory agar user tidak perlu diduplikasi di setiap sistem.