JwtTokenEnhancer -> JwtAccessTokenConverter

docs/oauth2.md

@@ -63,7 +63,13 @@ The [`AuthorizationServerTokenServices`][AuthorizationServerTokenServices] inter
 * When an access token is created, the authentication must be stored so that the subsequent access token can reference it.
 * The access token is used to load the authentication that was used to authorize its creation.
 
-When creating your `AuthorizationServerTokenServices` implementation, you may want to consider using the [`DefaultTokenServices`][DefaultTokenServices] which creates tokens via random value and handles everything except for the persistence of the tokens which it delegates to a `TokenStore`. The default store is an [in-memory implementation][InMemoryTokenStore], but there is also a [jdbc version](JdbcTokenStore) that may be suitable for your needs.
+When creating your `AuthorizationServerTokenServices` implementation, you may want to consider using the [`DefaultTokenServices`][DefaultTokenServices] which creates tokens via random value and handles everything except for the persistence of the tokens which it delegates to a `TokenStore`. The default store is an [in-memory implementation][InMemoryTokenStore], but there are some other implementations available. Here's a description with some discussion of each of them
+
+* The default `InMemoryTokenStore` is perfectly fine for a single server (i.e. low traffic and no hot swap to a backup server in the case of failure). Most projects can start here, and maybe operate this way in development mode, to make it easy to start a server with no dependencies.
+
+* The `JdbcTokenStore` is the [JDBC version](JdbcTokenStore) of the same thing, which stores token data in a relational database. Use the JDBC version if you can share a database between servers, either scaled up instances of the same server if there is only one, or the Authorization and Resources Servers if there are multiple components. To use the `JdbcTokenStore` you need "spring-jdbc" on the classpath.
+
+* The [JSON Web Token (JWT) version](`JwtTokenStore`) of the store encodes all the data about the grant into the token itself (so no back end store at all which is a significant advantage).  One disadvantage is that you can't easily revoke an access token (so they normally are granted with short expiry and the revocation is handled at the refresh token). Another disadvantage is that the tokens can get quite large if you are storing a lot of user credential information in them. The `JwtTokenStore` is not really a "store" in the sense that it doesn't persist any datam but it plays the same role of translating betweeen token values and authentication information in the `DefaultTokenServices`. Note that the `JwtTokenStore` has a dependency on a `JwtAccessTokenConverter`, and the same implementation is needed by both the Authorization Server and the Resource Server (so they can agree on the contents and decode them safely). The tokens are signed by default, and the Resource Server has to be able to verify the signature, so it either needs the same symmetric (signing) key as the Authorization Server (shared secret, or symmetric key), or it needs the public key (verifier key) that matches the private key (signing key) in the Authorization (public-private or asymmetric key). To use the `JwtTokenStore` you need "spring-security-jwt" on your classpath (you can find it in the same github repository as Spring OAuth but with a different release cycle).
 
 ### Grant Types
 

spring-security-oauth2/src/main/java/org/springframework/security/oauth2/provider/token/AccessTokenConverter.java

