Add host-based role mapping section to create role mapping API (#10289) (#10308)

* Add host-based role mapping section to create role mapping API



* Update _security/access-control/api.md



---------



(cherry picked from commit 5ab3d50)

Signed-off-by: Fanit Kolchina <kolchfa@amazon.com>
Signed-off-by: kolchfa-aws <105444904+kolchfa-aws@users.noreply.github.com>
Signed-off-by: github-actions[bot] <github-actions[bot]@users.noreply.github.com>
Co-authored-by: github-actions[bot] <github-actions[bot]@users.noreply.github.com>

Author: opensearch-trigger-bot[bot]

_security/access-control/api.md

@@ -940,6 +940,22 @@ PUT _plugins/_security/api/rolesmapping/<role>
 ```
 {% include copy-curl.html %}
 
+#### Host-based role mapping
+
+The `hosts` parameter maps requests originating from specific IP addresses or hostnames to the given role. CIDR blocks are not supported, but you can use wildcard patterns (globs), such as `192.168.*.*` or `*.example.com`. This is useful when you want to assign roles based on the client's source address:
+
+* To match by IP address (for example, `"192.168.1.10"`), no additional configuration is needed.
+* To match by hostname (for example, `"myserver.example.com"`), you must set the cluster-level configuration parameter:
+
+  ```yaml
+  opensearch_security.host_resolver_mode: ip-hostname
+  ```
+
+  This enables reverse DNS lookups to resolve hostnames. For more information, see [Configuring OpenSearch](https://docs.opensearch.org/docs/latest/install-and-configure/configuring-opensearch/index/).
+
+Using `"*"` in `hosts` matches all client IPs and hostnames, meaning this role will be applied to every request, regardless of user. This can unintentionally overgrant access if used alongside `users: ["someuser"]`. Avoid setting `hosts: ["*"]` unless you're intentionally granting the role to all client IPs.
+{: .warning}
+
 #### Example response
 
 ```json