diff --git a/docs/reference/security/authorization/managing-roles.asciidoc b/docs/reference/security/authorization/managing-roles.asciidoc
index 535d70cbc5e9c..d42bfc725379c 100644
--- a/docs/reference/security/authorization/managing-roles.asciidoc
+++ b/docs/reference/security/authorization/managing-roles.asciidoc
@@ -120,6 +120,12 @@ multiple data streams, indices, and aliases.
 ------------------------------------------------------------------------------
 ==============================================================================
 
+[IMPORTANT]
+==============================
+Granting privileges over an alias and hence granting privileges over all the indices that the alias points to is deprecated and will be removed in a future version of Elasticsearch.
+Instead define permissions exclusively on index names or index name patterns.
+==============================
+
 [[roles-global-priv]]
 ==== Global privileges
 The following describes the structure of the global privileges entry: