devise_scim 0.1.11

data/lib/devise_scim/rspec/shared_examples/groups_endpoint.rb

@@ -0,0 +1,148 @@
+# frozen_string_literal: true
+
+# rubocop:disable Metrics/BlockLength
+RSpec.shared_examples "a SCIM Groups endpoint" do |_options = {}|
+  include DeviseScim::RSpec::ScimHelpers
+
+  let(:_scim_test_token) { "scim-test-token-#{SecureRandom.hex(8)}" }
+  let(:_scim_headers)    { scim_auth_headers(_scim_test_token) }
+
+  before do
+    DeviseScim.configure do |c|
+      c.tenancy       = :single
+      c.auth_method   = :token
+      c.token         = _scim_test_token
+      c.enable_groups = true
+    end
+  end
+
+  after { DeviseScim.reset_configuration! }
+
+  # ── GET /Groups ──────────────────────────────────────────────────────────────
+
+  describe "GET /Groups" do
+    it "returns 200 with an empty ListResponse" do
+      get "#{scim_prefix}/Groups", headers: _scim_headers
+      expect(response).to have_http_status(:ok)
+      body = scim_json(response.body)
+      expect(body["schemas"]).to include(DeviseScim::Scim::LIST_RESPONSE_SCHEMA)
+      expect(body["Resources"]).to eq([])
+    end
+
+    it "sets Content-Type to application/scim+json" do
+      get "#{scim_prefix}/Groups", headers: _scim_headers
+      expect(response.content_type).to include("application/scim+json")
+    end
+  end
+
+  # ── POST /Groups ─────────────────────────────────────────────────────────────
+
+  describe "POST /Groups" do
+    let(:_group_payload) do
+      { "schemas" => [DeviseScim::Scim::GROUP_SCHEMA], "displayName" => "Test Group" }
+    end
+
+    context "when the adapter implements group_to_scim" do
+      let(:_group_scim_obj) do
+        grp = DeviseScim::Scim::Group.new
+        grp.id = "test-grp-1"
+        grp.display_name = "Test Group"
+        grp
+      end
+      let(:_adapter_spy) do
+        instance_double(DeviseScim::ScimAdapter,
+                        handle_group_create: nil,
+                        group_to_scim: _group_scim_obj)
+      end
+
+      before { allow(DeviseScim::ScimAdapter).to receive(:new).and_return(_adapter_spy) }
+
+      it "calls handle_group_create on the adapter" do
+        post "#{scim_prefix}/Groups", params: _group_payload.to_json, headers: _scim_headers
+        expect(_adapter_spy).to have_received(:handle_group_create)
+      end
+
+      it "returns 201 with the group representation" do
+        post "#{scim_prefix}/Groups", params: _group_payload.to_json, headers: _scim_headers
+        expect(response).to have_http_status(:created)
+        body = scim_json(response.body)
+        expect(body["displayName"]).to eq("Test Group")
+      end
+    end
+
+    context "when the adapter does not implement group_to_scim (default)" do
+      it "returns 500" do
+        post "#{scim_prefix}/Groups", params: _group_payload.to_json, headers: _scim_headers
+        expect(response).to have_http_status(:internal_server_error)
+      end
+    end
+  end
+
+  # ── GET /Groups/:id ──────────────────────────────────────────────────────────
+
+  describe "GET /Groups/:id" do
+    let(:_group_scim_obj) do
+      grp = DeviseScim::Scim::Group.new
+      grp.id = "grp-42"
+      grp.display_name = "My Group"
+      grp
+    end
+    let(:_adapter_spy) do
+      instance_double(DeviseScim::ScimAdapter, group_to_scim: _group_scim_obj)
+    end
+
+    before { allow(DeviseScim::ScimAdapter).to receive(:new).and_return(_adapter_spy) }
+
+    it "returns 200 with the group serialised by the adapter" do
+      get "#{scim_prefix}/Groups/grp-42", headers: _scim_headers
+      expect(response).to have_http_status(:ok)
+      body = scim_json(response.body)
+      expect(body["id"]).to eq("grp-42")
+    end
+  end
+
+  # ── PATCH /Groups/:id ────────────────────────────────────────────────────────
+
+  describe "PATCH /Groups/:id" do
+    let(:_group_scim_obj) do
+      grp = DeviseScim::Scim::Group.new
+      grp.id = "grp-42"
+      grp.display_name = "Updated Group"
+      grp
+    end
+    let(:_adapter_spy) do
+      instance_double(DeviseScim::ScimAdapter,
+                      handle_group_update: nil,
+                      group_to_scim: _group_scim_obj)
+    end
+
+    before { allow(DeviseScim::ScimAdapter).to receive(:new).and_return(_adapter_spy) }
+
+    it "calls handle_group_update on the adapter and returns 200" do
+      payload = {
+        "schemas" => ["urn:ietf:params:scim:api:messages:2.0:PatchOp"],
+        "Operations" => [{ "op" => "replace", "value" => { "displayName" => "Updated Group" } }]
+      }
+      patch "#{scim_prefix}/Groups/grp-42", params: payload.to_json, headers: _scim_headers
+      expect(response).to have_http_status(:ok)
+      expect(_adapter_spy).to have_received(:handle_group_update)
+    end
+  end
+
+  # ── DELETE /Groups/:id ───────────────────────────────────────────────────────
+
+  describe "DELETE /Groups/:id" do
+    let(:_adapter_spy) do
+      instance_double(DeviseScim::ScimAdapter, handle_group_destroy: nil)
+    end
+
+    before { allow(DeviseScim::ScimAdapter).to receive(:new).and_return(_adapter_spy) }
+
+    it "calls handle_group_destroy on the adapter and returns 204" do
+      delete "#{scim_prefix}/Groups/grp-42", headers: _scim_headers
+      expect(response).to have_http_status(:no_content)
+      expect(_adapter_spy).to have_received(:handle_group_destroy)
+    end
+  end
+end
+# rubocop:enable Metrics/BlockLength

