[Question] Requirements for plugin onboarding

[jmazanec15]

When a plugin included in distribution onboards a new API, are there any requirements/expectations it has to fulfill with respect to security.

For instance, is it a requirement to follow https://github.com/opensearch-project/security#onboarding-new-apis and set up roles for the plugin?

If there are no requirements/expectations, should there be?

[peternied]

When a user attempts to make an API call with security enable the task name, such as cluster:admin/plugins/replication/autofollow/update are checked for permissions. If the user does not have this permissions grant to them the request will be blocked.

If a new API is added it will automatically be blocked by the security plugins default configuration. Many plugins should document how to add security [1], but this doesn't help for the out of the box scenarios. Inside this repository there are the 'defaults' for action groups, roles, role mappings. By making a modification in these files [2] the permission could be available by default depending on these assignments.

There are no 'hard requirements' as the Security plugin can work with plugins that are not included in the distribution. However following common practice for the OpenSearch-Project should be in alignment to some degree, engage with @shanilpa @jimishs can help dig into the scenario and provide recommendations.

If you had an example of your API and how you'd like it to work we could dig in deeper.

---

@cwillum this would be good area to beef up our documentation for 'If you are plugin how do you work with the Security Plugin's access control system', maybe you could help clarify in our readme documentation

[1] https://opensearch.org/docs/latest/replication-plugin/permissions/
[2] https://github.com/opensearch-project/security/tree/main/src/main/resources/static_config

[jmazanec15]

If you had an example of your API and how you'd like it to work we could dig in deeper.

Question is more general - I am not asking about specific APIs.

There are no 'hard requirements' as the Security plugin can work with plugins that are not included in the distribution. However following common practice for the OpenSearch-Project should be in alignment to some degree,

Right, I am asking more about alignment amongst plugins in the distribution. I see a lot of plugins have already added roles here: https://github.com/opensearch-project/security/blob/main/config/roles.yml - I am wondering if this should be a standardization - maybe more of a question for @jimishs and @shanilpa. Maybe put another way, when should a plugin add a role to security plugin for their APIs?

[cwperks]

Hey @jmazanec15, this is a good question. I am now seeing instances where roles reference actions that are not contained in security-dashboards-plugin here, which means that a user is not able to create a custom role that permits the individual action.

See example role in the latest 2.4.0 RC which has a list of actions that have not yet been added to security-dashboards-plugin's list:

security_analytics_read_access:
  reserved: true
  cluster_permissions:
    - 'cluster:admin/opensearch/securityanalytics/alerts/get'
    - 'cluster:admin/opensearch/securityanalytics/detector/get'
    - 'cluster:admin/opensearch/securityanalytics/detector/search'
    - 'cluster:admin/opensearch/securityanalytics/findings/get'
    - 'cluster:admin/opensearch/securityanalytics/mapping/get'
    - 'cluster:admin/opensearch/securityanalytics/mapping/view/get'
    - 'cluster:admin/opensearch/securityanalytics/rule/get'
    - 'cluster:admin/opensearch/securityanalytics/rule/search'

I can see the role in OSD and map users, but I cannot create a custom role and assign the actions individually:

Not in the dropdown:

I'm not sure if this is desired behavior, but it is confusing that we display the action when looking at the reserved role but the same action is not assignable when creating a custom role.

[peternied]

[Triage] @cwillum what do you think the documentation for these requirements would look like, is the readme enough or should we have space in the documentation website - if so could you make a follow up issue.

FYI @shanilpa

[cwperks]

Adding to this discussion, its not clear to me reading the documentation website what the best route to take to add new reserved roles into the security index is. When upgrading between minor versions, there may be new reserved roles added to go with new plugins introduced. See https://github.com/opensearch-project/security/blob/main/config/roles.yml for list of reserved roles. The roles associated with security_analytics are a recent example in the 2.4.0 release.

When performing an update on a cluster that already has the security index initialized, these new reserved roles added are not sourced into the security index on an upgrade. It looks like the best route to take is to take a backup of the security index using securityadmin (https://opensearch.org/docs/latest/security-plugin/configuration/security-admin/), add the new reserved roles into the exported roles.yml and finally use security admin to update the security index. Is there a better way?

[cwillum]

@peternied @cwperks @jmazanec15 Just getting a chance to look at this. I'll need to spend some more time going through the information here. But after scratching the surface, my feeling is that we should have these steps on the documentation website. I haven't wrapped my head around it thoroughly. But I can imagine having a generic example of what you need to do to register a new API with the new plugin, OS, and OSD - and be able to link to it from any plugin doc.

I just finished a first iteration of Security Analytics. That has 17 APIs so far. With that plugin still fresh in memory, it seems right to have information about this issue in those docs. But I'll look at this a little more closely and revisit. Thanks.

[RyanL1997]

@jimishs Could you please follow up this?

[stephen-crawford]

@jimishs, have you had a moment to follow-up on this? Thank you.

[cwperks]

Closing this issue. The security plugin's README has information on how a plugin can onboard to the security plugin to grant access to user's to use their plugin in a cluster with the security plugin installed. https://github.com/opensearch-project/security?tab=readme-ov-file#onboarding-new-apis