Kibana Privilege Deprecation

Kibana Privilege Deprecation

Guides implementing and reviewing backward-compatible Kibana feature privilege deprecations using the deprecated privilege mapping framework.

When to Use

• Renaming a feature (e.g. alpha -> beta)
• Splitting a feature into multiple features
• Consolidating multiple features into one
• Moving capabilities between feature/sub-feature privileges
• Reviewing PRs that deprecate features or change privilege mappings

Key Concepts

• Deprecated feature: A feature marked with deprecated property that is frozen for backward compatibility. Not shown in role management UI; privileges still registered in Elasticsearch.
• `replacedBy` mapping: Links each deprecated privilege to equivalent non-deprecated privilege(s). Required on every privilege of a deprecated feature.
• Lazy migration: Roles are not auto-migrated. Deprecated privileges are replaced with current ones when an admin saves via UI.
• `kibana_system` cannot alter roles - this is a security constraint driving the entire design.

Implementation Steps

Step 1: Create new replacement feature(s)

Register new feature(s) with desired privileges using deps.features.registerKibanaFeature().

Step 2: Mark existing feature as deprecated

Add deprecated property with a user-facing notice string. Feature ID must stay unchanged.

deps.features.registerKibanaFeature({
  deprecated: {
    notice: i18n.translate('xpack.yourPlugin.featureDeprecationNotice', {
      defaultMessage: 'Feature X is deprecated. Use Feature Y instead. See {link}.',
      values: { link: 'https://...' },
    }),
    // Optional: override which features conceptually replace this one (for Spaces UI).
    // By default derived from privilege-level replacedBy. Only needed when replacedBy
    // references multiple features but you want the Spaces UI to show a subset.
    replacedBy: ['feature_y'],
  },
  id: 'feature_x',  // Must stay the same
  name: 'Feature X (DEPRECATED)',
  privileges: { /* keep original privileges unchanged, add replacedBy */ },
});

Step 3: Define replacedBy on every privilege

Every all, read, and sub-feature privilege must have replacedBy.

Simple form -- use when the deprecated feature has NO sub-features:

privileges: {
  all: {
    ...originalAllPrivilege,
    replacedBy: [
      { feature: 'feature_y', privileges: ['all'] },
    ],
  },
  read: {
    ...originalReadPrivilege,
    replacedBy: [
      { feature: 'feature_y', privileges: ['read'] },
    ],
  },
}

Extended `{ default, minimal }` form -- use when the deprecated feature HAS sub-features:

When a deprecated feature has sub-features, the top-level all privilege implicitly includes all sub-feature privileges granted via includeIn: 'all', while minimal_all does not. These two paths must map differently to preserve the distinction. The same applies to read / minimal_read.

privileges: {
  all: {
    ...originalAllPrivilege,
    replacedBy: {
      // `default` maps `all` (= minimal_all + auto-granted sub-feature privileges)
      default: [
        { feature: 'feature_y', privileges: ['all', 'sub_feature_priv_id'] },
      ],
      // `minimal` maps `minimal_all` (= top-level only, no sub-features)
      minimal: [
        { feature: 'feature_y', privileges: ['minimal_all'] },
      ],
    },
  },
  read: {
    ...originalReadPrivilege,
    replacedBy: {
      default: [
        { feature: 'feature_y', privileges: ['read', 'sub_feature_priv_id'] },
      ],
      minimal: [
        { feature: 'feature_y', privileges: ['minimal_read'] },
      ],
    },
  },
}
// Each sub-feature privilege also needs its own replacedBy (simple array form):
// replacedBy: [{ feature: 'feature_y', privileges: ['sub_feature_priv_id'] }]

Rule of thumb: If the deprecated feature defines subFeatures, always use the { default, minimal } form on its top-level privileges. The simple array form is only correct when there are no sub-features (it applies the same mapping to both default and minimal).

Step 4: Update code to use new features

• API privileges: Replacement privileges must provide all API privileges from deprecated privileges. Routes use security.authz.requiredPrivileges for authorization. Ensure deprecated feature's api array is updated so that both deprecated and replacement privilege holders can access the same endpoints.
• UI capabilities: Update client code to check capabilities.new_feature.capability instead of capabilities.old_feature.capability. The framework auto-maps deprecated capabilities to replacement ones.
• Alerting consumers: New features must register deprecated feature ID as additional consumer so rules created under old feature remain accessible.
• Cases owners: Follow same pattern as alerting for case ownership continuity.

Validation Rules (Enforced at Startup)

Kibana will refuse to start if any of these are violated:

1. Deprecated features must define replacedBy on every privilege 2. Non-deprecated features must not define replacedBy 3. Referenced replacement features must exist and not be deprecated 4. Referenced replacement privileges must exist 5. Enabled privileges cannot be replaced with disabled ones 6. feature.deprecated.replacedBy feature IDs (if set) must be a subset of features used in privilege-level replacedBy

PR Review Checklist

When reviewing deprecation PRs, focus on what startup validation does NOT catch:

