SEC-1529: More user-friendly expression @PreAuthorize expression in EL chapter.

docs/manual/src/docbook/el-access.xml

@@ -154,14 +154,16 @@
                     within the expression, so you can also access properties on the arguments. For
                     example, if you wanted a particular method to only allow access to a user whose
                     username matched that of the contact, you could write</para>
-                <programlisting>  @PreAuthorize("#contact.name == principal.name)")
+                <programlisting>
+  @PreAuthorize("#contact.name == authentication.name")
   public void doSomething(Contact contact);</programlisting>
-                <para>Here we are accessing another built–in expression, which is the
+                <para>Here we are accessing another built–in expression, <literal>authentication</literal>,
-                        <literal>principal</literal> of the current Spring Security
+                    which is the <interfacename>Authentication</interfacename> stored in the
-                        <interfacename>Authentication</interfacename> object obtained from the
+                    security context. You can also access its <quote>principal</quote> property
-                    security context. You can also access the
+                    directly, using the expression <literal>principal</literal>. The value will
-                        <interfacename>Authentication</interfacename> object itself directly using
+                    often be a <interfacename>UserDetails</interfacename> instance, so you might use an
-                    the expression name <literal>authentication</literal>.</para>
+                    expression like <literal>principal.username</literal> or
+                    <literal>principal.enabled</literal>.</para>
                 <para>Less commonly, you may wish to perform an access-control check after the
                     method has been invoked. This can be achieved using the
                         <literal>@PostAuthorize</literal> annotation. To access the return value