Role Management - Deprecated Elasticsearch Index Privileges

[kobelb]

With the forth-coming addition of the create_doc index privilege and the ability to restrict users to only be able to create documents, the @elastic/es-security is intending to deprecate certain index-privileges. We'd like these deprecations to be reflected in the role management screen, so users are aware of which index-privileges are truly deprecated.

The index-privileges are currently displayed in an EuiComboBox. @elastic/eui-design do you have a preference for how we denote a deprecated index-pattern item within the combo-box itself?

Blocked by elastic/elasticsearch#47333

[elasticmachine]

Pinging @elastic/kibana-security

[legrego]

For inspiration (or maybe examples of what not to do!), I have a draft PR that illustrates what deprecated roles might look like in the UI. The screenshots don't translate to this scenario 1:1, but it should give you a good idea of what I was going for:

#45045

[kobelb]

@bizybot I heard through the grape-vine that you'd be working on deprecating the index-pattern privileges in Elasticsearch. Would you mind letting us know when you have an idea of how it'll be expressed via the API?

[bizybot]

@bizybot I heard through the grape-vine that you'd be working on deprecating the index-pattern privileges in Elasticsearch. Would you mind letting us know when you have an idea of how it'll be expressed via the API?

Hi @kobelb :) yes we are working on deprecating the index pattern privileges in Elasticsearch.
I have a discuss issue open for the same but there are some things that need to be sorted before I deprecate the usage. elastic/elasticsearch#47333
I am thinking of using the built-in privileges API or we could use a separate API to convey this information something like:

{
  "cluster": [
    "..."
  ],
  "index": [
    "all",
    "create",
    "create_doc"
    "...",
    "write"
  ],
  "deprecations": {
    "cluster": [],
    "index": [
      {
        "name": "create",
        "alternative/suggestion": "create_doc",
        "is_exact_replacement": false
      },
      {
        "name": "index",
        "alternative/suggestion": "index_doc",
        "is_exact_replacement": true
      }
    ]
  }
}

I guess this would help UI to show the alternatives and whether the alternatives are exact replacement.

[tvernum]

I spoke to @kobelb earlier today and he suggested that the likely behaviour for the UI is to have a visual indicator for deprecated privileges (e.g. color) with a descriptive tooltip.
Given that, it might be simpler to just have the privilege/_builtinAPI return a list of deprecated names with a description of why (which could refer to the replacement name) rather than a complex alternative/suggestion.

[bizybot]

@tvernum I preferred the representation instead of the description as that would be easier for migration programs (if automated outside ES). If we go by description then the migration program needs to parse the string to know alternatives and work with it, are we okay with that? Thank you.

[legrego]

Given that, it might be simpler to just have the privilege/_builtinAPI return a list of deprecated names with a description of why (which could refer to the replacement name) rather than a complex alternative/suggestion.

I preferred the representation instead of the description as that would be easier for migration programs (if automated outside ES). If we go by description then the migration program needs to parse the string to know alternatives and work with it, are we okay with that? Thank you.

I'd prefer the alternative/suggestion approach as well for internationalization efforts. As far as I know, ES can only return messages in English, but the Kibana UI has to be translatable to a number of different languages. If we display a full description from ES to the end-user, it will always be in English, regardless of their chosen language.

If, on the other hand, ES returns an alternative role name, we can craft the message within Kibana, which will be translated correctly. The only piece that won't be translated is the alternative role name itself, which is fine as far as our i18n efforts are concerned.

[bizybot]

Thank you @legrego for the comment.
@kobelb do you have any other comments/suggestions around the response to communicate the deprecated privilege names? If not I can pick this as a valid approach and continue working on it. Thank you.

[kobelb]

@bizybot, I defer my opinion to @legrego as he'll be most likely the one implementing this.

[legrego]

@bizybot Just a couple of small thoughts:

"deprecations": {
  "cluster": [],
  "index": [
    {
      "name": "create",
      "alternative/suggestion": "create_doc",
      "is_exact_replacement": false
    },
    {
      "name": "index",
      "alternative/suggestion": "index_doc",
      "is_exact_replacement": true
    }
  ]
}

