Belajar Keycloak - Keycloak sebagai SAML IdP

#Pendahuluan

Di episode 12 kalian memahami fondasi SAML: assertion, binding, alur SP-initiated dan IdP-initiated, serta struktur XML. Episode 13 ini menerjemahkan teori itu menjadi konfigurasi nyata: menyalakan Keycloak sebagai SAML Identity Provider. Kalian akan membuat SAML client, mengekspor metadata, mengatur kunci signing dan enkripsi, memilih format NameID, memetakan atribut, lalu menguji alurnya — sebelum di episode 14 kita menyambungkan aplikasi sungguhan sebagai service provider.

#Peran Keycloak sebagai IdP

Ketika kalian membuat sebuah client dengan jenis SAML di sebuah realm, Keycloak langsung berperan sebagai IdP untuk aplikasi itu. Ini bukan mode khusus; realm yang sama bisa melayani klien OIDC dan SAML sekaligus. Yang membedakan hanyalah bagaimana aplikasi memintanya — lewat protocol SAML yang berbasis XML, bukan lewat token endpoint OIDC.

Dari sudut pandang SP, Keycloak mengekspos tiga hal penting:

• Single Sign-On endpoint — tempat SP mengarahkan AuthnRequest, berbentuk /realms/{realm}/protocol/saml.
• Single Logout endpoint — tempat SLO diproses, berbagi alamat yang sama.
• Metadata descriptor — dokumen XML yang mendeskripsikan seluruh kemampuan IdP.

#Membuat SAML Client

Langkah pertama di admin console:

1. Buka tab Clients pada sebuah realm, klik Create client
2. Pilih Client type SAML, isi Client ID dengan entity ID milik SP
3. Di tab Settings, isi Valid Redirect URIs dengan URL ACS aplikasi
4. Pilih Name ID Format yang disepakati dengan SP
5. Atur opsi signing dan enkripsi sesuai kebutuhan SP
6. Simpan konfigurasi

Di Keycloak modern, jenis client dipilih lewat dropdown Client type dengan nilai saml. Opsi-opsi yang kalian temukan di tab Settings: Sign Assertions, Sign Documents, Require Assertion Signature, Encrypt Assertions, Force POST Binding, dan Assertion Signature Algorithm. Jangan nyalakan semua tanpa paham — setiap opsi harus cocok dengan kemampuan SP.

Aturan praktis: nyalakan Sign Assertions selalu; aktifkan Encrypt Assertions hanya bila SP menuntutnya, karena enkripsi menambah kompleksitas pertukaran kunci.

#Metadata dan Kunci Signing

Setelah client dibuat, Keycloak menyediakan metadata lengkap realm di endpoint:

realms/demo/protocol/saml/descriptor

Dokumen inilah yang kalian berikan ke SP sebagai gambaran lengkap kemampuan IdP — termasuk kunci publik yang dipakai untuk memverifikasi signature. Potongannya kira-kira seperti ini:

<md:EntityDescriptor xmlns:md="urn:oasis:names:tc:SAML:2.0:metadata"
                     entityID="https://keycloak.example.com/realms/demo">
  <md:IDPSSODescriptor WantAuthnRequestsSigned="false"
                       protocolSupportEnumeration="urn:oasis:names:tc:SAML:2.0:protocol">
    <md:KeyDescriptor use="signing">
      <ds:KeyInfo xmlns:ds="http://www.w3.org/2000/09/xmldsig#">
        <ds:X509Certificate>MIIC...</ds:X509Certificate>
      </ds:KeyInfo>
    </md:KeyDescriptor>
    <md:SingleSignOnService Binding="urn:oasis:names:tc:SAML:2.0:bindings:HTTP-Redirect"
                            Location="https://keycloak.example.com/realms/demo/protocol/saml"/>
    <md:SingleLogoutService Binding="urn:oasis:names:tc:SAML:2.0:bindings:HTTP-Redirect"
                            Location="https://keycloak.example.com/realms/demo/protocol/saml"/>
  </md:IDPSSODescriptor>
</md:EntityDescriptor>

Keycloak memakai kunci realm untuk menandatangani assertion dan bisa mengekspornya lewat tab Realm Keys di admin console. Ingat: setiap kali kalian memutar (rotate) kunci signing, metadata yang sudah dipegang SP harus diperbarui — jika tidak, semua SP akan gagal memverifikasi signature.