data/lib/devise_scim/rspec/shared_examples/users_endpoint.rb

@@ -0,0 +1,301 @@
+# frozen_string_literal: true
+
+# rubocop:disable Metrics/BlockLength
+RSpec.shared_examples "a SCIM Users endpoint" do |options = {}|
+  include DeviseScim::RSpec::ScimHelpers
+
+  let(:_scim_model)      { options[:devise_model] || raise(ArgumentError, "devise_model: is required") }
+  let(:_scim_test_token) { "scim-test-token-#{SecureRandom.hex(8)}" }
+  let(:_scim_headers)    { scim_auth_headers(_scim_test_token) }
+  let(:_scim_email)      { "scim.user@example.com" }
+
+  before do
+    DeviseScim.configure do |c|
+      c.tenancy     = :single
+      c.auth_method = :token
+      c.token       = _scim_test_token
+    end
+  end
+
+  after { DeviseScim.reset_configuration! }
+
+  # ── GET /Users ─────────────────────────────────────────────────────────────
+
+  describe "GET /Users" do
+    let!(:_listed_user) { _scim_model.create!(email: _scim_email) }
+
+    it "returns 200 with ListResponse schema" do
+      get "#{scim_prefix}/Users", headers: _scim_headers
+      expect(response).to have_http_status(:ok)
+      body = scim_json(response.body)
+      expect(body["schemas"]).to include(DeviseScim::Scim::LIST_RESPONSE_SCHEMA)
+      expect(body).to have_key("totalResults")
+      expect(body).to have_key("Resources")
+    end
+
+    it "includes the user in Resources" do
+      get "#{scim_prefix}/Users", headers: _scim_headers
+      usernames = scim_json(response.body)["Resources"].map { |u| u["userName"] }
+      expect(usernames).to include(_scim_email)
+    end
+
+    it "sets Content-Type to application/scim+json" do
+      get "#{scim_prefix}/Users", headers: _scim_headers
+      expect(response.content_type).to include("application/scim+json")
+    end
+
+    context "with filter" do
+      before { _scim_model.create!(email: "other@example.com") }
+
+      it "filters by userName eq" do
+        get "#{scim_prefix}/Users?filter=userName eq \"#{_scim_email}\"", headers: _scim_headers
+        body = scim_json(response.body)
+        expect(body["totalResults"]).to eq(1)
+        expect(body["Resources"].first["userName"]).to eq(_scim_email)
+      end
+
+      it "returns 400 with invalidFilter scimType for a bad filter" do
+        get "#{scim_prefix}/Users?filter=!!!bad", headers: _scim_headers
+        expect(response).to have_http_status(:bad_request)
+        body = scim_json(response.body)
+        expect(body["scimType"]).to eq("invalidFilter")
+      end
+    end
+  end
+
+  # ── POST /Users ─────────────────────────────────────────────────────────────
+
+  describe "POST /Users" do
+    let(:_create_payload) { scim_user_payload(user_name: _scim_email) }
+
+    it "creates a user and returns 201" do
+      expect do
+        post "#{scim_prefix}/Users", params: _create_payload.to_json, headers: _scim_headers
+      end.to change(_scim_model, :count).by(1)
+      expect(response).to have_http_status(:created)
+      body = scim_json(response.body)
+      expect(body["userName"]).to eq(_scim_email)
+    end
+
+    it "sets scim_source to 'scim' on the created user" do
+      post "#{scim_prefix}/Users", params: _create_payload.to_json, headers: _scim_headers
+      user = _scim_model.find_by(email: _scim_email)
+      expect(user.scim_source).to eq("scim") if user.respond_to?(:scim_source)
+    end
+
+    it "returns 409 when the user already exists and is active" do
+      _scim_model.create!(email: _scim_email, scim_source: "scim")
+      post "#{scim_prefix}/Users", params: _create_payload.to_json, headers: _scim_headers
+      expect(response).to have_http_status(:conflict)
+    end
+
+    it "re-provisions a deprovisioned SCIM user" do
+      existing = _scim_model.create!(email: _scim_email, scim_source: "scim", scim_active: false)
+      post "#{scim_prefix}/Users", params: _create_payload.to_json, headers: _scim_headers
+      expect(response).to have_http_status(:created)
+      expect(existing.reload.scim_active).to be(true)
+    end
+  end
+
+  # ── GET /Users/:id ───────────────────────────────────────────────────────────
+
+  describe "GET /Users/:id" do
+    let!(:_shown_user) { _scim_model.create!(email: _scim_email) }
+
+    it "returns the user by id" do
+      get "#{scim_prefix}/Users/#{_shown_user.id}", headers: _scim_headers
+      expect(response).to have_http_status(:ok)
+      body = scim_json(response.body)
+      expect(body["id"]).to eq(_shown_user.id.to_s)
+      expect(body["userName"]).to eq(_scim_email)
+    end
+
+    it "returns 404 with SCIM error for an unknown id" do
+      get "#{scim_prefix}/Users/0", headers: _scim_headers
+      expect(response).to have_http_status(:not_found)
+      body = scim_json(response.body)
+      expect(body["status"]).to eq("404")
+      expect(body["schemas"]).to include(DeviseScim::Scim::ERROR_SCHEMA)
+    end
+  end
+
+  # ── PUT /Users/:id ───────────────────────────────────────────────────────────
+
+  describe "PUT /Users/:id" do
+    let!(:_replaced_user) { _scim_model.create!(email: "old@example.com") }
+
+    it "replaces user attributes and returns 200" do
+      payload = scim_user_payload(user_name: "updated@example.com")
+      put "#{scim_prefix}/Users/#{_replaced_user.id}", params: payload.to_json, headers: _scim_headers
+      expect(response).to have_http_status(:ok)
+      expect(_replaced_user.reload.email).to eq("updated@example.com")
+    end
+  end
+
+  # ── PATCH /Users/:id ─────────────────────────────────────────────────────────
+
+  describe "PATCH /Users/:id" do
+    let!(:_patched_user) { _scim_model.create!(email: _scim_email, scim_active: true) }
+
+    it "applies a replace op to active" do
+      payload = scim_patch_payload(scim_replace_op("active", false))
+      patch "#{scim_prefix}/Users/#{_patched_user.id}", params: payload.to_json, headers: _scim_headers
+      expect(response).to have_http_status(:ok)
+      expect(_patched_user.reload.scim_active).to be(false) if _patched_user.respond_to?(:scim_active)
+    end
+
+    it "applies a replace op to userName" do
+      payload = scim_patch_payload(scim_replace_op("userName", "patched@example.com"))
+      patch "#{scim_prefix}/Users/#{_patched_user.id}", params: payload.to_json, headers: _scim_headers
+      expect(response).to have_http_status(:ok)
+      expect(_patched_user.reload.email).to eq("patched@example.com")
+    end
+
+    it "applies a remove op without error" do
+      payload = scim_patch_payload(scim_remove_op("active"))
+      patch "#{scim_prefix}/Users/#{_patched_user.id}", params: payload.to_json, headers: _scim_headers
+      expect(response).to have_http_status(:ok)
+    end
+  end
+
+  # ── DELETE /Users/:id ────────────────────────────────────────────────────────
+
+  describe "DELETE /Users/:id" do
+    let!(:_scim_sourced_user) { _scim_model.create!(email: _scim_email, scim_source: "scim") }
+
+    it "soft-deactivates the user and returns 204" do
+      delete "#{scim_prefix}/Users/#{_scim_sourced_user.id}", headers: _scim_headers
+      expect(response).to have_http_status(:no_content)
+      reloaded = _scim_sourced_user.reload
+      expect(reloaded.scim_active).to be(false) if reloaded.respond_to?(:scim_active)
+      expect(reloaded.scim_deprovisioned_at).not_to be_nil if reloaded.respond_to?(:scim_deprovisioned_at)
+    end
+
+    context "with deprovision_manual_users: false (default)" do
+      let!(:_manual_user) { _scim_model.create!(email: "manual@example.com", scim_source: nil) }
+
+      it "returns 200 and skips deprovisioning the manual user" do
+        delete "#{scim_prefix}/Users/#{_manual_user.id}", headers: _scim_headers
+        expect(response).to have_http_status(:ok)
+        expect(_manual_user.reload.scim_active).to be(true) if _manual_user.respond_to?(:scim_active)
+      end
+    end
+
+    context "with deprovision_manual_users: :error" do
+      before { DeviseScim.configure { |c| c.deprovision_manual_users = :error } }
+
+      let!(:_manual_user) { _scim_model.create!(email: "manual@example.com", scim_source: nil) }
+
+      it "returns 409 for a manually-created user" do
+        delete "#{scim_prefix}/Users/#{_manual_user.id}", headers: _scim_headers
+        expect(response).to have_http_status(:conflict)
+      end
+    end
+  end
+
+  # ── Re-provisioning ──────────────────────────────────────────────────────────
+
+  describe "re-provisioning" do
+    it "POST after DELETE re-enables the deprovisioned user" do
+      user = _scim_model.create!(email: _scim_email, scim_source: "scim")
+      delete "#{scim_prefix}/Users/#{user.id}", headers: _scim_headers
+      expect(response).to have_http_status(:no_content)
+
+      post "#{scim_prefix}/Users",
+           params: scim_user_payload(user_name: _scim_email).to_json,
+           headers: _scim_headers
+      expect(response).to have_http_status(:created)
+      expect(user.reload.scim_active).to be(true)
+    end
+  end
+
+  # ── Authentication ───────────────────────────────────────────────────────────
+
+  describe "authentication" do
+    it "returns 401 with SCIM error body when no auth is provided" do
+      get "#{scim_prefix}/Users"
+      expect(response).to have_http_status(:unauthorized)
+      body = scim_json(response.body)
+      expect(body["schemas"]).to include(DeviseScim::Scim::ERROR_SCHEMA)
+      expect(body["status"]).to eq("401")
+    end
+
+    it "returns 401 for an invalid token" do
+      get "#{scim_prefix}/Users", headers: scim_auth_headers("invalid-token")
+      expect(response).to have_http_status(:unauthorized)
+    end
+  end
+
+  # ── Multi-tenant ─────────────────────────────────────────────────────────────
+
+  context "multi-tenant" do
+    let!(:_mt_tenant) do
+      DeviseScim::ScimTenant.create!(name: "Shared Example Org", auth_method: "token", active: true)
+    end
+    let(:_mt_token)   { _mt_tenant.rotate_token! }
+    let(:_mt_headers) { scim_auth_headers(_mt_token) }
+
+    before do
+      _mt_token
+      DeviseScim.configure { |c| c.tenancy = :multi }
+    end
+
+    it "claims an existing manual user and sets scim_claimed_at on the join record" do
+      manual = _scim_model.create!(email: "manual@example.com")
+      post "#{scim_prefix}/Users",
+           params: scim_user_payload(user_name: "manual@example.com").to_json,
+           headers: _mt_headers
+      expect(response).to have_http_status(:created)
+      join = DeviseScim::ScimTenantUser.find_by(user_id: manual.id)
+      expect(join).not_to be_nil
+      expect(join.scim_claimed_at).not_to be_nil
+    end
+
+    it "returns 404 for a user not assigned to this tenant" do
+      other_user = _scim_model.create!(email: "other@example.com")
+      get "#{scim_prefix}/Users/#{other_user.id}", headers: _mt_headers
+      expect(response).to have_http_status(:not_found)
+    end
+
+    context "with user_exclusivity: :one_to_one" do
+      let!(:_other_tenant) do
+        t = DeviseScim::ScimTenant.create!(name: "Other Org", auth_method: "token", active: true)
+        t.rotate_token!
+        t
+      end
+
+      before { DeviseScim.configure { |c| c.user_exclusivity = :one_to_one } }
+
+      it "returns 409 when user belongs to another tenant (exclusivity_conflict: :error)" do
+        DeviseScim.configure { |c| c.exclusivity_conflict = :error }
+        existing = _scim_model.create!(email: "taken@example.com")
+        DeviseScim::ScimTenantUser.create!(
+          scim_tenant_id: _other_tenant.id, user_id: existing.id,
+          active: true, provisioned_at: Time.current
+        )
+        post "#{scim_prefix}/Users",
+             params: scim_user_payload(user_name: "taken@example.com").to_json,
+             headers: _mt_headers
+        expect(response).to have_http_status(:conflict)
+      end
+
+      it "reassigns the user when exclusivity_conflict: :reassign" do
+        DeviseScim.configure { |c| c.exclusivity_conflict = :reassign }
+        existing = _scim_model.create!(email: "taken@example.com")
+        old_join = DeviseScim::ScimTenantUser.create!(
+          scim_tenant_id: _other_tenant.id, user_id: existing.id,
+          active: true, provisioned_at: Time.current
+        )
+        post "#{scim_prefix}/Users",
+             params: scim_user_payload(user_name: "taken@example.com").to_json,
+             headers: _mt_headers
+        expect(response).to have_http_status(:created)
+        expect(old_join.reload.active).to be(false)
+        new_join = DeviseScim::ScimTenantUser.find_by(user_id: existing.id, scim_tenant_id: _mt_tenant.id)
+        expect(new_join).not_to be_nil
+        expect(new_join.active).to be(true)
+      end
+    end
+  end
+end
+# rubocop:enable Metrics/BlockLength