1. You might have already planned on doing this, but can we choose to use either alternative or suggestion, rather than the composite alternative/suggestion property? This will make parsing easier on our side, and is more consistent with the rest of the keys.
2. I like that is_exact_replacement tells us if the suggestion is a simple rename as opposed to something that requires more thought from the end-user. When this returns false though, I don't have any actionable information to give to end-users. What do you think about having a dedicated "ES Role Privilege Deprecations" documentation page, which explains each deprecation in more detail, and any steps users need to take? I'd like to provide a link within Kibana to these docs to give users more context, and I think this is something that would help out the support folks as well.

[bizybot]

Thank you @legrego for your comment.

1. You might have already planned on doing this, but can we choose to use either alternative or suggestion, rather than the composite alternative/suggestion property? This will make parsing easier on our side, and is more consistent with the rest of the keys.

I was suggesting either one of those, sorry I did not explain it in my response. I think the final outcome might be different when put through review.

2. I like that is_exact_replacement tells us if the suggestion is a simple rename as opposed to something that requires more thought from the end-user. When this returns false though, I don't have any actionable information to give to end-users. What do you think about having a dedicated "ES Role Privilege Deprecations" documentation page, which explains each deprecation in more detail, and any steps users need to take? I'd like to provide a link within Kibana to these docs to give users more context, and I think this is something that would help out the support folks as well.

When is_exact_replacement is false, then there are suggestions that can be used as exact replacement or similar privileges in the response. This was the reason I was not sure what field name to use suggestion/alternative or something else.
The error message could be formed using the information presented using is_exact_replacement and alternative/suggestion.
For example, "create" index privilege has been deprecated, suggested alternatives for it are "create_doc". Please check the documentation for more details.
in case we have an exact replacement we could say "index" index privilege has been deprecated, the exact replacement for it is "index_doc". Please check the documentation for more details.

So far in Elasticsearch, we have avoided documentation links in the error messages, it becomes difficult to maintain the link and I agree. I think mentioning that you need to refer to the docs should be okay here as we are also giving them some alternative or suggestions and then redirecting them to the documentation for more details. WDYT?

[legrego]

When is_exact_replacement is false, then there are suggestions that can be used as exact replacement or similar privileges in the response.

If is_exact_replacement is false, then I wouldn't expect to find a suggestion that can be used as an exact replacement. I would instead expect to find a suggestion that comes close ("...or similar privileges"), but might not capture all of the user's requirements. Am I misunderstanding?

I think my original question about not providing any actionable information was poorly worded too -- I understand we'll likely have an alternative, but we won't be able to explain the nuanced differences between the deprecated privilege and the replacement privilege, which is why I was asking for a link to docs. I don't need the link as part of the deprecation response you send -- we can maintain that link ourselves within Kibana.

So far in Elasticsearch, we have avoided documentation links in the error messages, it becomes difficult to maintain the link and I agree. I think mentioning that you need to refer to the docs should be okay here as we are also giving them some alternative or suggestions and then redirecting them to the documentation for more details. WDYT?

I agree they can be hard to maintain -- that being said, Kibana has many links to our documentation site to help explain concepts in more detail, so I expect we'd do something similar here in the UI. ES doesn't have to worry about constructing this message though. We'll just need the link to the doc page once it's written so that we can reference it.

[bizybot]

but might not capture all of the user's requirements. Am I misunderstanding?

No your understanding is perfectly clear. Yes the suggestions might not capture the users requirement. Now whether that is entirely achievable or not it depends. It might simply be assigning action level privileges explicitly to achieve what the user wants.

I think my original question about not providing any actionable information was poorly worded too -- I understand we'll likely have an alternative, but we won't be able to explain the nuanced differences between the deprecated privilege and the replacement privilege, which is why I was asking for a link to docs.

No worries, yes we would not be able to provide the differences between the replacement alternatives if it is not an exact replacement.

I don't need the link as part of the deprecation response you send -- we can maintain that link ourselves within Kibana.

This is good if ES does not send the link as part of response.
Mostly the deprecations information would be present on the same page where we describe all the built-in privileges in current documentation, so that link can be used.

We'll just need the link to the doc page once it's written so that we can reference it.

I will share the documentation link once the changes are done.

Thank you @legrego for your inputs.

[legrego]

Closing this as "not planned" for now.

The ES-Security team is not planning on moving forward with these deprecations, so there is no need for us to track or implement this work. We can re-open this issue if our circumstances change.