diff --git a/x-pack/docs/en/security/authentication/configuring-saml-realm.asciidoc b/x-pack/docs/en/security/authentication/configuring-saml-realm.asciidoc
index 35f79b16d45..de8adde156c 100644
--- a/x-pack/docs/en/security/authentication/configuring-saml-realm.asciidoc
+++ b/x-pack/docs/en/security/authentication/configuring-saml-realm.asciidoc
@@ -218,12 +218,12 @@ When a user authenticates using SAML, they are identified to the {stack},
 but this does not automatically grant them access to perform any actions or
 access any data.
 
-Your SAML users cannot do anything until they are mapped to roles. See
-{stack-ov}/saml-role-mapping.html[Configuring role mappings]. 
+Your SAML users cannot do anything until they are assigned roles. This can be done
+through either the {stack-ov}/saml-role-mapping.html[role mapping API], or with
+{stack-ov}/realm-chains.html#authorization_realms[authorization realms].
 
-NOTE: The SAML realm supports
-{stack-ov}/realm-chains.html#authorization_realms[authorization realms] as an
-alternative to role mapping.
+NOTE: You cannot use {stack-ov}/defining-roles.html#roles-management-file[role mapping files]
+to grant roles to users authenticating via SAML.
 
 --
 
diff --git a/x-pack/docs/en/security/authentication/saml-guide.asciidoc b/x-pack/docs/en/security/authentication/saml-guide.asciidoc
index 2c11050a747..a2db942595a 100644
--- a/x-pack/docs/en/security/authentication/saml-guide.asciidoc
+++ b/x-pack/docs/en/security/authentication/saml-guide.asciidoc
@@ -620,11 +620,14 @@ When a user authenticates using SAML, they are identified to the Elastic Stack,
 but this does not automatically grant them access to perform any actions or
 access any data.
 
-Your SAML users cannot do anything until they are assigned roles. This is done
+Your SAML users cannot do anything until they are assigned roles. This can be done
 through either the
 {ref}/security-api-put-role-mapping.html[add role mapping API], or with
 <<authorization_realms, authorization realms>>.
 
+NOTE: You cannot use {stack-ov}/defining-roles.html#roles-management-file[role mapping files]
+to grant roles to users authenticating via SAML.
+
 This is an example of a simple role mapping that grants the `kibana_user` role
 to any user who authenticates against the `saml1` realm: