คู่มือการติดตั้ง Keycloak SSO บน Ubuntu Server 24.04 LTS

เชื่อมต่อ Microsoft Active Directory พร้อมระบบ Two-Factor Authentication (2FA)

เอกสาร: Installation & Configuration Guide
ระบบ: Keycloak Identity and Access Management
Operating System: Ubuntu Server 24.04 LTS
Database: PostgreSQL
Directory Service: Microsoft Active Directory
Authentication: SSO + MFA / 2FA
สถานะ: Draft สำหรับนำไปติดตั้งจริง

1. วัตถุประสงค์

เอกสารฉบับนี้จัดทำขึ้นเพื่อกำหนดขั้นตอนการติดตั้งระบบ Single Sign-On (SSO) ด้วย Keycloak บน Ubuntu Server 24.04 LTS โดยเชื่อมต่อกับ Microsoft Active Directory เพื่อใช้เป็นศูนย์กลางในการ Authentication ของผู้ใช้งานภายในองค์กร

ระบบจะรองรับความสามารถดังต่อไปนี้

Single Sign-On (SSO)
Active Directory / LDAP Integration
Two-Factor Authentication (2FA)
Multi-Factor Authentication (MFA)
OpenID Connect (OIDC)
SAML 2.0
User and Group Management
Centralized Authentication
Role-Based Access Control (RBAC)

2. System Architecture

2.1 ภาพรวมระบบ

Microsoft Active Directory จะทำหน้าที่เป็นแหล่งข้อมูลบัญชีผู้ใช้งานหลัก ส่วน Keycloak จะทำหน้าที่เป็น Identity Provider (IdP) สำหรับตรวจสอบตัวตนและจัดการการเข้าสู่ระบบ

โครงสร้างการทำงาน:

Microsoft Active Directory
↓ LDAPS (TCP 636)
Keycloak SSO Server
↓
2FA Verification
↓
OIDC / SAML 2.0
↓
ERP / Web Application / VPN / Internal Systems

2.2 ข้อมูล Server (ตัวอย่าง)

รายการ	ค่า
Operating System	Ubuntu Server 24.04
Hostname	sso.example.com
IP Address	192.168.1.20
CPU	4 vCPU
RAM	8 GB
Storage	50 GB
Keycloak	26.x (กำหนดรุ่นที่ผ่านการทดสอบ)
Database	PostgreSQL
Web Server	Nginx
AD Server	192.168.1.10
LDAP Port	636

หมายเหตุ: IP Address และ Domain เป็นตัวอย่าง ให้เปลี่ยนตามสภาพแวดล้อมจริง

3. Prerequisites

ก่อนเริ่มติดตั้งต้องเตรียมข้อมูลดังต่อไปนี้

Ubuntu Server 24.04 LTS
สิทธิ์ sudo
Static IP Address
DNS Record สำหรับ sso.example.com
Microsoft Active Directory ที่สามารถเข้าถึงจาก Keycloak Server
Service Account สำหรับ LDAP Bind
CA Certificate สำหรับตรวจสอบ LDAPS Certificate
SSL Certificate สำหรับ HTTPS

3.1 Firewall Ports

Port	Protocol	วัตถุประสงค์
443	TCP	HTTPS / SSO
80	TCP	HTTP Redirect / Let's Encrypt
636	TCP	LDAPS
389	TCP	LDAP (ไม่แนะนำสำหรับ Production)
5432	TCP	PostgreSQL (Internal Only)
8080	TCP	Keycloak Internal Only

ไม่ควรเปิด PostgreSQL และ Keycloak Management Interface ให้เข้าถึงจาก Internet โดยตรง

4. ติดตั้ง Ubuntu และ Docker

4.1 Update Ubuntu

sudo apt update

sudo apt upgrade -y
sudo apt install -y curl wget vim \
  ca-certificates gnupg ufw

4.2 ติดตั้ง Docker

sudo apt install -y docker.io docker-compose-v2

sudo systemctl enable docker
sudo systemctl start docker

docker --version
docker compose version

4.3 ตั้งค่า Time Synchronization

sudo timedatectl set-timezone Asia/Bangkok
sudo timedatectl set-ntp true

timedatectl status

การตั้งเวลาให้ตรงกันมีความสำคัญต่อการตรวจสอบ TOTP และการทำงานของระบบ Authentication

5. ติดตั้ง Keycloak และ PostgreSQL

5.1 สร้าง Directory

sudo mkdir -p /opt/keycloak
sudo chown -R $USER:$USER /opt/keycloak

cd /opt/keycloak

5.2 สร้างไฟล์ Environment

สร้างไฟล์ .env

sudo vi .env

กำหนดค่าตัวอย่าง:

env

KEYCLOAK_VERSION=26.8.0

POSTGRES_DB=keycloak
POSTGRES_USER=keycloak
POSTGRES_PASSWORD=CHANGE_TO_STRONG_PASSWORD

KC_BOOTSTRAP_ADMIN_USERNAME=kcadmin
KC_BOOTSTRAP_ADMIN_PASSWORD=CHANGE_TO_STRONG_ADMIN_PASSWORD

เปลี่ยน Password ทุกค่าก่อนนำไปใช้งานจริง และห้ามนำไฟล์นี้ขึ้น Git Repository

sudo chmod 600 .env

หมายเหตุ: ให้ตรวจสอบรุ่น Keycloak ที่ต้องการใช้งานและ Compatibility ก่อน Deploy จริง โดยควร Pin รุ่นที่ผ่านการทดสอบ ไม่ใช้ tag latest

5.3 สร้าง Docker Compose

สร้างไฟล์:

sudo vi docker-compose.yml

กำหนดค่า:

yaml

services:

  postgres:
    image: postgres:16
    container_name: keycloak-db
    restart: unless-stopped

    environment:
      POSTGRES_DB: ${POSTGRES_DB}
      POSTGRES_USER: ${POSTGRES_USER}
      POSTGRES_PASSWORD: ${POSTGRES_PASSWORD}

    volumes:
      - postgres_data:/var/lib/postgresql/data

    networks:
      - keycloak-network

  keycloak:
    image: quay.io/keycloak/keycloak:${KEYCLOAK_VERSION}

    container_name: keycloak
    restart: unless-stopped

    command:
      - start
      - --db=postgres
      - --hostname=https://sso.example.com
      - --http-enabled=true
      - --proxy-headers=xforwarded

    environment:
      KC_DB: postgres
      KC_DB_URL_HOST: postgres
      KC_DB_URL_DATABASE: ${POSTGRES_DB}
      KC_DB_USERNAME: ${POSTGRES_USER}
      KC_DB_PASSWORD: ${POSTGRES_PASSWORD}

      KC_BOOTSTRAP_ADMIN_USERNAME: ${KC_BOOTSTRAP_ADMIN_USERNAME}
      KC_BOOTSTRAP_ADMIN_PASSWORD: ${KC_BOOTSTRAP_ADMIN_PASSWORD}

    ports:
      - "127.0.0.1:8080:8080"

    depends_on:
      - postgres

    networks:
      - keycloak-network

volumes:
  postgres_data:

networks:
  keycloak-network:
    driver: bridge

สำหรับ Production ต้องตั้งค่า HTTPS ที่ Reverse Proxy ให้ถูกต้อง พร้อมกำหนด hostname และ trusted proxy ตามสภาพแวดล้อมจริง

5.4 Start Services

sudo docker compose pull


sudo docker compose up -d

sudo docker compose ps

ตรวจสอบ Log:

sudo docker compose logs -f keycloak

ทดสอบการเข้าถึง:

sudo curl -I http://127.0.0.1:8080

6. ตั้งค่า Nginx Reverse Proxy และ HTTPS

ติดตั้ง Nginx:

sudo apt install -y nginx

สร้าง Configuration:

sudo nano /etc/nginx/sites-available/keycloak

ตัวอย่าง Configuration:

nginx

server {
    listen 80;
    server_name sso.example.com;

    location / {
        return 301 https://$host$request_uri;
    }
}

server {
    listen 443 ssl;
    server_name sso.example.com;

    ssl_certificate /etc/letsencrypt/live/sso.example.com/fullchain.pem;
    ssl_certificate_key /etc/letsencrypt/live/sso.example.com/privkey.pem;

    location / {
        proxy_pass http://127.0.0.1:8080;

        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto https;
    }
}

เปิดใช้งาน:

