kinetic_sdk 7.0.0.rc3 → 7.0.0.rc4

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 7728373bd9c4a15c643c54aed99acd289e5f776ee0819c8b14f7aea9ec54c106
-  data.tar.gz: d22c5e6907360c11cb886dfb2c58f5c80c5434fcd2b8d669f846b074a57d78ae
+  metadata.gz: 0ab81a960e1aebbf2e7cd839fdf3fd60c33ca71e985e0c6530c7e84ca8e8ec6f
+  data.tar.gz: d485a88f2085aa142c0015c2899999d46c403f66b8b460efffb0918730ca51aa
 SHA512:
-  metadata.gz: 0eaa0e7c58dead1010dbd1bd7964f42cf762a712ab7bc888037e6a8e6709b2af1b2562df834ed0d759cc1e677473ffacad035582b10542baaaf45d58401c4979
-  data.tar.gz: f882b337544ec35443094eb971e821859d9480994ab7200519f090607672bc4e35ae284a04bb84aa2ffdc7fb15f1e6755c9712905c9188c518bb3751a06fdde3
+  metadata.gz: dbd1dbf0607dc20f54e2cbea981496d1fbc8088c8b00fa8ce6483317577fe15bff2b8ae3328d7e797506dea4db66a9cc5c6d3b3ca491bdc99a0ff6fd144e9725
+  data.tar.gz: 86092ddc85c919ace2d1bb3133c8feb9aa320969162e471cc100617b81fef05fa0dc5b644c770dbb1a41ebc8c4b6e8aa53586bcc31463b966caef2fb44aa74fe

data/CHANGELOG.md

@@ -1,6 +1,40 @@
 # Change Log
 
 
+## [7.0.0.rc4](https://github.com/kineticdata/kinetic-sdk-rb/tree/7.0.0.rc4) (2026-09-01)
+
+**Breaking changes:**
+
+- `jwt_token` now uses the OAuth 2.0 `client_credentials` grant, a single POST to
+  `/{space_slug}/app/oauth2/token`. Kinetic Platform 7 runs a standards compliant
+  authorization server in which `/app/oauth2/authorize` is an interactive endpoint
+  requiring a browser session, consent, a registered redirect_uri and PKCE, so the
+  previous authorization-code flow returned `400`. The response shape is unchanged:
+  callers reading `jwt_response.content["access_token"]` are unaffected.
+- `jwt_code` has been removed. It drove the authorization-code flow that no longer
+  applies to machine to machine clients.
+- The OAuth client used by the SDK must be registered in the space as a **confidential**
+  client (or with no `clientType`, which defaults to confidential). Public clients and
+  the built in system client register only the `authorization_code` grant and are
+  rejected by the token endpoint.
+
+**Fixed bugs:**
+
+- The OAuth routes are now space scoped (`/{space_slug}/app/oauth2/...`) when the SDK is
+  built from an `:app_server_url` plus a `:space_slug`. The authorization server resolves
+  the space from the request path and rejects requests made outside a space context.
+- OAuth failures now report the `error` and `error_description` from a JSON error, or the
+  `X-Kinetic-CID` correlation id when Core answers with its generic HTML error page,
+  instead of dumping the inspected response object.
+
+**Implemented enhancements:**
+
+- Added the `:oauth_scope` option, defaulting to `full`. Valid scopes are `full`, `read`,
+  `write`, `admin`, `submissions` and `submissions:read`.
+- Added specs covering the token exchange, scope configuration, and the failure modes for
+  both the Integrator and Discussions SDKs.
+
+
 ## [7.0.0.rc3](https://github.com/kineticdata/kinetic-sdk-rb/tree/7.0.0.rc3) (2026-09-01)
 
 **Fixed bugs:**

data/lib/kinetic_sdk/core/core-sdk.rb

@@ -14,7 +14,8 @@ module KineticSdk
     include KineticSdk::Utils::KineticExportUtils
 
     attr_reader :api_url, :username, :options, :password, :proxy_url,
