Keycloak IdP 요구사항

Keycloak IdP 요구사항

identity-contract: authentication_authority: external_idp · authentication_protocol: oidc · session_trust_adapter: pomerium · identity_assertion_mode: oidc_claims · directory_projection_protocol: groups · entitlement_projection_mechanism: realm_admin_role · account_materialization_strategy: federated_session · projection_scope: realm

역할

Keycloak은 조직 계정의 realm/role/group을 관리하는 **단일 인증 권한(IdP)**이다. 토폴로지 (identity_plane.keycloak)에 다음이 명시되어 있다.

• realm: yamon
• base_url: https://keycloak.yamon.io, internal_base_url: http://10.10.10.7:8080
• ct_id: 106
• primary_idp_alias: microsoft (직원 로그인은 Microsoft Entra로 브로커)

Keycloak은 동시에 FractalOps 이벤트 브리지 대상이다(admin event -> ingress).

인증/브로커 흐름

sequenceDiagram
  autonumber
  participant U as 직원
  participant E as Pomerium edge<br/>(auth.yamon.io)
  participant KC as Keycloak realm yamon<br/>(keycloak.yamon.io)
  participant EN as Microsoft Entra<br/>(alias: microsoft)
  participant API as FractalOps API

  U->>E: 보호 호스트 접근
  E->>KC: OIDC authorize
  KC->>EN: identity broker (microsoft)
  Note over KC,EN: broker.prompt="" · login_hint=false<br/>accepts_prompt_none_forward_from_client=true
  EN-->>KC: 인증 성공
  KC-->>E: id_token (email, groups, preferred_username)
  E->>API: x-pomerium-claim-sub / x-pomerium-claim-user 전달
  API->>API: subject_id 유지 (email만 ID로 쓰지 않음)

토폴로지 broker 설정(identity_plane.keycloak.broker)은 다음과 같다.

broker:
  prompt: ""
  extra_params: ""
  login_hint: false
  accepts_prompt_none_forward_from_client: true

필수 기능

• 사용자 직접 비밀번호 로그인은 관리자 계정만 허용한다.
• 일반 직원은 Entra 브로커 경유(비밀번호 입력 없는 흐름)로 로그인한다.
• GitHub 링크 필요 계정은 identity_link_required 상태로 명시한다.

FractalOps 연동

• admin event -> FractalOps ingress 전달.
• principal profile overlay 적용 가능 (identity_plane.principal_profiles_file: /etc/fractalops/principal-profiles.json).
• plugin 방식으로만 확장한다(직접 DB 수정 금지). Keycloak SPI는 platform/plugins/에 위치한다.
• Portal/Pomerium 로그인 버튼에서 로그인 시작점을 명시하고, Entra 직행 리다이렉트는 강제하지 않는다.
• FractalOps는 Keycloak authentication flow/execution을 삭제하거나 재구성하지 않는다.
  • 표준 연산 ID: reconcile_keycloak_idp_instance
  • 동작 스코프: identity-provider/instances/<alias> 설정 조정 (syncMode, loginHint, prompt, optional firstBrokerLoginFlowAlias)

connector 계약

connector inventory(connector_inventory[id=keycloak]):

- id: keycloak
  mode: hybrid
  endpoint: https://keycloak-admin.yamon.io
  openbao_scope: connectors/keycloak
  managed_by: fractalops
  jit:
    strategy: keycloak_admin_client_credentials
    credential_principal_kind: service_account
    credential_principal: fractalops-admin
    credential_rotation: openbao_required

secret delivery(secret_delivery.contracts[scope=connectors/keycloak])는 secret_classes: [admin_client_secret, oidc_broker_config], rotation_strategy: oauth2_client_credentials를 쓴다.

OIDC client 투영

Keycloak은 IdP이자 각 스택의 OIDC client를 발급하는 주체다. catalog의 모든 oidc_client 항목은 Keycloak yamon realm에 client로 투영된다(코드: StackIdentityContractCatalog.get_oidc_clients). 표준 mapper는 다음과 같다.

"mapperConfig": {
  "emailClaim": "email",
  "groupsClaim": "groups",
  "usernameClaim": "preferred_username"
}

Keycloak 자신의 admin 콘솔(keycloak.yamon.io / keycloak-admin.yamon.io)도 Pomerium 보호 호스트다(session_trust.pomerium.protected_hosts).

검증

• 신규 사용자 생성 시 principal_upsert 이벤트가 생성된다.
• role/group 변경이 FractalOps policy 입력(SpiceDB 관계 그래프 backfill)에 반영된다.
• x-pomerium-claim-sub 또는 x-pomerium-claim-user가 Portal principal subject_id로 유지되고 email만 ID로 쓰이지 않는다.
• pnpm verify로 CUE 런타임 계약과 realm/broker 투영을 검증한다.