#Endpoint dan Konfigurasi Signing

Di tab Settings client SAML, kalian mengatur titik-titik penting yang menentukan bagaimana SP akan berbicara ke IdP:

• Valid Redirect URIs — daftar URL ACS yang sah; ini harus persis dengan URL yang dipakai SP untuk menerima Response.
• Master SAML Processing URL — default URL pemrosesan request SAML bila SP tidak menyediakan URL spesifik.
• Force POST Binding — memaksa semua Response dikirim lewat HTTP POST, berguna bila URL redirect terlalu pendek untuk assertion yang besar.
• Assertion Signature Algorithm — pilihannya umumnya RSA-SHA256; gunakan SHA1 hanya untuk SP yang benar-benar tua.

Untuk enkripsi, Keycloak mendukung enkripsi assertion dengan standar XML Encryption. Kunci publik SP diambil dari metadata, lalu assertion dienkripsi sebelum dikirim. Kalian akan membutuhkan ini ketika SP menuntut assertion terenkripsi.

#Opsi Integrasi dengan Aplikasi

#NameID dan Atribut SAML

#Format NameID

NameID adalah identitas user yang dibawa assertion. Pilihan formatnya diatur lewat field Name ID Format pada client:

• email — cocok bila email adalah identitas utama di SP.
• persistent — identifier tidak berubah sepanjang hidup user, cocok untuk federation lintas organisasi.
• transient — identifier sekali pakai, untuk sesi yang tidak perlu dikaitkan antar kunjungan.
• username — nama user di realm Keycloak.

Force Name ID Format memaksa assertion selalu memakai format yang dipilih, mengabaikan yang diminta SP di AuthnRequest.

#Attribute Statements dan Mapper

Atribut di assertion diatur lewat tab Mappers pada client. Setiap mapper memetakan satu atribut user Keycloak ke sebuah nama atribut SAML yang dibawa assertion:

• Attribute Statement — atribut biasa seperti email, nama depan, dan nama belakang.
• Custom attributes — atribut user tambahan yang kalian definisikan sendiri, misalnya nomor karyawan.
• Attribute filtering — hanya atribut yang dipetakan lewat mapper yang muncul di assertion; ini sekaligus menjaga assertion tetap kecil dan tidak membocorkan data yang tidak perlu.

#Menguji Alur dan Troubleshooting

Setelah client dikonfigurasi, uji dengan menelusuri aplikasi SP dan menekan login. Beberapa titik yang selalu diperiksa saat alur gagal:

• Status response — pastikan StatusCode-nya Success, bukan Responder atau RequestDenied.
• Issuer — assertion harus menyebut issuer yang dikenali SP.
• Signature — kunci publik SP harus cocok dengan kunci signing realm saat ini.
• Audience — nilai audience harus sama dengan entity ID SP.
• NameID format — format yang dikirim harus persis seperti yang disepakati.
• Jam sistem — assertion punya NotBefore dan NotOnOrAfter; selisih jam membuat assertion ditolak, jadi sinkronkan NTP.

Event realm di Keycloak bisa dipakai untuk melihat alur: admin console mencatat login dan kegagalan yang berhubungan dengan client SAML ini.

#Penutup

Pada episode 13 ini, kalian menyalakan Keycloak sebagai SAML IdP: membuat SAML client, memahami endpoint SSO dan SLS, mengekspor metadata lengkap dengan kunci signing, mengatur enkripsi dan algoritma signature, memilih format NameID, memetakan atribut lewat mapper, serta mengetahui titik-titik troubleshooting utama.

Inti yang harus dibawa pulang:

• Client dengan tipe saml menjadikan Keycloak IdP tanpa mengubah realm yang sama untuk OIDC.
• Metadata adalah kontrak integrasi — endpoint realms/demo/protocol/saml/descriptor berisi semua yang dibutuhkan SP.
• Opsi signing dan enkripsi harus disepakati dua arah — menyalakan enkripsi sepihak hanya akan menambah masalah.
• Mapper menentukan isi assertion — atribut yang tidak dipetakan tidak akan pernah sampai ke SP.

Di episode 14 berikutnya, kita membalik sisi: Keycloak sudah siap sebagai IdP, sekarang kalian menyambungkan SAML service provider sungguhan — Salesforce, Google Workspace, atau aplikasi Jira — termasuk cara menguji assertion dengan SAML Tracer dan menangani error khas integrasi.