Security REST API

This commit is contained in:
aetter 2021-06-10 11:15:44 -07:00
parent 669e0043ec
commit d74507e3c4
8 changed files with 62 additions and 62 deletions

View File

@ -33,7 +33,7 @@ For example, consider two users: `judy` and `elon`.
`judy` has an IT backend role: `judy` has an IT backend role:
```json ```json
PUT _opensearch/_security/api/internalusers/judy PUT _plugins/_security/api/internalusers/judy
{ {
"password": "judy", "password": "judy",
"backend_roles": [ "backend_roles": [
@ -46,7 +46,7 @@ PUT _opensearch/_security/api/internalusers/judy
`elon` has an admin backend role: `elon` has an admin backend role:
```json ```json
PUT _opensearch/_security/api/internalusers/elon PUT _plugins/_security/api/internalusers/elon
{ {
"password": "elon", "password": "elon",
"backend_roles": [ "backend_roles": [
@ -59,7 +59,7 @@ PUT _opensearch/_security/api/internalusers/elon
Both `judy` and `elon` have full access to asynchronous search: Both `judy` and `elon` have full access to asynchronous search:
```json ```json
PUT _opensearch/_security/api/rolesmapping/async_full_access PUT _plugins/_security/api/rolesmapping/async_full_access
{ {
"backend_roles": [], "backend_roles": [],
"hosts": [], "hosts": [],

View File

@ -52,7 +52,7 @@ Possible values for `method` are:
- DELETE - DELETE
- PATCH - PATCH
For example, the following configuration grants three roles access to the REST API, but then prevents `test-role` from making PUT, POST, DELETE, or PATCH requests to `_opensearch/_security/api/roles` or `_opensearch/_security/api/internalusers`: For example, the following configuration grants three roles access to the REST API, but then prevents `test-role` from making PUT, POST, DELETE, or PATCH requests to `_plugins/_security/api/roles` or `_plugins/_security/api/internalusers`:
```yml ```yml
plugins.security.restapi.roles_enabled: ["all_access", "security_rest_api_access", "test-role"] plugins.security.restapi.roles_enabled: ["all_access", "security_rest_api_access", "test-role"]
@ -102,7 +102,7 @@ Returns account details for the current user. For example, if you sign the reque
#### Request #### Request
``` ```
GET _opensearch/_security/api/account GET _plugins/_security/api/account
``` ```
#### Sample response #### Sample response
@ -139,7 +139,7 @@ Changes the password for the current user.
#### Request #### Request
```json ```json
PUT _opensearch/_security/api/account PUT _plugins/_security/api/account
{ {
"current_password" : "old-password", "current_password" : "old-password",
"password" : "new-password" "password" : "new-password"
@ -169,7 +169,7 @@ Retrieves one action group.
#### Request #### Request
``` ```
GET _opensearch/_security/api/actiongroups/<action-group> GET _plugins/_security/api/actiongroups/<action-group>
``` ```
#### Sample response #### Sample response
@ -199,7 +199,7 @@ Retrieves all action groups.
#### Request #### Request
``` ```
GET _opensearch/_security/api/actiongroups/ GET _plugins/_security/api/actiongroups/
``` ```
@ -228,7 +228,7 @@ GET _opensearch/_security/api/actiongroups/
#### Request #### Request
``` ```
DELETE _opensearch/_security/api/actiongroups/<action-group> DELETE _plugins/_security/api/actiongroups/<action-group>
``` ```
#### Sample response #### Sample response
@ -248,7 +248,7 @@ Creates or replaces the specified action group.
#### Request #### Request
```json ```json
PUT _opensearch/_security/api/actiongroups/<action-group> PUT _plugins/_security/api/actiongroups/<action-group>
{ {
"allowed_actions": [ "allowed_actions": [
"indices:data/write/index*", "indices:data/write/index*",
@ -278,7 +278,7 @@ Updates individual attributes of an action group.
#### Request #### Request
```json ```json
PATCH _opensearch/_security/api/actiongroups/<action-group> PATCH _plugins/_security/api/actiongroups/<action-group>
[ [
{ {
"op": "replace", "path": "/allowed_actions", "value": ["indices:admin/create", "indices:admin/mapping/put"] "op": "replace", "path": "/allowed_actions", "value": ["indices:admin/create", "indices:admin/mapping/put"]
@ -303,7 +303,7 @@ Creates, updates, or deletes multiple action groups in a single call.
#### Request #### Request
```json ```json
PATCH _opensearch/_security/api/actiongroups PATCH _plugins/_security/api/actiongroups
[ [
{ {
"op": "add", "path": "/CREATE_INDEX", "value": { "allowed_actions": ["indices:admin/create", "indices:admin/mapping/put"] } "op": "add", "path": "/CREATE_INDEX", "value": { "allowed_actions": ["indices:admin/create", "indices:admin/mapping/put"] }
@ -336,7 +336,7 @@ These calls let you create, update, and delete internal users. If you use an ext
#### Request #### Request
``` ```
GET _opensearch/_security/api/internalusers/<username> GET _plugins/_security/api/internalusers/<username>
``` ```
@ -361,7 +361,7 @@ GET _opensearch/_security/api/internalusers/<username>
#### Request #### Request
``` ```
GET _opensearch/_security/api/internalusers/ GET _plugins/_security/api/internalusers/
``` ```
#### Sample response #### Sample response
@ -385,7 +385,7 @@ GET _opensearch/_security/api/internalusers/
#### Request #### Request
``` ```
DELETE _opensearch/_security/api/internalusers/<username> DELETE _plugins/_security/api/internalusers/<username>
``` ```
#### Sample response #### Sample response
@ -407,7 +407,7 @@ Note that any role you supply in the `opensearch_security_roles` array must alre
#### Request #### Request
```json ```json
PUT _opensearch/_security/api/internalusers/<username> PUT _plugins/_security/api/internalusers/<username>
{ {
"password": "kirkpass", "password": "kirkpass",
"opensearch_security_roles": ["maintenance_staff", "weapons"], "opensearch_security_roles": ["maintenance_staff", "weapons"],
@ -436,7 +436,7 @@ Updates individual attributes of an internal user.
#### Request #### Request
```json ```json
PATCH _opensearch/_security/api/internalusers/<username> PATCH _plugins/_security/api/internalusers/<username>
[ [
{ {
"op": "replace", "path": "/backend_roles", "value": ["klingons"] "op": "replace", "path": "/backend_roles", "value": ["klingons"]
@ -466,7 +466,7 @@ Creates, updates, or deletes multiple internal users in a single call.
#### Request #### Request
```json ```json
PATCH _opensearch/_security/api/internalusers PATCH _plugins/_security/api/internalusers
[ [
{ {
"op": "add", "path": "/spock", "value": { "password": "testpassword1", "backend_roles": ["testrole1"] } "op": "add", "path": "/spock", "value": { "password": "testpassword1", "backend_roles": ["testrole1"] }
@ -502,7 +502,7 @@ Retrieves one role.
#### Request #### Request
``` ```
GET _opensearch/_security/api/roles/<role> GET _plugins/_security/api/roles/<role>
``` ```
#### Sample response #### Sample response
@ -548,7 +548,7 @@ Retrieves all roles.
#### Request #### Request
``` ```
GET _opensearch/_security/api/roles/ GET _plugins/_security/api/roles/
``` ```
#### Sample response #### Sample response
@ -586,7 +586,7 @@ GET _opensearch/_security/api/roles/
#### Request #### Request
``` ```
DELETE _opensearch/_security/api/roles/<role> DELETE _plugins/_security/api/roles/<role>
``` ```
#### Sample response #### Sample response
@ -606,7 +606,7 @@ Creates or replaces the specified role.
#### Request #### Request
```json ```json
PUT _opensearch/_security/api/roles/<role> PUT _plugins/_security/api/roles/<role>
{ {
"cluster_permissions": [ "cluster_permissions": [
"cluster_composite_ops", "cluster_composite_ops",
@ -651,7 +651,7 @@ Updates individual attributes of a role.
#### Request #### Request
```json ```json
PATCH _opensearch/_security/api/roles/<role> PATCH _plugins/_security/api/roles/<role>
[ [
{ {
"op": "replace", "path": "/index_permissions/0/fls", "value": ["myfield1", "myfield2"] "op": "replace", "path": "/index_permissions/0/fls", "value": ["myfield1", "myfield2"]
@ -679,7 +679,7 @@ Creates, updates, or deletes multiple roles in a single call.
#### Request #### Request
```json ```json
PATCH _opensearch/_security/api/roles PATCH _plugins/_security/api/roles
[ [
{ {
"op": "replace", "path": "/role1/index_permissions/0/fls", "value": ["test1", "test2"] "op": "replace", "path": "/role1/index_permissions/0/fls", "value": ["test1", "test2"]
@ -714,7 +714,7 @@ Retrieves one role mapping.
#### Request #### Request
``` ```
GET _opensearch/_security/api/rolesmapping/<role> GET _plugins/_security/api/rolesmapping/<role>
``` ```
#### Sample response #### Sample response
@ -737,7 +737,7 @@ Retrieves all role mappings.
#### Request #### Request
``` ```
GET _opensearch/_security/api/rolesmapping GET _plugins/_security/api/rolesmapping
``` ```
#### Sample response #### Sample response
@ -760,7 +760,7 @@ Deletes the specified role mapping.
#### Request #### Request
``` ```
DELETE _opensearch/_security/api/rolesmapping/<role> DELETE _plugins/_security/api/rolesmapping/<role>
``` ```
#### Sample response #### Sample response
@ -780,7 +780,7 @@ Creates or replaces the specified role mapping.
#### Request #### Request
```json ```json
PUT _opensearch/_security/api/rolesmapping/<role> PUT _plugins/_security/api/rolesmapping/<role>
{ {
"backend_roles" : [ "starfleet", "captains", "defectors", "cn=ldaprole,ou=groups,dc=example,dc=com" ], "backend_roles" : [ "starfleet", "captains", "defectors", "cn=ldaprole,ou=groups,dc=example,dc=com" ],
"hosts" : [ "*.starfleetintranet.com" ], "hosts" : [ "*.starfleetintranet.com" ],
@ -805,7 +805,7 @@ Updates individual attributes of a role mapping.
#### Request #### Request
```json ```json
PATCH _opensearch/_security/api/rolesmapping/<role> PATCH _plugins/_security/api/rolesmapping/<role>
[ [
{ {
"op": "replace", "path": "/users", "value": ["myuser"] "op": "replace", "path": "/users", "value": ["myuser"]
@ -833,7 +833,7 @@ Creates or updates multiple role mappings in a single call.
#### Request #### Request
```json ```json
PATCH _opensearch/_security/api/rolesmapping PATCH _plugins/_security/api/rolesmapping
[ [
{ {
"op": "add", "path": "/human_resources", "value": { "users": ["user1"], "backend_roles": ["backendrole2"] } "op": "add", "path": "/human_resources", "value": { "users": ["user1"], "backend_roles": ["backendrole2"] }
@ -865,7 +865,7 @@ Retrieves one tenant.
#### Request #### Request
``` ```
GET _opensearch/_security/api/tenants/<tenant> GET _plugins/_security/api/tenants/<tenant>
``` ```
#### Sample response #### Sample response
@ -889,7 +889,7 @@ Retrieves all tenants.
#### Request #### Request
``` ```
GET _opensearch/_security/api/tenants/ GET _plugins/_security/api/tenants/
``` ```
#### Sample response #### Sample response
@ -919,7 +919,7 @@ Deletes the specified tenant.
#### Request #### Request
``` ```
DELETE _opensearch/_security/api/tenants/<tenant> DELETE _plugins/_security/api/tenants/<tenant>
``` ```
#### Sample response #### Sample response
@ -939,7 +939,7 @@ Creates or replaces the specified tenant.
#### Request #### Request
```json ```json
PUT _opensearch/_security/api/tenants/<tenant> PUT _plugins/_security/api/tenants/<tenant>
{ {
"description": "A tenant for the human resources team." "description": "A tenant for the human resources team."
} }
@ -962,7 +962,7 @@ Add, delete, or modify a single tenant.
#### Request #### Request
```json ```json
PATCH _opensearch/_security/api/tenants/<tenant> PATCH _plugins/_security/api/tenants/<tenant>
[ [
{ {
"op": "replace", "path": "/description", "value": "An updated description" "op": "replace", "path": "/description", "value": "An updated description"
@ -987,7 +987,7 @@ Add, delete, or modify multiple tenants in a single call.
#### Request #### Request
```json ```json
PATCH _opensearch/_security/api/tenants/ PATCH _plugins/_security/api/tenants/
[ [
{ {
"op": "replace", "op": "replace",
@ -1024,7 +1024,7 @@ Retrieves the current security plugin configuration in JSON format.
#### Request #### Request
``` ```
GET _opensearch/_security/api/securityconfig GET _plugins/_security/api/securityconfig
``` ```
@ -1035,7 +1035,7 @@ Creates or updates the existing configuration using the REST API. This operation
#### Request #### Request
```json ```json
PUT _opensearch/_security/api/securityconfig/config PUT _plugins/_security/api/securityconfig/config
{ {
"dynamic": { "dynamic": {
"filtered_alias_mode": "warn", "filtered_alias_mode": "warn",
@ -1093,7 +1093,7 @@ Updates the existing configuration using the REST API. This operation can easily
#### Request #### Request
```json ```json
PATCH _opensearch/_security/api/securityconfig PATCH _plugins/_security/api/securityconfig
[ [
{ {
"op": "replace", "path": "/config/dynamic/authc/basic_internal_auth_domain/transport_enabled", "value": "true" "op": "replace", "path": "/config/dynamic/authc/basic_internal_auth_domain/transport_enabled", "value": "true"
@ -1122,7 +1122,7 @@ Retrieves the current security plugin configuration in JSON format.
#### Request #### Request
``` ```
GET _opensearch/_security/api/securityconfig GET _plugins/_security/api/securityconfig
``` ```
@ -1133,7 +1133,7 @@ Creates or updates the existing configuration using the REST API rather than `se
#### Request #### Request
```json ```json
PUT _opensearch/_security/api/securityconfig/config PUT _plugins/_security/api/securityconfig/config
{ {
"dynamic": { "dynamic": {
"filtered_alias_mode": "warn", "filtered_alias_mode": "warn",
@ -1191,7 +1191,7 @@ Updates the existing configuration using the REST API rather than `securityadmin
#### Request #### Request
```json ```json
PATCH _opensearch/_security/api/securityconfig PATCH _plugins/_security/api/securityconfig
[ [
{ {
"op": "replace", "path": "/config/dynamic/authc/basic_internal_auth_domain/transport_enabled", "value": "true" "op": "replace", "path": "/config/dynamic/authc/basic_internal_auth_domain/transport_enabled", "value": "true"
@ -1220,7 +1220,7 @@ Flushes the security plugin user, authentication, and authorization cache.
#### Request #### Request
``` ```
DELETE _opensearch/_security/api/cache DELETE _plugins/_security/api/cache
``` ```
@ -1246,7 +1246,7 @@ Checks to see if the security plugin is up and running. If you operate your clus
#### Request #### Request
``` ```
GET _opensearch/_security/health GET _plugins/_security/health
``` ```

View File

@ -190,8 +190,8 @@ curl -XGET -k -u 'admin:admin' 'https://localhost:9250/opensearch-cluster1:books
To continue testing, create a new user on both clusters: To continue testing, create a new user on both clusters:
```bash ```bash
curl -XPUT -k -u 'admin:admin' 'https://localhost:9200/_opensearch/_security/api/internalusers/booksuser' -H 'Content-Type: application/json' -d '{"password":"password"}' curl -XPUT -k -u 'admin:admin' 'https://localhost:9200/_plugins/_security/api/internalusers/booksuser' -H 'Content-Type: application/json' -d '{"password":"password"}'
curl -XPUT -k -u 'admin:admin' 'https://localhost:9250/_opensearch/_security/api/internalusers/booksuser' -H 'Content-Type: application/json' -d '{"password":"password"}' curl -XPUT -k -u 'admin:admin' 'https://localhost:9250/_plugins/_security/api/internalusers/booksuser' -H 'Content-Type: application/json' -d '{"password":"password"}'
``` ```
Then run the same search as before with `booksuser`: Then run the same search as before with `booksuser`:
@ -216,8 +216,8 @@ curl -XGET -k -u booksuser:password 'https://localhost:9250/opensearch-cluster1:
Note the permissions error. On the remote cluster, create a role with the appropriate permissions, and map `booksuser` to that role: Note the permissions error. On the remote cluster, create a role with the appropriate permissions, and map `booksuser` to that role:
```bash ```bash
curl -XPUT -k -u 'admin:admin' -H 'Content-Type: application/json' 'https://localhost:9200/_opensearch/_security/api/roles/booksrole' -d '{"index_permissions":[{"index_patterns":["books"],"allowed_actions":["indices:admin/shards/search_shards","indices:data/read/search"]}]}' curl -XPUT -k -u 'admin:admin' -H 'Content-Type: application/json' 'https://localhost:9200/_plugins/_security/api/roles/booksrole' -d '{"index_permissions":[{"index_patterns":["books"],"allowed_actions":["indices:admin/shards/search_shards","indices:data/read/search"]}]}'
curl -XPUT -k -u 'admin:admin' -H 'Content-Type: application/json' 'https://localhost:9200/_opensearch/_security/api/rolesmapping/booksrole' -d '{"users" : ["booksuser"]}' curl -XPUT -k -u 'admin:admin' -H 'Content-Type: application/json' 'https://localhost:9200/_plugins/_security/api/rolesmapping/booksrole' -d '{"users" : ["booksuser"]}'
``` ```
Both clusters must have the user, but only the remote cluster needs the role and mapping; in this case, the coordinating cluster handles authentication (i.e. "Does this request include valid user credentials?"), and the remote cluster handles authorization (i.e. "Can this user access this data?"). Both clusters must have the user, but only the remote cluster needs the role and mapping; in this case, the coordinating cluster handles authentication (i.e. "Does this request include valid user credentials?"), and the remote cluster handles authorization (i.e. "Can this user access this data?").

View File

@ -36,7 +36,7 @@ A typical request to the `_search` API includes `{ "query": { ... } }` around th
In the REST API, you provide the query as a string, so you must escape your quotes. This role allows a user to read any document in any index with the field `public` set to `true`: In the REST API, you provide the query as a string, so you must escape your quotes. This role allows a user to read any document in any index with the field `public` set to `true`:
```json ```json
PUT _opensearch/_security/api/roles/public_data PUT _plugins/_security/api/roles/public_data
{ {
"cluster_permissions": [ "cluster_permissions": [
"*" "*"
@ -64,7 +64,7 @@ A number of variables exist that you can use to enforce rules based on the prope
This rule allows a user to read any document where the username is a value of the `readable_by` field: This rule allows a user to read any document where the username is a value of the `readable_by` field:
```json ```json
PUT _opensearch/_security/api/roles/user_data PUT _plugins/_security/api/roles/user_data
{ {
"cluster_permissions": [ "cluster_permissions": [
"*" "*"
@ -99,7 +99,7 @@ You can use roles and parameter substitution with the `terms_set` query to enabl
#### User definition #### User definition
```json ```json
PUT _opensearch/_security/api/internalusers/user1 PUT _plugins/_security/api/internalusers/user1
{ {
"password": "asdf", "password": "asdf",
"backend_roles": ["abac"], "backend_roles": ["abac"],
@ -112,7 +112,7 @@ PUT _opensearch/_security/api/internalusers/user1
#### Role definition #### Role definition
```json ```json
PUT _opensearch/_security/api/roles/abac PUT _plugins/_security/api/roles/abac
{ {
"index_permissions": [{ "index_permissions": [{
"index_patterns": [ "index_patterns": [

View File

@ -42,8 +42,8 @@ plugins.security.authcz.impersonation_dn:
## Impersonating Users ## Impersonating Users
To impersonate another user, submit a request to the system with the HTTP header `opensearch_security_impersonate_as` set to the name of the user to be impersonated. A good test is to make a GET request to the `_opensearch/_security/authinfo` URI: To impersonate another user, submit a request to the system with the HTTP header `opensearch_security_impersonate_as` set to the name of the user to be impersonated. A good test is to make a GET request to the `_plugins/_security/authinfo` URI:
```bash ```bash
curl -XGET -u 'admin:admin' -k -H "opensearch_security_impersonate_as: user_1" https://localhost:9200/_opensearch/_security/authinfo?pretty curl -XGET -u 'admin:admin' -k -H "opensearch_security_impersonate_as: user_1" https://localhost:9200/_plugins/_security/authinfo?pretty
``` ```

View File

@ -48,7 +48,7 @@ After deciding which role you want to map your certificate's CN to, you can use
**Sample request** **Sample request**
```json ```json
PUT _opensearch/_security/api/rolesmapping/readall PUT _plugins/_security/api/rolesmapping/readall
{ {
"backend_roles" : ["sample_role" ], "backend_roles" : ["sample_role" ],
"hosts" : [ "example.host.com" ], "hosts" : [ "example.host.com" ],

View File

@ -308,13 +308,13 @@ plugins.security.auth.type: "saml"
In addition, the OpenSearch Dashboards endpoint for validating the SAML assertions must be whitelisted: In addition, the OpenSearch Dashboards endpoint for validating the SAML assertions must be whitelisted:
``` ```
server.xsrf.whitelist: ["/_opensearch/_security/saml/acs"] server.xsrf.whitelist: ["/_plugins/_security/saml/acs"]
``` ```
If you use the logout POST binding, you also need to whitelist the logout endpoint: If you use the logout POST binding, you also need to whitelist the logout endpoint:
```yml ```yml
server.xsrf.whitelist: ["/_opensearch/_security/saml/acs", "/_opensearch/_security/saml/logout"] server.xsrf.whitelist: ["/_plugins/_security/saml/acs", "/_plugins/_security/saml/logout"]
``` ```
### IdP-initiated SSO ### IdP-initiated SSO
@ -322,11 +322,11 @@ server.xsrf.whitelist: ["/_opensearch/_security/saml/acs", "/_opensearch/_securi
To use IdP-initiated SSO, set the Assertion Consumer Service endpoint of your IdP to this: To use IdP-initiated SSO, set the Assertion Consumer Service endpoint of your IdP to this:
``` ```
/_opensearch/_security/saml/acs/idpinitiated /_plugins/_security/saml/acs/idpinitiated
``` ```
Then add this endpoint to `server.xsrf.whitelist` in `opensearch_dashboards.yml`: Then add this endpoint to `server.xsrf.whitelist` in `opensearch_dashboards.yml`:
```yml ```yml
server.xsrf.whitelist: ["/_opensearch/_security/saml/acs/idpinitiated", "/_opensearch/_security/saml/acs", "/_opensearch/_security/saml/logout"] server.xsrf.whitelist: ["/_plugins/_security/saml/acs/idpinitiated", "/_plugins/_security/saml/acs", "/_plugins/_security/saml/logout"]
``` ```

View File

@ -42,7 +42,7 @@ After a successful login, your IdP sends a SAML response using HTTP POST to Open
The endpoint the OpenSearch Dashboards security plugin provides is: The endpoint the OpenSearch Dashboards security plugin provides is:
``` ```
/_opensearch/_security/saml/acs /_plugins/_security/saml/acs
``` ```
Make sure that you have configured this endpoint correctly in your IdP. Some IdPs also require you to whitelist all endpoints that they send requests to. Ensure that the ACS endpoint is listed. Make sure that you have configured this endpoint correctly in your IdP. Some IdPs also require you to whitelist all endpoints that they send requests to. Ensure that the ACS endpoint is listed.
@ -50,7 +50,7 @@ Make sure that you have configured this endpoint correctly in your IdP. Some IdP
OpenSearch Dashboards also requires you to whitelist this endpoint. Make sure you have the following entry in `opensearch_dashboards.yml`: OpenSearch Dashboards also requires you to whitelist this endpoint. Make sure you have the following entry in `opensearch_dashboards.yml`:
``` ```
server.xsrf.whitelist: [/_opensearch/_security/saml/acs] server.xsrf.whitelist: [/_plugins/_security/saml/acs]
``` ```
@ -94,7 +94,7 @@ This setting prints the SAML response to the OpenSearch log file so that you can
Another way of inspecting the SAML response is to monitor network traffic while logging in to OpenSearch Dashboards. The IdP uses HTTP POST requests to send Base64-encoded SAML responses to: Another way of inspecting the SAML response is to monitor network traffic while logging in to OpenSearch Dashboards. The IdP uses HTTP POST requests to send Base64-encoded SAML responses to:
``` ```
/_opensearch/_security/saml/acs /_plugins/_security/saml/acs
``` ```
Inspect the payload of this POST request, and use a tool like [base64decode.org](https://www.base64decode.org/) to decode it. Inspect the payload of this POST request, and use a tool like [base64decode.org](https://www.base64decode.org/) to decode it.