data/lib/devise_scim/rspec.rb

@@ -0,0 +1,7 @@
+# frozen_string_literal: true
+
+require "devise_scim/rspec/scim_helpers"
+require "devise_scim/rspec/factories"
+require "devise_scim/rspec/shared_examples/users_endpoint"
+require "devise_scim/rspec/shared_examples/groups_endpoint"
+require "devise_scim/rspec/shared_examples/discovery_endpoints"

data/lib/devise_scim/scim/error.rb

@@ -0,0 +1,59 @@
+# frozen_string_literal: true
+
+require "json"
+
+module DeviseScim
+  module Scim
+    ERROR_SCHEMA = "urn:ietf:params:scim:api:messages:2.0:Error"
+
+    class Error
+      attr_reader :status, :detail, :scim_type
+
+      def initialize(status:, detail:, scim_type: nil)
+        @status    = status
+        @detail    = detail
+        @scim_type = scim_type
+      end
+
+      def to_h
+        h = {
+          "schemas" => [ERROR_SCHEMA],
+          "status" => status.to_s,
+          "detail" => detail
+        }
+        h["scimType"] = scim_type if scim_type
+        h
+      end
+
+      def to_json(*)
+        to_h.to_json
+      end
+
+      class << self
+        def unauthorized(detail = "Unauthorized")
+          new(status: 401, detail: detail)
+        end
+
+        def not_found(detail = "Resource not found")
+          new(status: 404, detail: detail)
+        end
+
+        def conflict(detail = "Resource already exists", scim_type: "uniqueness")
+          new(status: 409, detail: detail, scim_type: scim_type)
+        end
+
+        def bad_request(detail, scim_type: "invalidValue")
+          new(status: 400, detail: detail, scim_type: scim_type)
+        end
+
+        def unprocessable(detail)
+          new(status: 422, detail: detail)
+        end
+
+        def server_error(detail = "Internal server error")
+          new(status: 500, detail: detail)
+        end
+      end
+    end
+  end
+end

