keycloak-sdk 1.0.1 → 1.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: ced74e5c197f31bcea44f678715d2c2b30d8cfe6b597393a200bda451057f582
-  data.tar.gz: ff1f1781cfc00acfcca781217eedb6be8f76c7efc72f93b49940f9a85882f1b2
+  metadata.gz: 73ecdc82d8bb713a7529ce242c2eacfa8279d9e413ce09aa2e2e468e4fd269c3
+  data.tar.gz: c6670b1e3767730f49604d2215a4650d3630e34b5cac979ecc24d63517c423e3
 SHA512:
-  metadata.gz: 2e4564e3f092dc1161a80e4bd0bb854dd1c05b4c57dd9552db23c8607f5aace485dc5fd160dddcae0e7c27989ddf4b0f4a889e6f365345dc847504afd61c4dea
-  data.tar.gz: 2b4df9762901e5b1c7f43372952a298ee82392a6ab95cabbfd974c737213813266d7c206dcea5ee5f3509330f71a6674edc8ae5017c77a6769783cedb5356e16
+  metadata.gz: 165d9c457ceb36f8b38e0cf622c15175af2ce8643e6ccfdba818143b4ca85a09d7967e0c51422108ce5b906ae6f805e28f0bc44380695f0a530e96cc9b0e01b6
+  data.tar.gz: fcbce56000bd6f42ff3c376b0c8913487792eac3803e7fbbc2a718d58bf1fec6826dc3f99e4d59b61f7cc950116926629766cb408b990347479df87bd2e64f6e

data/README.md

@@ -4,7 +4,7 @@ Authentication (OIDC / OAuth2) and the Admin REST API for [Keycloak](https://www
 
 Part of a **nine-language polyglot SDK** (Java · Python · Node · Go · C# · PHP · Rust · Ruby · Kotlin) — one API surface, isomorphic across all of them: [github.com/xzawed/KeyCloakSDK](https://github.com/xzawed/KeyCloakSDK).
 
-> **`1.0.1` is on RubyGems** — a patch release of security and correctness fixes on top of `1.0.0`, the first release carrying the stability guarantee. A bare `gem install keycloak-sdk` resolves it. Admin path segments are now escaped (an unescaped name could redirect a call to another endpoint), the token provider's default `inspect` no longer prints the cached access token, a token whose expiry is unknown is treated as expired, JWKS responses are size-capped, an empty `200` JWKS key set no longer replaces a good cached one, failed JWKS fetches back off instead of hitting the IdP on every validation, and a token response of the wrong shape is no longer returned as a success. ⚠️ **A `server_url` that is not an absolute http(s) URL now raises `ConfigError` when the config is built**, instead of a stdlib exception on the first call.
+> **`1.2.0` is on RubyGems** — a minor release on top of `1.1.0`; `1.0.0` was the first release carrying the stability guarantee. A bare `gem install keycloak-sdk` resolves it. **Fixed**: with `expected_audience` set to something other than the client_id (a resource server), `exchange_code` with an `expected_nonce:` rejected the server's valid id_token as `invalid id_token` (`Invalid audience`), because the id_token was checked against the same override as access tokens. The id_token's `aud` is now checked for the **client_id** (OIDC Core §2, §3.1.3.7), so that exchange passes, and an id_token without the client_id in `aud` is refused even when it carries the overridden value. `validate` still applies the override to access tokens, and both share one JWKS cache and refetch limit. **Added**: an `audience:` keyword on `JwtValidator#validate(token, audience:)` — omit it and nothing changes; `nil` or a blank value raises `ConfigError`.
 
 ## Requirements
 
@@ -55,7 +55,7 @@ client.admin.users.delete(user_id)
 client.close
 ```
 
-> **Audience:** validation requires the token's `aud` to contain `client_id`. A stock realm does *not* put the client id in a client-credentials token's `aud`, so on a default realm either pass `expected_audience: "my-api"` (the audience your realm actually issues), or add an *Audience* protocol mapper to the client in Keycloak.
+> **Audience:** validation requires the token's `aud` to contain `client_id`. A stock realm does *not* put the client id in a client-credentials token's `aud`, so on a default realm either pass `expected_audience: "my-api"` (the audience your realm actually issues), or add an *Audience* protocol mapper to the client in Keycloak. `expected_audience` applies to access tokens (`validate`) only: the `id_token` that `exchange_code(expected_nonce:)` validates must always carry `client_id` in `aud` (OIDC Core §3.1.3.7).
 
 The five admin resources — `users` / `clients` / `roles` / `groups` / `realms` — offer symmetric CRUD, and `client.admin.raw` is the escape hatch to the underlying bearer-authenticated `Faraday::Connection`.
 

data/lib/keycloak_sdk/admin/call.rb

@@ -32,7 +32,8 @@ module KeycloakSdk
 
         raise AdminError.from_status(resp.status, "admin request failed: HTTP #{resp.status}")
       rescue Faraday::Error => e
-        raise TransportError, "admin transport error: #{e.message}"
+        # 원본을 달면 `Faraday::ParsingError#inspect` 가 요청의 베어러 토큰을, 메시지가 응답 앞부분을 찍는다(실측).
+        raise TransportError, "admin transport error: #{RedactedCause.describe(e)}", cause: RedactedCause.new(e)
       end
 
       def id_from_location(resp)

data/lib/keycloak_sdk/auth_client.rb

@@ -11,6 +11,10 @@ module KeycloakSdk
   class AuthClient
     include TokenProvider
 
+    # 메시지에 실어도 되는 OAuth 오류 코드 모양 — RFC 6749·OIDC 등록 코드와 Keycloak 코드는 전부 이 모양이고,
+    # 토큰·시크릿(JWT·base64·hex·UUID)은 대문자·숫자·점·하이픈 때문에 걸러진다.
+    OAUTH_CODE = /\A[a-z_]{1,64}\z/
+
     def initialize(config:, http:, jwt_validator:)
       @config = config
       @http = http
@@ -35,37 +39,25 @@ module KeycloakSdk
     end
 
     # `expected_nonce`가 주어지면(create_authorization_request가 항상 돌려주는 nonce) 응답 id_token을
-    # realm JWKS로 서명·iss·aud·exp까지 강화 검증한 뒤 nonce 클레임을 대조한다 — OIDC nonce 재생
+    # realm JWKS로 서명·iss·aud(client_id)·exp까지 강화 검증한 뒤 nonce 클레임을 대조한다 — OIDC nonce 재생
     # 방지. 불일치·부재·검증실패는 모두 거부(fail-closed). 생략 시 id_token 검증을 건너뛴다
     # (여덟 언어 공통 — exchange에서 nonce를 필수로 만들지 않는다).
     def exchange_code(code:, code_verifier:, redirect_uri:, expected_nonce: nil)
       client = oauth_client(redirect_uri: redirect_uri)
       client.authorization_code = code
-      token_set = to_token_set(client.access_token!(code_verifier: code_verifier))
+      token_set = token_request("authorization_code exchange") { client.access_token!(code_verifier: code_verifier) }
       verify_nonce!(token_set.id_token, expected_nonce) unless expected_nonce.nil?
       token_set
-    rescue Rack::OAuth2::Client::Error => e
-      raise AuthError.new("authorization_code exchange failed: #{e.message}", oauth_error: e.response[:error].to_s)
-    rescue Faraday::Error => e
-      raise TransportError, "token endpoint transport error: #{e.message}"
     end
 
     def refresh(refresh_token:)
       client = oauth_client
       client.refresh_token = refresh_token
-      to_token_set(client.access_token!)
-    rescue Rack::OAuth2::Client::Error => e
-      raise AuthError.new("refresh failed: #{e.message}", oauth_error: e.response[:error].to_s)
-    rescue Faraday::Error => e
-      raise TransportError, "token endpoint transport error: #{e.message}"
+      token_request("refresh") { client.access_token! }
     end
 
     def client_credentials_token
-      to_token_set(oauth_client.access_token!(scope: @config.scopes.join(" ")))
-    rescue Rack::OAuth2::Client::Error => e
-      raise AuthError.new("client-credentials failed: #{e.message}", oauth_error: e.response[:error].to_s)
-    rescue Faraday::Error => e
-      raise TransportError, "token endpoint transport error: #{e.message}"
+      token_request("client-credentials") { oauth_client.access_token!(scope: @config.scopes.join(" ")) }
     end
 
     # TokenProvider 계약(직접 사용용). admin은 캐싱 provider를 별도로 쓴다.
@@ -81,7 +73,7 @@ module KeycloakSdk
 
       IntrospectionResult.from_response(resp.body)
     rescue Faraday::Error => e
-      raise TransportError, "introspection transport error: #{e.message}"
+      raise TransportError, "introspection transport error: #{RedactedCause.describe(e)}", cause: RedactedCause.new(e)
     end
 
     def logout(refresh_token:)
@@ -93,7 +85,7 @@ module KeycloakSdk
 
       nil
     rescue Faraday::Error => e
-      raise TransportError, "logout transport error: #{e.message}"
+      raise TransportError, "logout transport error: #{RedactedCause.describe(e)}", cause: RedactedCause.new(e)
     end
 
     def validate(token)
@@ -112,14 +104,13 @@ module KeycloakSdk
       end
     end
 
-    # id_token의 nonce 클레임을 대조하기 전에 강화 JwtValidator로 서명·iss·aud·exp까지 검증한다
-    # (액세스 토큰과 id_token 모두 aud=client_id이므로 검증기를 공유해도 안전 — Kotlin/.NET 동형).
-    # ⚠️ `config.expected_audience`를 설정하면 이 공유 검증기가 id_token에도 그 값을 요구한다 —
-    # 이 흐름을 쓴다면 해당 오디언스를 id_token에도 매핑해야 한다(audience 매퍼의 "Add to ID token").
+    # id_token의 nonce 클레임을 대조하기 전에 강화 JwtValidator로 서명·iss·aud·exp까지 검증한다.
+    # aud 는 `expected_audience` 재정의가 아니라 **client_id** 다(OIDC Core §2·§3.1.3.7) — 재정의는 액세스 토큰의 것.
+    # 검증기(=키 저장소)는 `validate` 와 같은 하나를 쓴다.
     def verify_nonce!(id_token, expected_nonce)
       raise AuthError, "authorization_code exchange failed: missing id_token for nonce validation" if id_token.nil?
 
-      validated = @jwt_validator.validate(id_token)
+      validated = @jwt_validator.validate(id_token, audience: @config.client_id)
       return if validated.claims["nonce"] == expected_nonce
 
       raise AuthError, "authorization_code exchange failed: unexpected nonce"
@@ -127,6 +118,27 @@ module KeycloakSdk
       raise AuthError, "authorization_code exchange failed: invalid id_token: #{e.message}"
     end
 
+    # rack-oauth2 토큰 호출의 오류 경계(§4). 하위 예외는 SDK 타입이 되고 `cause` 에는 원본 대신 `RedactedCause` 가 달린다.
+    # ⚠️ OAuth 오류는 **코드와 HTTP 상태만** 싣는다 — `error_description` 은 서버가 고른 자유 문장이라 토큰을
+    # 되울릴 수 있고, 오류 본문이 JSON 이 아니면 rack-oauth2 가 본문 전체를 거기 넣는다. 코드 자리도 서버 값이라
+    # **코드 모양**(`OAUTH_CODE` — 등록 코드는 전부 소문자·밑줄)일 때만 메시지에 싣는다(`oauth_error` 에는 그대로).
+    # ⚠️ 마지막 `StandardError` 는 rack-oauth2 가 형식이 틀린 200 을 읽다 내는 것(NoMethodError·AttrMissing·
+    # 'Unknown Token Type')과 `to_token_set` 의 형 변환 실패다 — 원본이 새면 Ruby 3.2 의 NoMethodError 가 본문을 인용한다.
+    def token_request(operation)
+      to_token_set(yield)
+    rescue Error
+      raise
+    rescue Rack::OAuth2::Client::Error => e
+      code = e.response[:error].is_a?(String) ? e.response[:error] : ""
+      shown = code.match?(OAUTH_CODE) ? code : "non-standard error code"
+      raise AuthError.new("#{operation} failed: #{shown} (HTTP #{e.status})", oauth_error: code),
+            cause: RedactedCause.new(e)
+    rescue Faraday::Error => e
+      raise TransportError, "token endpoint transport error: #{RedactedCause.describe(e)}", cause: RedactedCause.new(e)
+    rescue StandardError => e
+      raise AuthError, "#{operation} failed: unusable token response (#{e.class})", cause: RedactedCause.new(e)
+    end
+
     def oauth_client(redirect_uri: nil)
       Rack::OAuth2::Client.new(
         identifier: @config.client_id,
@@ -137,17 +149,19 @@ module KeycloakSdk
       )
     end
 
+    # `expires_in` 은 `TokenSet.from_response` 와 같이 정수로 읽는다(문자열 "300" 허용) — 예전에는 문자열이면
+    # `Float + String` 의 TypeError 가 경계를 뚫었다. 변환 실패는 `token_request` 가 AuthError 로 바꾼다.
     def to_token_set(token)
       raw = token.raw_attributes || {}
-      scope = raw[:scope] || raw["scope"]
+      expires_in = token.expires_in && Integer(token.expires_in)
       TokenSet.new(
         access_token: token.access_token,
         token_type: "Bearer",
-        expires_in: token.expires_in,
+        expires_in: expires_in,
         refresh_token: token.refresh_token,
         id_token: raw[:id_token] || raw["id_token"],
-        scope: scope,
-        expires_at: token.expires_in ? Time.now.to_f + token.expires_in : nil
+        scope: raw[:scope] || raw["scope"],
+        expires_at: expires_in ? Time.now.to_f + expires_in : nil
       )
     end
   end

data/lib/keycloak_sdk/errors.rb

@@ -1,5 +1,9 @@
 # frozen_string_literal: true
 
+require "openssl"
+require "socket"
+require "timeout"
+
 module KeycloakSdk
   # 모든 SDK 오류의 루트.
   class Error < StandardError; end
@@ -46,4 +50,39 @@ module KeycloakSdk
   class NotFoundError < AdminError; end
   class ConflictError < AdminError; end
   class ForbiddenError < AdminError; end
+
+  # SDK 오류의 `cause` 에 원본 하위 예외 대신 다는 사본 — **클래스 이름 사슬과 백트레이스만** 옮긴다.
+  # 경계는 `raise …, cause: RedactedCause.new(e)` 로 단다(`KeycloakSdk::Error` 가 아니다 — 원인 자리에만 있다).
+  #
+  # ⚠️ Ruby 는 `rescue` 안의 `raise` 가 처리 중인 예외를 `cause` 에 **자동으로** 달고, `full_message`(잡히지 않은
+  # 예외·로거)가 그 사슬의 메시지를 찍는다. 하위 예외는 응답을 싣는다 — JSON 파서는 본문 앞 32 바이트를,
+  # rack-oauth2 는 `error_description`(JSON 이 아닌 오류면 본문 전체)을, Net::HTTP 는 깨진 상태 줄을 메시지에 싣고,
+  # `Faraday::ParsingError#inspect` 는 **요청** 본문·헤더(클라이언트 시크릿·refresh 토큰·베어러)까지 찍었다. Ruby 3.2 의
+  # `NoMethodError` 는 수신자(응답 본문)를 인용했다(실측 2026-09-26 · `spec/unit/hostile_token_response_spec.rb`).
+  # 원본 객체를 공개 API 로 내보내지 않는 것은 §4 도 요구한다.
+  class RedactedCause < StandardError
+    # 메시지를 SDK 메시지로 옮겨도 되는 하위 원인 — 응답을 인용할 수 없는 소켓·타임아웃·TLS 실패뿐이다.
+    # ⚠️ `Faraday::ConnectionFailed` 를 통째로 넣지 않는다 — `Net::HTTPBadResponse`(깨진 상태 줄 dump)도 그것으로 온다.
+    QUOTE_FREE = [SystemCallError, SocketError, IOError, Timeout::Error, OpenSSL::SSL::SSLError].freeze
+
+    # 원본과 그 `cause` 들의 클래스 이름(바깥부터).
+    attr_reader :lower_classes
+
+    def initialize(error)
+      @lower_classes = []
+      link = error
+      while link && @lower_classes.size < 8
+        @lower_classes << link.class.name
+        link = link.cause
+      end
+      super("#{@lower_classes.join(' <- ')} (message withheld: it can quote the response)")
+      set_backtrace(error.backtrace) if error.backtrace
+    end
+
+    # SDK 메시지에 실을 하위 오류 설명 — 인용할 수 없는 연결 실패면 그 메시지, 아니면 클래스 이름뿐.
+    def self.describe(error)
+      origin = error.respond_to?(:wrapped_exception) && error.wrapped_exception ? error.wrapped_exception : error
+      QUOTE_FREE.any? { |k| origin.is_a?(k) } ? error.message : error.class.name
+    end
+  end
 end

data/lib/keycloak_sdk/jwks_store.rb

@@ -122,11 +122,11 @@ module KeycloakSdk
       body = begin
         JSON.parse(buf)
       rescue JSON::ParserError => e
-        raise TransportError, "JWKS response unparsable: #{e.message}"
+        raise TransportError, "JWKS response unparsable (JSON::ParserError)", cause: RedactedCause.new(e)
       end
       validate_key_set!(body)
     rescue Faraday::Error => e
-      raise TransportError, "JWKS transport error: #{e.message}"
+      raise TransportError, "JWKS transport error: #{RedactedCause.describe(e)}", cause: RedactedCause.new(e)
     end
 
     # 파싱된 본문이 **캐시에 올려도 되는 집합인가**. 통과하면 그 본문을 돌려준다.

data/lib/keycloak_sdk/jwt_validator.rb

@@ -30,21 +30,28 @@ module KeycloakSdk
           algorithms: config.signature_algorithms, clock_skew: config.clock_skew)
     end
 
-    def validate(token)
-      payload, = JWT.decode(token, nil, true, decode_options)
+    # `audience:` 는 이 호출만의 기대 aud 다(기본 = 생성 시 값). 코드 교환이 id_token 을 client_id 로 검사할 때
+    # 쓴다 — 키 저장소(캐시 · 재조회 제한 · 백오프)는 그대로 이 인스턴스의 것 하나다.
+    # ⚠️ nil·공백은 생성자와 같이 ConfigError — ruby-jwt 는 `aud: nil` 이면 aud 검사를 건너뛴다.
+    def validate(token, audience: @audience)
+      raise ConfigError, "audience is required" if audience.nil? || audience.to_s.strip.empty?
+
+      payload, = JWT.decode(token, nil, true, decode_options(audience))
       to_validated(payload)
     rescue JWT::DecodeError => e
-      raise TokenValidationError, "JWT validation failed: #{e.message}"
+      # ruby-jwt 메시지는 입력을 인용하지 않는다. 그 **원인**은 인용한다 — 조각이 JSON 이 아니면 JSON::ParserError 가
+      # 디코드한 토큰 조각을 싣는다(실측) — 그래서 사슬은 `RedactedCause` 로 끊는다.
+      raise TokenValidationError, "JWT validation failed: #{e.message}", cause: RedactedCause.new(e)
     end
 
     private
 
-    def decode_options
+    def decode_options(audience)
       {
         algorithms: @algorithms,
         jwks: jwks_loader,
         verify_iss: true, iss: @issuer,
-        verify_aud: true, aud: @audience,
+        verify_aud: true, aud: audience,
         verify_expiration: true,
         verify_not_before: true,
         required_claims: %w[exp iss aud],

data/lib/keycloak_sdk/token_provider.rb

@@ -59,7 +59,7 @@ module KeycloakSdk
 
       TokenSet.from_response(resp.body, received_at: Time.now.to_f)
     rescue Faraday::Error => e
-      raise TransportError, "token endpoint transport error: #{e.message}"
+      raise TransportError, "token endpoint transport error: #{RedactedCause.describe(e)}", cause: RedactedCause.new(e)
     end
   end
 end

data/lib/keycloak_sdk/tokens.rb

@@ -17,6 +17,9 @@ module KeycloakSdk
     end
 
     def self.from_response(body, received_at: Time.now.to_f)
+      # 배열 본문은 `Array#[]` 의 TypeError 로 경계를 뚫었다 — 객체가 아니면 SDK 오류다.
+      raise AuthError, "token response is not a JSON object" unless body.is_a?(Hash)
+
       # ⚠️ **존재 검사는 타입 검사가 아니다.** 예전에는 값을 그대로 담아 숫자·해시·nil 이
       # `access_token` 이 됐고, 소비자는 그것을 Bearer 로 실어 보내 매번 401 을 받았다
       # (조용한 반복 실패). `expires_in` 의 문자열 허용은 **의도된 것**이라 건드리지 않는다.
@@ -25,7 +28,12 @@ module KeycloakSdk
         raise AuthError, "token response has no usable access_token"
       end
 
-      expires_in = body["expires_in"] && Integer(body["expires_in"])
+      expires_in = begin
+        body["expires_in"] && Integer(body["expires_in"])
+      rescue ArgumentError, TypeError, RangeError # RangeError: JSON 1e400 = Infinity → FloatDomainError
+        # `cause: nil` — ArgumentError 는 그 값을 인용한다(`invalid value for Integer(): "…"`).
+        raise AuthError, "token response has an unusable expires_in", cause: nil
+      end
       new(
         access_token: access_token,
         token_type: body["token_type"],
@@ -67,7 +75,10 @@ module KeycloakSdk
 
   # RFC 7662 introspection 결과.
   IntrospectionResult = Data.define(:active, :username, :client_id, :claims) do
+    # 객체가 아닌 본문은 SDK 오류다 — 배열은 TypeError 로 경계를 뚫었고, 문자열은 `claims` 가 문자열인 결과가 됐다.
     def self.from_response(body)
+      raise AuthError, "introspection response is not a JSON object" unless body.is_a?(Hash)
+
       new(active: body["active"] == true, username: body["username"],
           client_id: body["client_id"], claims: body)
     end

data/lib/keycloak_sdk/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module KeycloakSdk
-  VERSION = "1.0.1"
+  VERSION = "1.2.0"
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: keycloak-sdk
 version: !ruby/object:Gem::Version
-  version: 1.0.1
+  version: 1.2.0
 platform: ruby
 authors:
 - xzawed