Provide abstraction for an Authenticated Principal

Author: jgrandja

core/src/main/java/org/springframework/security/authentication/AbstractAuthenticationToken.java

@@ -24,8 +24,8 @@
 import org.springframework.security.core.Authentication;
 import org.springframework.security.core.GrantedAuthority;
 import org.springframework.security.core.CredentialsContainer;
+import org.springframework.security.core.AuthenticatedPrincipal;
 import org.springframework.security.core.authority.AuthorityUtils;
-import org.springframework.security.core.userdetails.UserDetails;
 
 /**
  * Base class for <code>Authentication</code> objects.
@@ -79,8 +79,8 @@ public Collection<GrantedAuthority> getAuthorities() {
 	}
 
 	public String getName() {
-		if (this.getPrincipal() instanceof UserDetails) {
-			return ((UserDetails) this.getPrincipal()).getUsername();
+		if (this.getPrincipal() instanceof AuthenticatedPrincipal) {
+			return ((AuthenticatedPrincipal) this.getPrincipal()).getName();
 		}
 
 		if (getPrincipal() instanceof Principal) {

core/src/main/java/org/springframework/security/core/AuthenticatedPrincipal.java

@@ -0,0 +1,46 @@
+/*
+ * Copyright 2012-2017 the original author or authors.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *      http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+package org.springframework.security.core;
+
+import org.springframework.security.authentication.AuthenticationManager;
+
+/**
+ * Representation of an authenticated <code>Principal</code> once an
+ * {@link Authentication} request has been successfully authenticated
+ * by the {@link AuthenticationManager#authenticate(Authentication)} method.
+ *
+ * Implementors typically provide their own representation of a <code>Principal</code>,
+ * which usually contains information describing the <code>Principal</code> entity,
+ * such as, first/middle/last name, address, email, phone, id, etc.
+ *
+ * This interface allows implementors to expose specific attributes
+ * of their custom representation of <code>Principal</code> in a generic way.
+ *
+ * @author Joe Grandja
+ * @since 5.0
+ * @see Authentication#getPrincipal()
+ * @see org.springframework.security.core.userdetails.UserDetails
+ */
+public interface AuthenticatedPrincipal {
+
+	/**
+	 * Returns the name of the authenticated <code>Principal</code>. Never <code>null</code>.
+	 *
+	 * @return the name of the authenticated <code>Principal</code>
+	 */
+	String getName();
+
+}

core/src/main/java/org/springframework/security/core/userdetails/UserDetails.java

@@ -18,6 +18,7 @@
 
 import org.springframework.security.core.Authentication;
 import org.springframework.security.core.GrantedAuthority;
+import org.springframework.security.core.AuthenticatedPrincipal;
 
 import java.io.Serializable;
 import java.util.Collection;
@@ -41,7 +42,7 @@
  *
  * @author Ben Alex
  */
-public interface UserDetails extends Serializable {
+public interface UserDetails extends AuthenticatedPrincipal, Serializable {
 	// ~ Methods
 	// ========================================================================================================
 
@@ -60,8 +61,7 @@ public interface UserDetails extends Serializable {
 	String getPassword();
 
 	/**
-	 * Returns the username used to authenticate the user. Cannot return <code>null</code>
-	 * .
+	 * Returns the username used to authenticate the user. Cannot return <code>null</code>.
 	 *
 	 * @return the username (never <code>null</code>)
 	 */
@@ -100,4 +100,14 @@ public interface UserDetails extends Serializable {
 	 * @return <code>true</code> if the user is enabled, <code>false</code> otherwise
 	 */
 	boolean isEnabled();
+
+	/**
+	 * Returns the name of the user. Cannot return <code>null</code>.
+	 * The default implementation of this method returns {@link #getUsername()}.
+	 *
+	 * @return the name of the user (never <code>null</code>)
+	 */
+	default String getName() {
+		return getUsername();
+	}
 }

core/src/test/java/org/springframework/security/authentication/AbstractAuthenticationTokenTests.java

@@ -17,8 +17,10 @@
 package org.springframework.security.authentication;
 
 import static org.assertj.core.api.Assertions.*;
+import static org.mockito.Mockito.*;
 
 import org.junit.*;
+import org.springframework.security.core.AuthenticatedPrincipal;
 import org.springframework.security.core.GrantedAuthority;
 import org.springframework.security.core.authority.AuthorityUtils;
 import org.springframework.security.core.authority.SimpleGrantedAuthority;
@@ -135,6 +137,18 @@ public void testToStringWithNullAuthorities() {
 		assertThat(token.toString().lastIndexOf("Not granted any authorities") != -1).isTrue();
 	}
 
+	@Test
+	public void testGetNameWhenPrincipalIsAuthenticatedPrincipal() {
+		String principalName = "test";
+
+		AuthenticatedPrincipal principal = mock(AuthenticatedPrincipal.class);
+		when(principal.getName()).thenReturn(principalName);
+
+		MockAuthenticationImpl token = new MockAuthenticationImpl(principal, "Password", authorities);
+		assertThat(token.getName()).isEqualTo(principalName);
+		verify(principal, times(1)).getName();
+	}
+
 	// ~ Inner Classes
 	// ==================================================================================================
 

core/src/test/java/org/springframework/security/core/userdetails/UserDetailsTest.java

@@ -0,0 +1,81 @@
+/*
+ * Copyright 2012-2017 the original author or authors.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *      http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+package org.springframework.security.core.userdetails;
+
+import org.junit.Test;
+import org.springframework.security.core.GrantedAuthority;
+import org.springframework.security.core.authority.AuthorityUtils;
+
+import java.util.Collection;
+
+import static org.assertj.core.api.Assertions.assertThat;
+
+/**
+ * Tests {@link UserDetails}
+ *
+ * @author Joe Grandja
+ */
+public class UserDetailsTest {
+
+	@Test
+	public void getNameWhenCalledThenDefaultToGetUsername() {
+		UserDetails userDetails = new MockUserDetails("joeg");
+		assertThat(userDetails.getName()).isEqualTo(userDetails.getUsername());
+	}
+
+	private class MockUserDetails implements UserDetails {
+		private final String username;
+
+		private MockUserDetails(String username) {
+			this.username = username;
+		}
+
+		@Override
+		public Collection<? extends GrantedAuthority> getAuthorities() {
+			return AuthorityUtils.NO_AUTHORITIES;
+		}
+
+		@Override
+		public String getPassword() {
+			return null;
+		}
+
+		@Override
+		public String getUsername() {
+			return this.username;
+		}
+
+		@Override
+		public boolean isAccountNonExpired() {
+			return true;
+		}
+
+		@Override
+		public boolean isAccountNonLocked() {
+			return true;
+		}
+
+		@Override
+		public boolean isCredentialsNonExpired() {
+			return true;
+		}
+
+		@Override
+		public boolean isEnabled() {
+			return true;
+		}
+	}
+}