data/lib/devise_scim/scim/group.rb

@@ -0,0 +1,66 @@
+# frozen_string_literal: true
+
+require "json"
+
+module DeviseScim
+  module Scim
+    GROUP_SCHEMA = "urn:ietf:params:scim:schemas:core:2.0:Group"
+
+    # rubocop:disable Lint/StructNewOverride
+    Member = Struct.new(:value, :display, :ref, keyword_init: true)
+    # rubocop:enable Lint/StructNewOverride
+
+    class Group
+      SCHEMAS = [GROUP_SCHEMA].freeze
+
+      attr_accessor :id, :external_id, :display_name, :members, :meta
+
+      def self.from_h(hash)
+        group = new
+        group.id           = hash["id"]
+        group.external_id  = hash["externalId"]
+        group.display_name = hash["displayName"]
+        group.members = Array(hash["members"]).map do |entry|
+          Member.new(value: entry["value"], display: entry["display"], ref: entry["$ref"])
+        end
+        group
+      end
+
+      def to_h
+        h = {
+          "schemas" => SCHEMAS,
+          "id" => id,
+          "externalId" => external_id,
+          "displayName" => display_name,
+          "members" => (members || []).map { |member| serialize_member(member) }
+        }.compact
+        h["schemas"]  = SCHEMAS
+        h["members"]  = (members || []).map { |member| serialize_member(member) }
+        h["meta"]     = serialize_meta if meta
+        h
+      end
+
+      def to_json(*)
+        to_h.to_json
+      end
+
+      private
+
+      def serialize_member(member)
+        { "value" => member.value, "display" => member.display, "$ref" => member.ref }.compact
+      end
+
+      def serialize_meta
+        {
+          "resourceType" => meta.resource_type || "Group",
+          "created" => iso8601_or_raw(meta.created),
+          "lastModified" => iso8601_or_raw(meta.last_modified)
+        }.compact
+      end
+
+      def iso8601_or_raw(value)
+        value.respond_to?(:iso8601) ? value.iso8601 : value
+      end
+    end
+  end
+end

