donghyeon.kang/llm-wiki
1
0
Fork 0
Code Issues Pull Requests Projects Releases Wiki Activity
Files
6c53ded9cb70f2d7cf3e66ff50d42f2d151c98b1
llm-wiki/vault/20-evidence/official-docs/keycloak-getting-started-docker.md
T

8.0 KiB
Raw Blame History

title, source_type, url, archive_url, status, confidence, tags, related_projects, related_branches, created, last_reviewed
title source_type url archive_url status confidence tags related_projects related_branches created last_reviewed
Keycloak — Get started with Keycloak on Docker (quickstart) official-doc https://www.keycloak.org/getting-started/getting-started-docker raw high
keycloak
keycloak-patterns
p3a-single-ec2
docker
quickstart
realm
client
redirect-uri
keycloak-patterns
feature-keycloak-patterns
feature-keycloak-single-ec2-no-google
feature-keycloak-docker-compose-stack
feature-keycloak-realm-client-export
2026-05-25 2026-05-27

Keycloak — Getting started on Docker (quickstart)

Layer: raw/official-docs/ — Keycloak quickstart 가이드 발췌. P3A 단일 EC2 학습 환경의 docker 기반 booting 절차의 1차 근거.

Parent / 활용 branch (필수)

Branch 이 자료가 정당화하는 결정
raw/branch-notes/feature-keycloak-patterns keycloak-patterns root — 최소 booting 방법으로 start-dev + docker 채택 근거
raw/branch-notes/feature-keycloak-single-ec2-no-google P3A 단일 EC2 학습 환경에서 quickstart docker 명령으로 초기 부팅 결정 근거
raw/branch-notes/feature-keycloak-docker-compose-stack docker-compose 로 동일 부팅 정보 (KC_BOOTSTRAP_ADMIN_* env, port 8080) 를 확장
raw/branch-notes/feature-keycloak-realm-client-export realm/client 생성 절차의 admin console 경로 + Partial export 의 baseline 사실

컨텍스트

Keycloak 의 학습용 quickstart. production 용 아님 — start-dev 옵션은 명시적으로 dev 모드. P3A 단일 EC2 학습 환경에서 booting + realm/client 생성을 한 번에 시연.

출처 / Source

핵심 인용 / Key quotes (verbatim)

[§Start Keycloak] "docker run -p 127.0.0.1:8080:8080 -e KC_BOOTSTRAP_ADMIN_USERNAME=admin -e KC_BOOTSTRAP_ADMIN_PASSWORD=admin quay.io/keycloak/keycloak:26.6.2 start-dev"

[§Start Keycloak] "This command starts Keycloak exposed on the local port 8080 and creates an initial admin user with the username admin and password admin."

[§Create a realm] "A realm in Keycloak is equivalent to a tenant. Each realm allows an administrator to create isolated groups of applications and users."

[§Secure the first application] "Set Valid redirect URIs to https://www.keycloak.org/app/*"

[§Secure the first application] "Set Web origins to https://www.keycloak.org"

Claims Extracted / 추출된 주장