-                :space_slug, :server, :version, :logger
+                :space_slug, :server, :version, :logger, :oauth_url,
+                :oauth_scope
 
     # Initalize the Core SDK with the web server URL, the space user
     # username and password, along with any custom option values.
@@ -55,6 +56,8 @@ module KineticSdk
     #   * :max_redirects (Fixnum) (_defaults to: 5_) maximum number of redirects to follow
     #   * :ssl_ca_file (String) full path to PEM certificate used to verify the server
     #   * :ssl_verify_mode (String) (_defaults to: none_) - none | peer
+    #   * :oauth_scope (String) (_defaults to: full_) scope requested when retrieving a
+    #     JWT - full | read | write | admin | submissions | submissions:read
     #
     # Example: using a configuration file
     #
@@ -154,12 +157,17 @@ module KineticSdk
         @server = options[:app_server_url].chomp('/')
         @api_url = @server + (@space_slug.nil? ? "/app/api/v1" : "/#{@space_slug}/app/api/v1")
         @proxy_url = @space_slug.nil? ? nil : "#{@server}/#{@space_slug}/app/components"
+        # The authorization server resolves the space from the request path, so the
+        # OAuth routes must be space scoped exactly like the API routes.
+        @oauth_url = @server + (@space_slug.nil? ? "/app/oauth2" : "/#{@space_slug}/app/oauth2")
       else
         raise StandardError.new "The :space_slug option is required when using the :space_server_url option" if @space_slug.nil?
         @server = options[:space_server_url].chomp('/')
         @api_url = "#{@server}/app/api/v1"
         @proxy_url = "#{@server}/app/components"
+        @oauth_url = "#{@server}/app/oauth2"
       end
+      @oauth_scope = @options[:oauth_scope] || @options["oauth_scope"] || "full"
       @version = 1
     end
 

data/lib/kinetic_sdk/core/lib/jwt.rb

@@ -1,55 +1,79 @@
 module KineticSdk
   class Core
 
-    # Gets an authentication token
+    # Gets an authentication token using the OAuth 2.0 client credentials grant.
+    #
+    # Kinetic Platform 7 runs a standards compliant authorization server, in which
+    # `/app/oauth2/authorize` is an interactive endpoint: it expects an authenticated
+    # browser session, a consent round trip, a registered redirect_uri, and PKCE. A
+    # machine to machine client cannot drive it, and should not try - it exchanges its
+    # own credentials for a token directly at the token endpoint instead.
+    #
+    # The OAuth client must be registered in the space as a confidential client (or with
+    # no clientType, which defaults to confidential) so that it carries the
+    # `client_credentials` grant. Public clients and the built in system client support
+    # only `authorization_code`, and will be rejected here.
     #
     # @param client_id [String] the oauth client id
     # @param client_secret [String] the oauth client secret
-    # @param headers [Hash] hash of headers to send, default is basic authentication and accept JSON content type
+    # @param headers [Hash] additional headers to send. The Accept, Authorization and
+    #   Content-Type headers required by the token endpoint always take precedence.
+    # @param scope [String] scope to request, defaults to the +:oauth_scope+ option (+full+)
     # @return [KineticSdk::Utils::KineticHttpResponse] object, with +code+, +message+, +content_string+, and +content+ properties
-    def jwt_token(client_id, client_secret, headers = default_headers)
-      # retrieve the jwt code
-      jwt_code = jwt_code(client_id, headers)
-      # retrieve the jwt token
+    def jwt_token(client_id, client_secret, headers = {}, scope = oauth_scope)
       @logger.info("Retrieving JWT authorization token")