data/lib/devise_scim/scim/list_response.rb

@@ -0,0 +1,32 @@
+# frozen_string_literal: true
+
+require "json"
+
+module DeviseScim
+  module Scim
+    LIST_RESPONSE_SCHEMA = "urn:ietf:params:scim:api:messages:2.0:ListResponse"
+
+    class ListResponse
+      def initialize(resources:, total_results: nil, start_index: 1, items_per_page: 100)
+        @resources     = resources
+        @total_results = total_results || resources.size
+        @start_index   = start_index
+        @items_per_page = items_per_page
+      end
+
+      def to_h
+        {
+          "schemas" => [LIST_RESPONSE_SCHEMA],
+          "totalResults" => @total_results,
+          "startIndex" => @start_index,
+          "itemsPerPage" => @items_per_page,
+          "Resources" => @resources.map { |r| r.respond_to?(:to_h) ? r.to_h : r }
+        }
+      end
+
+      def to_json(*)
+        to_h.to_json
+      end
+    end
+  end
+end

data/lib/devise_scim/scim/patch_operation.rb

@@ -0,0 +1,55 @@
+# frozen_string_literal: true
+
+module DeviseScim
+  module Scim
+    PATCH_OP_SCHEMA = "urn:ietf:params:scim:api:messages:2.0:PatchOp"
+
+    class PatchOperation
+      VALID_OPS = %w[add remove replace].freeze
+
+      attr_reader :op, :raw_path, :value, :attribute, :filter, :sub_attribute
+
+      def self.parse(hash)
+        operation = hash["op"]&.downcase
+        raise ArgumentError, "Invalid op '#{hash["op"]}'; must be one of: #{VALID_OPS.join(", ")}" unless VALID_OPS.include?(operation)
+
+        new(operation: operation, path: hash["path"], value: hash["value"])
+      end
+
+      def self.parse_request(body)
+        ops = body["Operations"] || body["operations"] || []
+        ops.map { |op_hash| parse(op_hash) }
+      end
+
+      def initialize(operation:, path:, value: nil)
+        @op = operation
+        @raw_path = path
+        @value = value
+        parse_path(path)
+      end
+
+      private
+
+      # Handles three path forms:
+      #   "active"                            → attribute: "active"
+      #   "name.givenName"                    → attribute: "name", sub_attribute: "givenName"
+      #   "emails[type eq \"work\"].value"    → attribute: "emails", filter: "...", sub_attribute: "value"
+      #   "emails[type eq \"work\"]"          → attribute: "emails", filter: "..."
+      def parse_path(path)
+        return unless path
+
+        if (match = path.match(/\A(\w+)\[(.+?)\](?:\.(\w+))?\z/))
+          @attribute     = match[1]
+          @filter        = match[2]
+          @sub_attribute = match[3]
+        elsif path.include?(".")
+          parts          = path.split(".", 2)
+          @attribute     = parts[0]
+          @sub_attribute = parts[1]
+        else
+          @attribute = path
+        end
+      end
+    end
+  end
+end