@@ -31,7 +31,7 @@ public interface AccessTokenConverter {
 
 	final String EXP = "exp";
 
-	final String JTI = JwtTokenEnhancer.TOKEN_ID;
+	final String JTI = JwtAccessTokenConverter.TOKEN_ID;
 
 	final String SCOPE = OAuth2AccessToken.SCOPE;
 

spring-security-oauth2/src/main/java/org/springframework/security/oauth2/provider/token/JwtTokenEnhancer.java → spring-security-oauth2/src/main/java/org/springframework/security/oauth2/provider/token/JwtAccessTokenConverter.java

@@ -41,19 +41,23 @@
 import org.springframework.util.Assert;
 
 /**
- * OAuth2 token services that produces JWT encoded token values.
+ * Helper that translates between JWT encoded token values and OAuth authentication information (in both directions).
+ * Also acts as a {@link TokenEnhancer} when tokens are granted.
+ * 
+ * @see TokenEnhancer
+ * @see AccessTokenConverter
  * 
  * @author Dave Syer
  * @author Luke Taylor
  */
-public class JwtTokenEnhancer implements TokenEnhancer, AccessTokenConverter, InitializingBean {
+public class JwtAccessTokenConverter implements TokenEnhancer, AccessTokenConverter, InitializingBean {
 
 	/**
 	 * Field name for token id.
 	 */
 	public static final String TOKEN_ID = "jti";
 
-	private static final Log logger = LogFactory.getLog(JwtTokenEnhancer.class);
+	private static final Log logger = LogFactory.getLog(JwtAccessTokenConverter.class);
 
 	private AccessTokenConverter tokenConverter = new DefaultAccessTokenConverter();
 

spring-security-oauth2/src/main/java/org/springframework/security/oauth2/provider/token/JwtTokenStore.java

@@ -33,15 +33,15 @@
  * A {@link TokenStore} implementation that just reads data from the tokens themselves. Not really a store since it
  * never persists anything, and methods like {@link #getAccessToken(OAuth2Authentication)} always return null. But
  * nevertheless a useful tool since it translates access tokens to and from authentications. Use this wherever a
- * {@link TokenStore} is needed, but remember to use the same {@link JwtTokenEnhancer} instance (or one with the same
+ * {@link TokenStore} is needed, but remember to use the same {@link JwtAccessTokenConverter} instance (or one with the same
  * verifier) as was used when the tokens were minted.
  * 
  * @author Dave Syer
  *
  */
 public class JwtTokenStore implements TokenStore {
 
-	private JwtTokenEnhancer jwtTokenEnhancer;
+	private JwtAccessTokenConverter jwtTokenEnhancer;
 
 	private ApprovalStore approvalStore;
 
@@ -50,7 +50,7 @@ public class JwtTokenStore implements TokenStore {
 	 * 
 	 * @param jwtTokenEnhancer
 	 */
-	public JwtTokenStore(JwtTokenEnhancer jwtTokenEnhancer) {
+	public JwtTokenStore(JwtAccessTokenConverter jwtTokenEnhancer) {
 		this.jwtTokenEnhancer = jwtTokenEnhancer;
 	}
 
@@ -158,7 +158,7 @@ public Collection<OAuth2AccessToken> findTokensByClientId(String clientId) {
 		return Collections.emptySet();
 	}
 
-	public void setTokenEnhancer(JwtTokenEnhancer tokenEnhancer) {
+	public void setTokenEnhancer(JwtAccessTokenConverter tokenEnhancer) {
 		this.jwtTokenEnhancer = tokenEnhancer;
 	}
 

spring-security-oauth2/src/test/java/org/springframework/security/oauth2/config/annotation/AuthorizationServerConfigurationTests.java

@@ -56,7 +56,7 @@
 import org.springframework.security.oauth2.provider.token.DefaultTokenServices;
 import org.springframework.security.oauth2.provider.token.InMemoryTokenStore;
 import org.springframework.security.oauth2.provider.token.JdbcTokenStore;
-import org.springframework.security.oauth2.provider.token.JwtTokenEnhancer;
+import org.springframework.security.oauth2.provider.token.JwtAccessTokenConverter;
 import org.springframework.security.oauth2.provider.token.JwtTokenStore;
 import org.springframework.security.oauth2.provider.token.TokenStore;
 import org.springframework.test.util.ReflectionTestUtils;
@@ -336,8 +336,8 @@ public TokenStore tokenStore() {
 		}
 
 		@Bean
-		protected JwtTokenEnhancer jwtTokenEnhancer() {
-			return new JwtTokenEnhancer();
+		protected JwtAccessTokenConverter jwtTokenEnhancer() {
+			return new JwtAccessTokenConverter();
 		}
 
 		@Override

spring-security-oauth2/src/test/java/org/springframework/security/oauth2/provider/token/JwtTokenEnhancerTests.java

@@ -36,13 +36,13 @@
  */
 public class JwtTokenEnhancerTests {
 
-	private JwtTokenEnhancer tokenEnhancer;
+	private JwtAccessTokenConverter tokenEnhancer;
 
 	private Authentication userAuthentication;
 
 	@Before
 	public void setUp() throws Exception {
-		tokenEnhancer = new JwtTokenEnhancer();
+		tokenEnhancer = new JwtAccessTokenConverter();
 		userAuthentication = new TestAuthentication("test2", true);
 	}
 

spring-security-oauth2/src/test/java/org/springframework/security/oauth2/provider/token/JwtTokenStoreTests.java

@@ -24,7 +24,7 @@
  */
 public class JwtTokenStoreTests {
 
-	private JwtTokenEnhancer enhancer = new JwtTokenEnhancer();
+	private JwtAccessTokenConverter enhancer = new JwtAccessTokenConverter();
 
 	private JwtTokenStore tokenStore = new JwtTokenStore(enhancer);
 

spring-security-oauth2/src/test/java/org/springframework/security/oauth2/provider/token/TokenServicesWithTokenEnhancerTests.java

@@ -40,7 +40,7 @@ public class TokenServicesWithTokenEnhancerTests {
 
 	private DefaultTokenServices tokenServices = new DefaultTokenServices();
 
-	private JwtTokenEnhancer jwtTokenEnhancer = new JwtTokenEnhancer();
+	private JwtAccessTokenConverter jwtTokenEnhancer = new JwtAccessTokenConverter();
 
 	private TokenEnhancerChain enhancer = new TokenEnhancerChain();