# 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.

Bản gốc: https://fdetimes.net/vi/cong-cu/keycloak-dung-sso-oidc-tren-laptop-de-thu-tich-hop/

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:

```bash
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ỗ `` 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.

```yaml
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:

```json
{
  "realm": "khach-gia",
  "enabled": true,
  "clients": [
    {
      "clientId": "app-cua-ban",
      "publicClient": true,
      "redirectUris": ["http://localhost:3000/callback"]
    }
  ],
  "users": [
    {
      "username": "nhanvien1",
      "email": "nhanvien1@khach-gia.test",
      "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.

**Điểm mấu chốt:** Đừng để buổi họp với IT của khách là lần đầu ứng dụng của bạn gặp một IdP thật.

## 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.

**Thử ngay tuần này:**

- Chạy Keycloak bằng Docker theo trang getting-started chính thức, đăng nhập admin console rồi tạo một realm và một client OIDC cho ứng dụng của bạn.
- Export realm vừa tạo ra file .json, thêm vài tài khoản test, rồi dựng lại từ một instance sạch với --import-realm để chắc chắn mọi thứ tái lập được.
- Viết một README ngắn để đồng nghiệp chạy lại IdP này mà không phải hỏi bạn câu nào.

## Nguồn

- [Docker - Keycloak](https://www.keycloak.org/getting-started/getting-started-docker)

- [Keycloak](https://www.keycloak.org/)

- [Keycloak joins CNCF as an incubating project](https://cncf.io/blog/2023/04/11/keycloak-joins-cncf-as-an-incubating-project)

- [GitHub - keycloak/keycloak: Open Source Identity and Access Management For Modern Applications and Services](https://github.com/keycloak/keycloak)

- [Importing and exporting realms - Keycloak](https://www.keycloak.org/server/importExport)

- [Setting Up SSO with Keycloak - PuppyGraph Docs](https://docs.puppygraph.com/getting-started/setting-up-sso-with-keycloak/)

- [Keycloak OIDC Setup for Local Development | Welcome to the Artemis Documentation](https://docs.artemis.tum.de/developer/keycloak-oidc-setup)

- [Test SAML SSO Locally Without an Okta or Entra Tenant](https://ssojet.com/blog/test-saml-sso-locally-without-idp-tenant)

- [Introducing Test SSO, an easier way to integrate SSO into your app](https://www.workos.com/blog/introducing-test-sso)