-      url = "#{@server}/app/oauth2/token?grant_type=authorization_code&response_type=token&client_id=#{client_id}&code=#{jwt_code}"
-      token_headers = header_accept_json.merge(header_basic_auth(client_id, client_secret))
-      response = post(url, {}, token_headers, { :max_redirects => 0 })
+      url = "#{@oauth_url}/token"
+
+      # The required headers are merged last so that a caller passing the SDK default
+      # headers cannot replace the client's basic authentication with the user's.
+      token_headers = headers
+        .merge(header_accept_json)
+        .merge(header_basic_auth(client_id, client_secret))
+        .merge({ "Content-Type" => "application/x-www-form-urlencoded" })
+
+      payload = { "grant_type" => "client_credentials" }
+      payload["scope"] = scope unless scope.nil? || scope.to_s.empty?
 
-      if response.status == 401
-        raise StandardError.new "#{response.message}, the oauth client id and secret are invalid."
-      elsif response.status == 200
+      # Redirects are not followed: the token endpoint has no reason to redirect, and
+      # following one would forward the client credentials to another host.
+      response = post(url, URI.encode_www_form(payload), token_headers, { :max_redirects => 0 })
+
+      case response.status
+      when 200
         response
+      when 401
+        raise StandardError.new(
+          "Unable to retrieve token: #{oauth_error_message(response)}. The oauth client id " \
+          "and secret are invalid, or no such client is registered in this space."
+        )
       else
-        raise StandardError.new "Unable to retrieve token: #{response}"
+        raise StandardError.new("Unable to retrieve token: #{oauth_error_message(response)}")
       end
     end
 
-    # Gets an authentication code.
+    private
+
+    # Builds an actionable message from an OAuth error response.
     #
-    # This method should really never need to be called externally.
+    # The authorization server answers most failures with a JSON OAuth error, but falls
+    # back to Core's generic HTML error page for others. That page carries no error code,
+    # only a correlation id in the X-Kinetic-CID response header, which is what is needed
+    # to find the matching entry in the server log.
     #
-    # @param client_id [String]
-    # @param headers [Hash] hash of headers to send, default is basic authentication and accept JSON content type
-    # @return [KineticSdk::Utils::KineticHttpResponse] object, with +code+, +message+, +content_string+, and +content+ properties
-    def jwt_code(client_id, headers = default_headers)
-      @logger.info("Retrieving JWT authorization code")
-      url = "#{@server}/app/oauth2/authorize?grant_type=authorization_code&response_type=code&client_id=#{client_id}"
-      response = post(url, {}, headers, { :max_redirects => -1 })
-
-      if response.status == 401
-        raise StandardError.new "#{response.message}: #{response.content["error"]}"
-      elsif response.status == 302 || response.status == 303
-        location = response.headers["location"]
-        if location.nil?
-          raise StandardError.new "Unable to retrieve code: #{response.inspect}"
-        elsif !location.include?("?code=")
-          raise StandardError.new "Unable to retrieve code, the authorize endpoint redirected to #{location} without an authorization code."
-        else
-          location.split("?code=").last.split("#/").first
-        end
+    # @param response [KineticSdk::Utils::KineticHttpResponse] the failed response
+    # @return [String] a single line description of the failure
+    def oauth_error_message(response)
+      content = response.content.is_a?(Hash) ? response.content : {}
+      if content["error"]
+        message = "#{response.status} #{content["error"]}"
+        message += " - #{content["error_description"]}" if content["error_description"]
+        message
       else
-        raise StandardError.new "Unable to retrieve code #{response.inspect}"
+        message = "#{response.status} #{response.message}"
+        headers = response.headers
+        correlation_id = headers.is_a?(Hash) ? headers["x-kinetic-cid"] : nil
+        message += " (correlation id #{correlation_id})" if correlation_id
+        message
       end
     end
   end

data/lib/kinetic_sdk/version.rb

@@ -3,5 +3,5 @@ module KineticSdk
   # Version of Kinetic SDK
   #
   # @return [String] Version of the SDK
-  VERSION = "7.0.0.rc3"
+  VERSION = "7.0.0.rc4"
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: kinetic_sdk
 version: !ruby/object:Gem::Version
-  version: 7.0.0.rc3
+  version: 7.0.0.rc4
 platform: ruby
 authors:
 - Kinetic Data