• [ ] Deprecated feature ID is unchanged from original
• [ ] deprecated.notice is localized (i18n.translate) with a link to docs or PR
• [ ] If deprecated feature has sub-features: top-level replacedBy uses { default, minimal } form, not simple array
• [ ] Replacement privileges cover all SO types, api entries, ui capabilities, app, catalogue, and management from the deprecated ones
• [ ] If replacement grants MORE access than deprecated, it is intentional and justified
• [ ] New features register deprecated feature ID as additional alerting consumer and cases owner
• [ ] Routes use security.authz.requiredPrivileges; deprecated feature's api array matches replacement's
• [ ] Client code uses new feature ID for capability checks (e.g. capabilities.new_feature.ui_all)
• [ ] Integration tests updated; Spaces feature visibility verified
• [ ] No privilege escalation or reduction; ZDT and rollback safe

Examples

For concrete code covering all deprecation scenarios (rename, split, sub-feature extraction, consolidation, alerting/cases), read the test plugin:

x-pack/platform/test/security_api_integration/plugins/features_provider/server/index.ts

For real-world deprecations (discover, dashboard, visualize, maps):

x-pack/platform/plugins/shared/features/server/oss_features.ts

Test Files

Additional Resources

• For detailed type definitions and validation rules, see references/reference.md
• PoC PR: #kibana/186800
• API authorization guide: dev_docs/key_concepts/api_authorization.mdx

Privilege Deprecation Reference

Type Definitions

KibanaFeatureConfig.deprecated

Located in x-pack/platform/plugins/shared/features/common/kibana_feature.ts:

readonly deprecated?: Readonly<{
  // Mandatory, localizable, user-facing notice explaining why the feature is deprecated
  // and what should be used instead. Can include links to documentation.
  notice: string;

  // Optional list of feature IDs that conceptually replace this deprecated feature.
  // Used in Spaces feature visibility UI. By default derived from privilege-level replacedBy.
  // Override when privilege replacedBy references multiple features but only a subset
  // should appear in Spaces UI.
  replacedBy?: readonly string[];
}>;

FeatureKibanaPrivileges.replacedBy

Located in x-pack/platform/plugins/shared/features/common/feature_kibana_privileges.ts:

// For top-level privileges (all, read) - supports separate default/minimal mappings
replacedBy?:
  | readonly FeatureKibanaPrivilegesReference[]
  | {
      default: readonly FeatureKibanaPrivilegesReference[];
      minimal: readonly FeatureKibanaPrivilegesReference[];
    };

Two forms explained:

• Simple array form: Applies the same replacement mapping to both all/minimal_all (or read/minimal_read). Only correct when the deprecated feature has no sub-features.
• Extended `{ default, minimal }` form: Required when the deprecated feature has sub-features. This is because:
• all = minimal_all + all sub-feature privileges with includeIn: 'all'
• minimal_all = only the top-level privilege, no sub-feature privileges
• These two must map to different sets of replacement privileges to preserve the distinction.

If a deprecated feature has sub-features and you use the simple array form, the minimal_all mapping will incorrectly include sub-feature replacements, granting more access than intended.

SubFeaturePrivilegeConfig.replacedBy

Located in x-pack/platform/plugins/shared/features/common/sub_feature.ts:

// For sub-feature privileges - only simple array form
replacedBy?: readonly FeatureKibanaPrivilegesReference[];

FeatureKibanaPrivilegesReference

Located in x-pack/platform/plugins/shared/features/common/feature_kibana_privileges_reference.ts:

export interface FeatureKibanaPrivilegesReference {
  // The ID of the target (non-deprecated) feature
  feature: string;
  // IDs of feature or sub-feature privileges from that feature
  privileges: readonly string[];
}

Validation Rules

Enforced in feature_registry.ts -> validateFeatures() after all features are registered:

How Deprecated Privileges Work at Runtime

Elasticsearch Registration

• Deprecated features' privileges are still registered as Elasticsearch application privileges
• Users with roles referencing deprecated privileges continue to pass authorization checks
• No automatic role migration occurs

Role Deserialization (UI)

In elasticsearch_role.ts -> deserializeKibanaFeaturePrivileges(): 1. When replaceDeprecatedKibanaPrivileges: true (used by role management UI):

• Deprecated privileges are resolved to their replacedBy targets
• Only replacement privileges appear in the deserialized role

2. When false (default for APIs):

• Deprecated privileges remain as-is in the role

UI Capabilities

In privileges.ts -> privilege computation:

• Deprecated privileges generate UI actions from both the deprecated feature and its replacement features
• Client code should check replacement feature capabilities (e.g. capabilities.feature_beta.ui_all)
• Works for users with either deprecated or replacement privileges

Spaces Feature Visibility

In spaces_client.ts:

• Deprecated features are excluded from enabled/disabled feature lists
• Replacement features are shown instead
• feature.deprecated.replacedBy (feature-level) controls which features appear

API Authorization

• Routes using security.authz.requiredPrivileges continue to work with deprecated privileges
• API privileges from deprecated features remain valid in Elasticsearch
• When changing privilege names: update deprecated feature's api array to match replacement feature's entries
• Routes must use security.authz.requiredPrivileges to authorize access, covering both deprecated and replacement privilege holders

Role Management APIs

• Deprecated privileges are still accepted in create/update role API requests
• This maintains backward compatibility for automation built around role APIs
• Deprecation warnings may be surfaced in future API responses