sudo ln -s /etc/nginx/sites-available/keycloak \
  /etc/nginx/sites-enabled/keycloak

sudo nginx -t

sudo systemctl reload nginx

ต้องติดตั้ง SSL Certificate ที่ถูกต้องก่อนเปิดใช้งาน Configuration นี้

7. เชื่อมต่อ Microsoft Active Directory

7.1 เตรียมข้อมูล Active Directory

ตัวอย่างข้อมูล:

รายการ	ค่า
Domain	example.local
Domain Controller	192.168.1.10
LDAP URL	ldaps://192.168.1.10:636
Base DN	DC=example,DC=local
Users OU	OU=Users,DC=example,DC=local
Bind Account	svc_keycloak@example.local
Username Attribute	sAMAccountName
User Object Class	user

ควรใช้ Service Account ที่มีสิทธิ์อ่านข้อมูล Directory เท่าที่จำเป็น ไม่ใช้ Domain Administrator

7.2 ตรวจสอบ LDAPS

ติดตั้ง LDAP Utilities:

sudo apt install -y ldap-utils

ทดสอบการเชื่อมต่อ:

sudo ldapsearch -H ldaps://192.168.1.10:636 \
  -x \
  -D "svc_keycloak@example.local" \
  -W \
  -b "DC=example,DC=local" \
  "(sAMAccountName=testuser)"

หมายเหตุ: ต้องติดตั้งและ Trust CA Certificate ของ Active Directory บน Keycloak Container ก่อนใช้งานจริง หากใช้ Internal CA

ควรใช้ FQDN ของ Domain Controller ให้ตรงกับชื่อใน Certificate

7.3 ตั้งค่า User Federation ใน Keycloak

เข้าสู่ระบบ:

https://sso.example.com

จากนั้นดำเนินการดังนี้

เข้าสู่ Administration Console
เลือก Realm ที่ต้องการ
เลือก User Federation
คลิก Add LDAP Providers
กำหนดค่าการเชื่อมต่อ

ค่าที่แนะนำ:

Configuration	Value
Vendor	Active Directory
Connection URL	ldaps://dc01.example.local:636
Bind Type	Simple
Bind DN	svc_keycloak@example.local
Users DN	OU=Users,DC=example,DC=local
Username LDAP Attribute	sAMAccountName
RDN LDAP Attribute	cn
UUID LDAP Attribute	objectGUID
User Object Classes	person, organizationalPerson, user
Search Scope	Subtree
Edit Mode	READ_ONLY

กด Test Connection และ Test Authentication

หากผ่านการทดสอบให้กด Save

7.4 Synchronize Users

หลังจากเชื่อมต่อ AD สำเร็จ

เข้า User Federation
เลือก LDAP Provider
ใช้ Synchronize all users
ตรวจสอบจำนวน User ที่นำเข้ามา
ตรวจสอบ Username, Email และ Group Mapping

การตั้งค่า LDAP Federation ควรทดสอบกับกลุ่มผู้ใช้ขนาดเล็กก่อนนำไปใช้จริง

8. ตั้งค่า Two-Factor Authentication (2FA)

Keycloak รองรับ TOTP สำหรับแอปพลิเคชัน เช่น

Google Authenticator
Microsoft Authenticator
FreeOTP

และรองรับ WebAuthn / FIDO2

8.1 ตั้งค่า OTP Policy

เข้าสู่ Keycloak Admin Console

เลือก:

Authentication
  → Policies
  → OTP Policy

กำหนดค่าตัวอย่าง:

Setting	Value
OTP Type	Time Based
OTP Algorithm	SHA256
Digits	6
Token Period	30 Seconds
Look Around Window	1

ตรวจสอบความเข้ากันได้ของ Authenticator ที่เลือกก่อนกำหนด Algorithm

8.2 บังคับให้ผู้ใช้ลงทะเบียน 2FA

ไปที่:

text

Authentication
  → Required Actions

เปิดใช้งาน:

text

Configure OTP

จากนั้นกำหนดให้ผู้ใช้ต้องลงทะเบียน OTP ก่อนใช้งาน

8.3 Authentication Flow

กำหนด Authentication Flow ให้มีขั้นตอนดังนี้

