feat(security): extend Feature definition to support explicit feature replacements

[azasypkin]

Summary

Today, when a developer deprecates a feature and replaces its privileges with those of another feature, we reasonably assume that the new feature fully replaces the old one in all possible contexts - whether in role management UIs or in the Spaces feature toggles visibility UI. However, when deprecated privileges are replaced by the privileges of multiple features, such as in this case where the Discover/Dashboard/Maps feature privileges are replaced by the privileges of Discover_v2/Dashboard_v2/Maps_v2, respectively, and the privileges of the Saved Query Management feature, the choice is ambiguous.

Which of these features should be treated as the replacement for the deprecated feature in contexts that deal with entire features (like the Spaces feature toggles visibility UI) rather than individual privileges (like in role management UIs)? Should all referenced features be considered replacements? Or just a subset - or even a single feature? If so, which one? Currently, we treat all referenced features as replacements for the deprecated feature, which creates problems, as described in detail in this discussion.

This PR allows developers to customize this behavior by specifying which features Kibana should treat as direct successors to deprecated features in contexts that deal with whole features rather than individual privileges:

deps.features.registerKibanaFeature({
  deprecated: {
    notice: 'The feature is deprecated because … well, there’s a reason.',
    --> replacedBy: ['feature_id_v2'], <--
  },
  id: 'feature_id'
  name: `Case #4 feature ${suffix} (DEPRECATED)`,
  …
});

How to test

1. Run test server

node scripts/functional_tests_server.js --config x-pack/test/security_api_integration/features.config.ts

2. Execute the following request from the Dev Tools (case_4_feature_a is a deprecated feature that is replaced by multiple features and doesn't use deprecated.replacedBy)

PUT kbn:/api/spaces/space/default?overwrite=true
{
  "id":"default",
  "name":"Default",
  "description":"This is your default space!",
  "color":"#00bfb3",
  "disabledFeatures":["case_4_feature_a"],
  "_reserved":true,
  "imageUrl":"",
  "initials":"D"
}

3. Observe that in response deprecated case_4_feature_a is replaced by two features (you can also check http://localhost:5620/app/management/kibana/spaces/edit/default to see how it's reflected in UI)

{
  "id": "default",
  "name": "Default",
  "description": "This is your default space!",
  "color": "#00bfb3",
  "initials": "D",
  "imageUrl": "",
  "disabledFeatures": [
    "case_4_feature_a_v2",
    "case_4_feature_c"
  ],
  "_reserved": true
}

4. Execute the following request from the Dev Tools (case_4_feature_b is a deprecated feature that is replaced by multiple features, but uses deprecated.replacedBy to set the conceptual feature-successor)

PUT kbn:/api/spaces/space/default?overwrite=true
{
  "id":"default",
  "name":"Default",
  "description":"This is your default space!",
  "color":"#00bfb3",
  "disabledFeatures":["case_4_feature_b"],
  "_reserved":true,
  "imageUrl":"",
  "initials":"D"
}

5. Observe that in response deprecated case_4_feature_b is replaced by a single feature (you can also check http://localhost:5620/app/management/kibana/spaces/edit/default to see how it's reflected in UI)

{
  "id": "default",
  "name": "Default",
  "description": "This is your default space!",
  "color": "#00bfb3",
  "initials": "D",
  "imageUrl": "",
  "disabledFeatures": [
    "case_4_feature_b_v2"
  ],
  "_reserved": true
}

Required by: #202863 (comment)

//cc @davismcphee

[azasypkin]

note: I couldn't come up with a better name to describe what it's for, but open to suggestions...

[elasticmachine]

💚 Build Succeeded

• Buildkite Build
• Commit: 1beef16

Metrics [docs]

Public APIs missing comments

Total count of every public API that lacks a comment. Target amount is 0. Run node scripts/build_api_docs --plugin [yourplugin] --stats comments for more detailed information.

id	before	after	diff
features	110	109	-1

Unknown metric groups

API count

id	before	after	diff
features	270	273	+3

References to deprecated APIs

id	before	after	diff
spaces	14	12	-2

[azasypkin]

note: Due to the way the start contract of the Feature plugin was defined, it was technically possible to pass any arguments to the getKibanaFeatures method, even though this was not reflected in the type definition:

getKibanaFeatures: this.featureRegistry.getAllKibanaFeatures.bind(this.featureRegistry),

This change explicitly defines the list of accepted arguments, ensuring that only omitDeprecated is exposed publicly:

getKibanaFeatures: (params) => this.featureRegistry.getAllKibanaFeatures(
  params && { omitDeprecated: params.omitDeprecated }
),

[azasypkin]

note: getKibanaFeatures in setup contract is deprecated.

[afharo]

Core changes LGTM. Code review only.

[davismcphee]

I merged this into my PR branch to test and confirmed it's working as expected. I can now deprecate the necessary features and choose which ones replace them separately from the deprecated privileges. Thanks for addressing this so quickly!

Without replacedBy: ['dashboard_v2']:

With replacedBy: ['dashboard_v2']:

[SiddharthMantri]

LGTM! tested and synced with @azasypkin about the changes.

[azasypkin]

@elasticmachine merge upstream

[kibanamachine]

Starting backport for target branches: 8.x

https://github.com/elastic/kibana/actions/runs/12808033095

[kibanamachine]

💚 All backports created successfully

Status	Branch	Result
✅	8.x

Note: Successful backport PRs will be merged automatically after passing CI.

Questions ?

Please refer to the Backport tool documentation