Thử SSO doanh nghiệp trên laptop trước khi gặp IT của khách
Một container Keycloak và một file realm JSON đủ để bạn đến buổi họp với luồng đăng nhập đã chạy được.
Tóm tắt nhanh
- Keycloak là IAM mã nguồn mở, giấy phép Apache 2.0, dự án incubating của CNCF từ tháng 4/2023.
- Có thể chạy nó trên laptop làm IdP thay thế tạm để thử luồng SSO từ đầu đến cuối, kèm realm nạp từ file JSON.
- Keycloak hoạt động đúng kiểu Keycloak chứ không giống Okta hay Entra, nên trước khi go-live vẫn cần một lần kiểm tra với IdP thật của khách.
Khi một ứng dụng được đưa vào doanh nghiệp, sớm muộn đội IT của khách cũng sẽ hỏi: người dùng của họ đăng nhập vào đó qua hệ thống danh tính nào, và bằng cách nào?
Nếu lúc đó bạn mới đọc tài liệu OIDC lần đầu, buổi họp sẽ thành buổi học. Keycloak giúp bạn đến họp với một luồng đăng nhập đã chạy được trên chính laptop của mình.
Đây không phải công cụ ngách. Keycloak là dự án IAM mã nguồn mở theo giấy phép Apache 2.0, và tháng 4/2023 hội đồng kỹ thuật của CNCF đã bỏ phiếu nhận nó làm dự án incubating.
Lý do FDE cần nó nằm ở chỗ khác. WorkOS nhận xét rằng thử SSO theo cách truyền thống đòi hỏi một tài khoản IdP và người dùng test, một việc khá mất công. Với FDE, tài khoản ấy thường thuộc quyền IT của khách và có thể chưa được cấp khi dự án mới bắt đầu, trong khi bạn vẫn phải cho thấy ứng dụng tích hợp được.
Keycloak làm được gì cho bạn ở hiện trường?
Trang chủ Keycloak đặt mục tiêu giúp gắn đăng nhập vào ứng dụng mà tốn ít công sức nhất. Quan trọng hơn với FDE, nó dựa trên các giao thức chuẩn: OpenID Connect, OAuth 2.0 và SAML, cũng là những giao thức mà IdP của khách dùng.
Vì thế nhiều đội đã dùng nó như sân tập. Tài liệu của PuppyGraph chạy một Keycloak cục bộ làm IdP thay thế, dựng sẵn một client OIDC và một người dùng test, để người đọc đi hết luồng SSO mà không cần IdP production.
Artemis, nền tảng của Đại học Kỹ thuật München (TUM), cũng làm vậy: một container Keycloak nạp realm có sẵn thay cho nhà cung cấp OIDC production của trường.
Thử hình dung bạn sắp triển khai một công cụ nội bộ cho một ngân hàng dùng Entra. Trước buổi họp, bạn đã biết ứng dụng cần redirect URI nào, đọc claim nào để lấy email và nhóm người dùng, và lỗi gì xảy ra khi token hết hạn. Câu hỏi bạn mang đến IT sẽ cụ thể hơn hẳn.
Một lệnh để có IdP trên máy
Trang getting-started Docker chính thức chạy Keycloak ở chế độ phát triển và tạo sẵn một tài khoản quản trị với username và mật khẩu đều là admin. Lệnh có dạng như sau:
docker run -p 127.0.0.1:8080:8080 \
-e KC_BOOTSTRAP_ADMIN_USERNAME=admin \
-e KC_BOOTSTRAP_ADMIN_PASSWORD=admin \
<image-keycloak-theo-huong-dan-chinh-thuc> start-dev
Chỗ <image-keycloak-theo-huong-dan-chinh-thuc> là phần bạn phải tự điền. Mở trang keycloak.org/getting-started/getting-started-docker, tìm lệnh docker run trong bước khởi động Keycloak, rồi chép nguyên cụm tên image kèm tag phiên bản đứng ngay trước start-dev. Đối chiếu luôn tên các biến môi trường admin với lệnh trên trang, vì chúng có thể đổi theo bản phát hành.
Sau đó vào admin console, tạo một realm cho “khách hàng giả”, một client OIDC cho ứng dụng của bạn và vài người dùng, rồi trỏ ứng dụng vào realm đó và thử đăng nhập.
Đến đây bạn mới có một IdP làm bằng tay. Lần sau bật lên, hoặc khi đồng nghiệp muốn chạy lại, mọi cú click trong admin console phải làm lại từ đầu.
Biến IdP thành file để ai cũng dựng lại được
Keycloak giải quyết chuyện này bằng import realm. Tài liệu chính thức cho biết có thể nạp realm ngay lúc server khởi động bằng tùy chọn --import-realm, và với container thì thư mục import là /opt/keycloak/data/import.
Artemis là ví dụ đáng chép. Họ ghim phiên bản Keycloak ngay trong file compose và nạp realm từ một file JSON nằm trong repo mỗi lần khởi động.
Một bản tối giản theo cùng ý tưởng có thể trông như dưới đây. Điểm mấu chốt là thư mục realms/ trong repo được gắn vào thư mục import của container và lệnh khởi động có thêm --import-realm. Đường dẫn này lấy từ tài liệu hiện hành; hãy đối chiếu lại với tài liệu ứng với phiên bản image bạn dùng.
services:
keycloak:
image: ${KEYCLOAK_IMAGE} # tên image + phiên bản cố định, lấy từ trang Docker của Keycloak
command: start-dev --import-realm
environment:
KC_BOOTSTRAP_ADMIN_USERNAME: admin
KC_BOOTSTRAP_ADMIN_PASSWORD: admin
ports:
- "127.0.0.1:8080:8080"
volumes:
- ./realms:/opt/keycloak/data/import # kiểm tra lại đường dẫn theo tài liệu của phiên bản bạn dùng
Để file này chạy được, tạo một file .env cạnh file compose với đúng một dòng KEYCLOAK_IMAGE= theo sau là cụm image và tag bạn vừa chép từ trang Docker. Commit cả file .env đó: tag cố định là thứ giúp đồng nghiệp dựng ra đúng IdP như bạn, thay vì một bản mới hơn cư xử khác.
File realms/khach-gia.json chỉ cần một client và một người dùng test là đủ để chạy thử. Đoạn trích minh hoạ dưới đây giữ lại phần cốt lõi; bản export thật từ admin console sẽ dài hơn nhiều:
{
"realm": "khach-gia",
"enabled": true,
"clients": [
{
"clientId": "app-cua-ban",
"publicClient": true,
"redirectUris": ["http://localhost:3000/callback"]
}
],
"users": [
{
"username": "nhanvien1",
"email": "[email protected]",
"enabled": true,
"credentials": [{ "type": "password", "value": "test", "temporary": false }]
}
]
}
Cách làm nên theo: cấu hình realm bằng tay một lần, export ra JSON, thêm các tài khoản đóng vai đúng những nhóm người dùng của khách (nhân viên, quản lý, admin), rồi commit file vào repo cùng file compose. Từ đó, ai trong team chạy docker compose up cũng có cùng một IdP, và buổi demo không phụ thuộc vào trí nhớ của ai.
Ba lỗi dễ mắc khi dựng lần đầu
Phần lớn thời gian mất đi khi dựng IdP cục bộ không nằm ở Keycloak mà ở vài chi tiết nhỏ. Bảng dưới đây là những chỗ nên kiểm tra trước tiên khi đăng nhập không chạy.
| Triệu chứng | Nguyên nhân thường gặp | Cách xử lý |
|---|---|---|
| Đăng nhập xong bị từ chối khi quay về ứng dụng | Redirect URI khai trong client không khớp với địa chỉ ứng dụng thật sự gọi | So từng ký tự: giao thức, cổng, đường dẫn, dấu / cuối |
| Sửa file realm JSON nhưng khởi động lại không thấy thay đổi | Realm đã tồn tại trên server nên bước import bị bỏ qua | Dựng lại từ một instance sạch hoặc xoá realm cũ trước khi import |
| Keycloak khởi động nhưng không có realm nào được nạp | Quên --import-realm, hoặc volume không trỏ vào đúng thư mục import |
Kiểm tra lệnh khởi động và đường dẫn mount theo tài liệu của phiên bản đang dùng |
Lỗi đầu tiên là kinh nghiệm chung khi làm OIDC, và nó sẽ quay lại ở môi trường của khách. Lỗi thứ hai đến thẳng từ quy tắc của Keycloak: realm đã có thì import bị bỏ qua. Ghi cả hai vào README để đồng nghiệp không mất một buổi chiều.
Laptop không thay được IdP của khách
Giới hạn đầu tiên nằm ngay trong lệnh khởi động. Chế độ phát triển với admin/admin chỉ hợp với máy cục bộ; đừng để cấu hình đó lọt vào bất kỳ môi trường nào của khách.
Giới hạn thứ hai là về bản chất. SSOJet nói thẳng: Keycloak chạy cục bộ chỉ với một lệnh docker run, nhưng nó hoạt động đúng kiểu Keycloak chứ không giống Okta hay Entra. Tên claim, cách cấu hình nhóm và chính sách của từng IdP có thể khác.
SSOJet cũng mô tả nhịp làm việc mà nhiều đội chọn: dùng IdP giả trong lúc phát triển và trong CI, rồi kiểm tra một lần với IdP thật của khách trước khi ra mắt. Đó là cách nên lên kế hoạch: laptop xác nhận ứng dụng xử lý đúng luồng chuẩn, còn buổi làm việc với IT dành cho những chi tiết riêng của khách.
Vì vậy, đừng bắt đầu bằng việc học hết tính năng của Keycloak. Hãy nắm chắc luồng OIDC cơ bản trước: realm, client, redirect URI, token và claim. Hiểu chúng trên Keycloak rồi, bạn sẽ đọc tài liệu của bất kỳ IdP doanh nghiệp nào nhanh hơn.
Bài tập cuối: nhóm “quản lý” có thật sự vào token?
Phần lớn ứng dụng doanh nghiệp không chỉ hỏi “ai đăng nhập” mà còn hỏi “người đó thuộc nhóm nào”. Đây là bài tập nên làm trước khi coi môi trường của bạn là xong.
Trong realm khach-gia, tạo một nhóm quan-ly và gán cho một tài khoản test mới, chẳng hạn quanly1. Cấu hình client để thông tin nhóm được đưa vào token, rồi đăng nhập lần lượt bằng nhanvien1 và quanly1. Giải mã ID token của từng người và so: chỉ token của quanly1 được có claim nhóm quan-ly.
Khi đã thấy claim đó, cho ứng dụng đọc nó để mở hoặc khoá một trang quản trị, rồi export realm lần nữa để nhóm mới nằm trong file JSON. Bạn vừa có sẵn câu hỏi cụ thể nhất cho IT của khách: IdP của họ gửi thông tin nhóm trong claim nào, với tên gì.
Một repo nhỏ đáng giá hơn một dòng kỹ năng
Một repo gồm ứng dụng mẫu, file compose và realm JSON có sẵn người dùng test là bằng chứng mà nhà tuyển dụng FDE có thể tự chạy. Trong CV, hãy viết theo kết quả: đã dựng môi trường SSO tái lập được để kiểm thử tích hợp OIDC trước khi kết nối IdP của khách.
Lần tới khi lịch có buổi “kickoff với IT”, hãy dành một buổi tối trước đó cho Keycloak. Bạn sẽ bước vào phòng họp với câu hỏi đúng thay vì danh sách những thứ chưa biết.
Bài này có hữu ích không?
Cảm ơn bạn đã góp ý!
9 nguồn
- Docker - Keycloak
- Keycloak
- Keycloak joins CNCF as an incubating project · 2023-04-11
- GitHub - keycloak/keycloak: Open Source Identity and Access Management For Modern Applications and Services
- Importing and exporting realms - Keycloak
- Setting Up SSO with Keycloak - PuppyGraph Docs
- Keycloak OIDC Setup for Local Development | Welcome to the Artemis Documentation
- Test SAML SSO Locally Without an Okta or Entra Tenant · 2026-10-26
- Introducing Test SSO, an easier way to integrate SSO into your app · 2024-02-26