Username / Password
ตรวจสอบ Credentials ผ่าน Active Directory
ตรวจสอบ OTP
Authentication Success
ส่ง Token ให้ Application

ควรทดสอบ Flow กับ User Group ที่กำหนดก่อนบังคับใช้กับผู้ใช้ทุกคน

9. ตั้งค่า SSO ให้ Application

Keycloak รองรับ Protocol หลักสองประเภท:

OpenID Connect (OIDC)

เหมาะกับ:

Web Application
Modern Application
API
Mobile Application

SAML 2.0

เหมาะกับ:

Enterprise Application
ระบบ ERP
ระบบที่รองรับ SAML Service Provider

การสร้าง Application:

text

Clients
  → Create Client
  → Select OpenID Connect
  → Configure Client ID
  → Configure Redirect URI
  → Save

กำหนด Redirect URI ให้ตรงกับ Application จริง และหลีกเลี่ยง Wildcard ที่กว้างเกินจำเป็น

10. Security Hardening

ก่อนใช้งาน Production ควรดำเนินการดังนี้

เปิดใช้งาน HTTPS ทุกการเชื่อมต่อ
ใช้ LDAPS แทน LDAP แบบไม่เข้ารหัส
จำกัดสิทธิ์ Service Account
จำกัดการเข้าถึง Admin Console
เปิด MFA สำหรับ Administrator
ใช้ PostgreSQL แยกจาก Public Network
ตั้งค่าการสำรองข้อมูล PostgreSQL
ตั้งค่าการเก็บ Audit Logs
ป้องกัน Brute Force Login
ใช้ Firewall จำกัด Port
ทดสอบ Account Lockout และ Recovery
จัดทำแผน High Availability และ Disaster Recovery

11. Testing & Validation

Test Case	Expected Result
Login ด้วย AD Account	ผ่าน
Login ด้วย Password ผิด	ไม่ผ่าน
Login ด้วย User ที่ถูก Disable ใน AD	ไม่ผ่าน
Login ด้วย TOTP ถูกต้อง	ผ่าน
Login ด้วย TOTP ผิด	ไม่ผ่าน
Login Application ผ่าน SSO	ผ่าน
Logout จากระบบ	Session ถูกจัดการตาม Policy
AD Server ไม่พร้อมใช้งาน	ระบบแจ้งข้อผิดพลาด
LDAP Certificate ไม่ถูกต้อง	ปฏิเสธการเชื่อมต่อ

12. Backup and Recovery

ควรสำรองข้อมูลต่อไปนี้:

PostgreSQL Database
Keycloak Configuration
Realm Export
Client Configuration
SSL Certificates
LDAP CA Certificates
Docker Compose และ Environment Configuration

ควรเก็บ Backup แยกจากเครื่อง Production และทดสอบ Restore เป็นระยะ

13. สรุป

การติดตั้ง Keycloak บน Ubuntu Server 24.04 LTS และเชื่อมต่อกับ Microsoft Active Directory ช่วยให้องค์กรสามารถรวมศูนย์การจัดการ Authentication ได้

ระบบรองรับ SSO, LDAP Federation, OIDC, SAML และ 2FA ทำให้สามารถนำไปใช้เป็นระบบ Identity Provider กลางสำหรับ Application ต่าง ๆ ภายในองค์กร

Recommended Solution:

Identity Provider: Keycloak
Operating System: Ubuntu 24.04 LTS
Database: PostgreSQL
Directory: Microsoft Active Directory
Directory Protocol: LDAPS
SSO Protocol: OIDC / SAML 2.0
MFA: TOTP / WebAuthn
Reverse Proxy: Nginx
SSL: TLS Certificate

14. Official References

Keycloak Official Website
https://www.keycloak.org/
Keycloak Server Administration Guide
https://www.keycloak.org/docs/latest/server_admin/
Keycloak LDAP / Active Directory Integration
https://www.keycloak.org/docs/latest/server_admin/#_ldap
Keycloak OTP Policy
https://www.keycloak.org/docs/latest/server_admin/#_otp
Keycloak Production Configuration
https://www.keycloak.org/server/configuration-production
Ubuntu Server Documentation
https://documentation.ubuntu.com/server/

End of Document

software

วันอังคารที่ 10 พฤศจิกายน พ.ศ. 2569

Ubuntu - Keycloak