Add @AuthenticationPrincipal expression

It is now possible to provide a SpEL expression for
@AuthenticationPrincipal. This allows invoking custom logic including
methods on the principal object.

Fixes gh-3859

core/src/main/java/org/springframework/security/core/annotation/AuthenticationPrincipal.java

@@ -30,9 +30,9 @@ import org.springframework.security.core.Authentication;
  * @author Rob Winch
  * @since 4.0
  *
- *  See: <a href="{@docRoot}/org/springframework/security/web/method/annotation/AuthenticationPrincipalArgumentResolver.html">
- *  AuthenticationPrincipalArgumentResolver
- *  </a>
+ * See: <a href=
+ * "{@docRoot}/org/springframework/security/web/method/annotation/AuthenticationPrincipalArgumentResolver.html"
+ * > AuthenticationPrincipalArgumentResolver </a>
  */
 @Target({ ElementType.PARAMETER, ElementType.ANNOTATION_TYPE })
 @Retention(RetentionPolicy.RUNTIME)
@@ -46,4 +46,33 @@ public @interface AuthenticationPrincipal {
 	 * @return
 	 */
 	boolean errorOnInvalidType() default false;
+
+	/**
+	 * If specified will use the provided SpEL expression to resolve the principal. This
+	 * is convenient if users need to transform the result.
+	 *
+	 * <p>
+	 * For example, perhaps the user wants to resolve a CustomUser object that is final
+	 * and is leveraging a UserDetailsService. This can be handled by returning an object
+	 * that looks like:
+	 * </p>
+	 *
+	 * <pre>
+	 * public class CustomUserUserDetails extends User {
+	 *     // ...
+	 *     public CustomUser getCustomUser() {
+	 *         return customUser;
+	 *     }
+	 * }
+	 * </pre>
+	 *
+	 * Then the user can specify an annotation that looks like:
+	 *
+	 * <pre>
+	 * &#64;AuthenticationPrincipal(expression = "customUser")
+	 * </pre>
+	 *
+	 * @return the expression to use.
+	 */
+	String expression() default "";
 }