Adds documentation for REST admin API permissions feature #4257
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
|
|
@@ -36,6 +36,22 @@ plugins.security.restapi.endpoints_disabled.<role>.<endpoint>: ["<method>", ...] | |
| ``` | ||
| {% include copy.html %} | ||
| Roles also allow you to control access to specific REST APIs. You can add individual or multiple cluster permissions to a role and grant users access to associated APIs when they are mapped to the role. The following list of cluster permissions includes the endpoints that correspond to the Security REST APIs: | ||
| | **Permission** | **APIs granted** | **Description** | | ||
| |:-------------------------------|:-----------------------------------|:---------------------------------------------------------------------------------------------------------------------------------------------------| | ||
| | restapi:admin/actiongroups | `/actiongroup` and `/actiongroups` | Permission to get, delete, create, and patch actions groups (including bulk updates). | | ||
| | restapi:admin/allowlist | `/allowlist` | Permission to add any endpoints and HTTP requests to a list of allowed endpoints and requests. | | ||
| | restapi:admin/internalusers | `/internaluser` and `/user` | Permission to add, retrieve, modify, and delete any user in the cluster. | | ||
| | restapi:admin/nodesdn | `/nodesdn` | Permission to add, retrieve, update, or delete any distinguished names from an allow list and enable communication between clusters and/or nodes. | | ||
| | restapi:admin/roles | `/roles` | Permission to add, retrieve, modify, and delete any roles in the cluster. | | ||
| | restapi:admin/rolesmapping | `/rolesmapping` | Permission to add, retrieve, modify, and delete any roles-mapping. | | ||
| | restapi:admin/ssl/certs/info | `/ssl/certs/info` | Permission to view current Transport and HTTP certificates. | | ||
| | restapi:admin/ssl/certs/reload | `/ssl/certs/reload` | Permission to view reload Transport and HTTP certificates. | | ||
| | restapi:admin/tenants | `/tenants` | Permission to get, delete, create, and patch tenants. | | ||
|
|
||
|
|
||
|
|
||
| Possible values for `endpoint` are: | ||
|
|
||
| - ACTIONGROUPS | ||
|
|
@@ -45,6 +61,8 @@ Possible values for `endpoint` are: | |
| - CONFIG | ||
| - CACHE | ||
| - SYSTEMINFO | ||
| - NODESDN | ||
| - SSL | ||
|
|
||
| Possible values for `method` are: | ||
|
|
||
|
|
@@ -146,20 +164,33 @@ Introduced 1.0 | |
|
|
||
| Changes the password for the current user. | ||
|
|
||
| #### Path and HTTP methods | ||
|
|
||
| ```json | ||
| PUT _plugins/_security/api/account | ||
| ``` | ||
| {% include copy-curl.html %} | ||
|
|
||
| #### Request fields | ||
|
|
||
| | Field | Data type | Description | Required | | ||
| |:-------------------|:-----------|:-------------------------------|:----------| | ||
| | current_password | String | The current password. | Yes | | ||
| | password | String | The new password to set. | Yes | | ||
|
|
||
| ##### Example request | ||
|
|
||
| ```json | ||
| PUT _plugins/_security/api/account | ||
| { | ||
| "current_password": "old-password", | ||
| "password": "new-password" | ||
| } | ||
| ``` | ||
| {% include copy-curl.html %} | ||
|
|
||
|
|
||
| ##### Example response | ||
|
|
||
| ```json | ||
| { | ||
|
|
@@ -168,6 +199,13 @@ PUT _plugins/_security/api/account | |
| } | ||
| ``` | ||
|
|
||
| #### Response fields | ||
|
|
||
| | Field | Data type | Description | | ||
| |:---------|:-----------|:------------------------------| | ||
| | status | String | The status of the operation. | | ||
| | message | String | A descriptive message. | | ||
|
|
||
|
|
||
| --- | ||
|
|
||
|
|
@@ -1256,7 +1294,7 @@ PATCH _plugins/_security/api/securityconfig | |
|
|
||
| ## Distinguished names | ||
|
|
||
| These REST APIs let a super admin (or a user with sufficient permissions to access this API) add, retrieve, update, or delete any distinguished names from an allow list to enable communication between clusters and/or nodes. | ||
|
|
||
| Before you can use the REST API to configure the allow list, you must first add the following line to `opensearch.yml`: | ||
|
|
||
|
|
@@ -1336,6 +1374,56 @@ PUT _plugins/_security/api/nodesdn/<cluster-name> | |
| } | ||
| ``` | ||
|
|
||
| ### Update all distinguished names | ||
|
|
||
| Makes a bulk update for the list of distinguished names. | ||
|
|
||
| #### Path and HTTP methods | ||
|
|
||
| ```json | ||
| PATCH _plugins/_security/api/nodesdn | ||
| ``` | ||
| {% include copy-curl.html %} | ||
|
|
||
| #### Request fields | ||
|
|
||
| | Field | Data type | Description | Required | | ||
| |:----------------|:-----------|:------------------------------------------------------------------------------------------------------------------|:---------| | ||
| | op | string | The operation to perform on the action group. Possible values: `remove`,`add`, `replace`, `move`, `copy`, `test`. | Yes | | ||
| | path | string | The path to the resource. | Yes | | ||
| | value | Array | The new values used for the update. | Yes | | ||
|
|
||
|
|
||
| ##### Example request | ||
|
|
||
| ``` | ||
| PATCH _plugins/_security/api/nodesdn | ||
| [ | ||
| { | ||
| "op":"replace", | ||
| "path":"/cluster1/nodes_dn/0", | ||
| "value": ["CN=Karen Berge,CN=admin,DC=corp,DC=Fabrikam,DC=COM", "CN=George Wall,CN=admin,DC=corp,DC=Fabrikam,DC=COM"] | ||
| } | ||
|
There was a problem hiding this comment. Is it possible to add a mock value to the example: "value": "CN=Karen Berge,CN=admin,DC=corp,DC=Fabrikam,DC=COM", "CN=George Wall,CN=admin,DC=corp,DC=Fabrikam,DC=COM", There was a problem hiding this comment. yes, but since this is a remove operation we don't need it. If we want to add a sample value, I will change the example |
||
| ] | ||
| ``` | ||
| {% include copy-curl.html %} | ||
| ##### Example response | ||
| ```json | ||
| { | ||
| "status":"OK", | ||
| "message":"Resources updated." | ||
| } | ||
| ``` | ||
|
|
||
| #### Response fields | ||
|
|
||
| | Field | Data type | Description | | ||
| |:--------|:----------|:---------------------| | ||
| | status | string | The response status. | | ||
| | message | string | Response message. | | ||
|
|
||
|
|
||
| ### Delete distinguished names | ||
|
|
||
|
|
@@ -1399,33 +1487,77 @@ GET _plugins/_security/api/ssl/certs | |
| ] | ||
| } | ||
| ``` | ||
|
|
||
| ### Reload transport certificates | ||
|
|
||
| Reload transport layer communication certificates. These REST APIs let a super admin (or a user with sufficient permissions to access this API) reload transport layer certificates. | ||
|
|
||
| #### Path and HTTP methods | ||
|
|
||
| ```json | ||
| PUT /_plugins/_security/api/ssl/transport/reloadcerts | ||
| ``` | ||
| {% include copy-curl.html %} | ||
|
|
||
| ##### Example request | ||
|
|
||
| ```bash | ||
| curl -X PUT "https://your-opensearch-cluster/_plugins/_security/api/ssl/transport/reloadcerts" | ||
| ``` | ||
| {% include copy-curl.html %} | ||
|
|
||
| ##### Example response | ||
|
|
||
| ```json | ||
| { | ||
| "status": "OK", | ||
| "message": "updated transport certs" | ||
| } | ||
| ``` | ||
|
|
||
| #### Response fields | ||
|
|
||
| | Field | Data type | Description | | ||
| |:--------|:----------|:----------------------------------------------------------------------------------| | ||
| | status | String | Indicates the status of the operation. Possible values: "OK" or an error message. | | ||
| | message | String | Additional information about the operation. | | ||
|
|
||
|
|
||
| #### Reload HTTP certificates | ||
|
|
||
| Reload HTTP layer communication certificates. These REST APIs let a super admin (or a user with sufficient permissions to access this API) reload HTTP layer certificates. | ||
|
|
||
| #### Path and HTTP methods | ||
|
|
||
| ```json | ||
| PUT /_plugins/_security/api/ssl/http/reloadcerts | ||
| ``` | ||
| {% include copy-curl.html %} | ||
|
|
||
|
|
||
| ##### Example request | ||
|
|
||
| ``` | ||
| curl -X PUT "https://your-opensearch-cluster/_plugins/_security/api/ssl/http/reloadcerts" | ||
| ``` | ||
| {% include copy-curl.html %} | ||
|
|
||
| ##### Example response | ||
|
|
||
| ```json | ||
| { | ||
| "status": "OK", | ||
| "message": "updated http certs" | ||
| } | ||
| ``` | ||
|
|
||
| #### Response fields | ||
|
There was a problem hiding this comment. I think it's fine to leave this table. But the example response is probably self explanatory for this. It can stay or go. There was a problem hiding this comment. I followed the API Style Guide. Let's keep it? |
||
|
|
||
| | Field | Data type | Description | | ||
| |:--------|:----------|:--------------------------------------------------------------------| | ||
| | status | String | The status of the API operation. Possible value: "OK". | | ||
| | message | String | A message indicating that the HTTP certificates have been updated. | | ||
|
|
||
| --- | ||
|
|
||
| ## Cache | ||
|
|
@@ -1502,7 +1634,7 @@ You can do an initial configuration of audit logging in the `audit.yml` file, fo | |
|
|
||
| #### Request fields | ||
|
|
||
| Field | Data type | Description | ||
| :--- | :--- | :--- | ||
| `enabled` | Boolean | Enables or disables audit logging. Default is `true`. | ||
| `audit` | Object | Contains fields for audit logging configuration. | ||
|
|
||
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
|
|
@@ -393,3 +393,20 @@ These permissions apply to an index or index pattern. You might want a user to h | |
| - indices:monitor/shard_stores | ||
| - indices:monitor/stats | ||
| - indices:monitor/upgrade | ||
|
|
||
|
|
||
| ## Security REST permissions | ||
|
|
||
| These permissions apply to REST APIs to control access to the endpoints. Granting access to any of these will allow a user the permission to change fundamental operational components of the Security plugin. | ||
| Allowing access to these endpoints has the potential to trigger operational changes in the cluster. Proceed with caution. | ||
| {: .warning } | ||
|
|
||
|
There was a problem hiding this comment. If these are cluster permissions, let's format them like the others in the Permissions documentation and add them in the section above index permissions, Cluster permissions. So, the whole enchilada: Security REST API permissionsAllowing access to these endpoints has the potential to trigger operational changes in the cluster. Proceed with caution. See API for more information about Security REST APIs.
There was a problem hiding this comment. these permissions are not prefixed with |
||
| - restapi:admin/actiongroups | ||
| - restapi:admin/allowlist | ||
| - restapi:admin/internalusers | ||
| - restapi:admin/nodesdn | ||
| - restapi:admin/roles | ||
| - restapi:admin/rolesmapping | ||
| - restapi:admin/ssl/certs/info | ||
| - restapi:admin/ssl/certs/reload | ||
| - restapi:admin/tenants | ||
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
How does this differ from "Update distinguished names" using a PUT call? Just a brief blurb describing the API.