Claim ID Claim (이 자료가 직접 말하는 것) Evidence quote Strength Applies to Does not prove
KC-GSD-C1 quickstart docker 명령은 quay.io/keycloak/keycloak:26.6.2 start-dev 이미지를 KC_BOOTSTRAP_ADMIN_USERNAME=admin + KC_BOOTSTRAP_ADMIN_PASSWORD=admin env 와 함께 127.0.0.1:8080:8080 으로 노출 [§Start Keycloak] "docker run -p 127.0.0.1:8080:8080 -e KC_BOOTSTRAP_ADMIN_USERNAME=admin -e KC_BOOTSTRAP_ADMIN_PASSWORD=admin quay.io/keycloak/keycloak:26.6.2 start-dev" official-vendor-doc quickstart / 학습 환경 booting production 사용을 권장한다는 뜻은 아님 — start-dev 명시
KC-GSD-C2 위 명령은 Keycloak 을 local 8080 포트로 노출하고 username/password = admin/admin 의 초기 admin user 를 생성 [§Start Keycloak] "This command starts Keycloak exposed on the local port 8080 and creates an initial admin user with the username admin and password admin." official-vendor-doc 첫 booting 시점 admin password 를 그대로 두고 production 운영해도 된다는 뜻 아님 — quickstart 한정
KC-GSD-C3 Keycloak 의 realm = tenant. 각 realm 은 application/user 의 isolated group 을 제공 [§Create a realm] "A realm in Keycloak is equivalent to a tenant. Each realm allows an administrator to create isolated groups of applications and users." official-vendor-doc Keycloak multi-tenancy 모델 일반 realm 간 cross-realm trust 또는 federation 의 디테일은 본 인용 범위 밖
KC-GSD-C4 Client 등록 시 Valid redirect URIs 와 Web origins 는 정확한 URI/origin 값으로 설정 (quickstart 예시: https://www.keycloak.org/app/* + https://www.keycloak.org) [§Secure the first application] "Set Valid redirect URIs to https://www.keycloak.org/app/*" + "Set Web origins to https://www.keycloak.org" official-vendor-doc OIDC public client (SPA) 등록 시 redirect_uri + CORS 정책 wildcard /* 매칭의 정확한 보안 영향 / SPA path-level 매칭 규칙은 본 인용에 없음 — 별도 keycloak-google-redirect-uri-policy.md 참조

Usage Boundaries / 적용 경계

  • 이 자료가 직접 증명하는 것:
    • KC-GSD-C1 ~ C4: 학습용 quickstart 의 docker 명령, realm 정의, client 등록 시 redirect_uri/web origins 의 정확한 값 형식
  • 이 자료가 증명하지 않는 것:
    • production deployment 의 hardening 절차 (별도 keycloak-server-containers-docker.md, keycloak-hostname-configuration.md, keycloak-reverseproxy-official.md 참조)
    • start-dev vs start 모드의 정확한 차이 (production-ready 전환 시 변경되는 default)
    • realm export/import JSON 의 schema (별도 페이지)
    • PKCE / Standard Flow 강제 토글의 정확한 위치 (Advanced settings 의 정확한 label)
  • 내 프로젝트에 적용하려면 추가 확인이 필요한 것:
    • P3A 의 redirect_uri 가 http://localhost/callback (localhost+path) 인지 http://<ec2-ip>:8080/callback 인지에 따라 client 등록 값 결정
    • --import-realm 옵션의 정확한 명령 위치 (docker run ... start-dev --import-realm 형태인지)
    • admin 초기 password 를 rotate 하는 권장 명령

quickstart 명령 (인용 그대로)

docker run -p 127.0.0.1:8080:8080 \
  -e KC_BOOTSTRAP_ADMIN_USERNAME=admin \
  -e KC_BOOTSTRAP_ADMIN_PASSWORD=admin \
  quay.io/keycloak/keycloak:26.6.2 start-dev

Realm/Client 생성 절차 (페이지 기준 요약)

  1. http://localhost:8080/admin 접속 (admin/admin 로그인).
  2. 좌측 컬럼 "Manage realms" 클릭.
  3. "Create realm" 선택. 이름 입력 (예: myrealm → P3A 에서는 keycloak-patterns).
  4. "Clients" 섹션에서 "Create client".
    • Client type: OpenID Connect
    • Client ID: myclient (P3A 에서는 spa-client)
  5. Login settings:
    • Valid redirect URIs: quickstart 예시는 https://www.keycloak.org/app/* — P3A 는 실제 SPA callback 으로 변경
    • Web origins: quickstart 예시는 https://www.keycloak.org — P3A 는 실제 SPA origin
  6. Save.

P3A 적용 메모 (내 프로젝트 해석)

본 섹션은 자료 직접 인용 아님. P3A 결정 컨텍스트 해석.

  • Client type public + Standard Flow + PKCE S256 강제 (Advanced settings → Proof Key for Code Exchange Code Challenge Method = S256).
  • redirect_uri 정확 매칭: http://localhost/callback ≠ http://127.0.0.1/callback ≠ http://<ec2-ip>/callback. SPA 가 사용하는 URI 와 한 글자도 다르면 안 됨.
  • realm export: 관리 콘솔 → Realm settings → Action → Partial export → JSON 다운로드. keycloak-patterns-realm.json 으로 commit 하면 docker-compose 에서 --import-realm 옵션으로 자동 임포트 가능 (정확한 명령 형식은 별도 확인).

한계 / 후속

  • 본 문서는 quickstart. production hardening, HA, clustering 은 별도 가이드.
  • 본 wiki 변환 시 wiki/projects/keycloak-patterns (P3A 구현 후) 후보.

Related / 관련

Reference in New Issue View Git Blame Copy Permalink