One of the new features in AppFuse 2.1 is an appfuse-ws archetype. This archetype leverages Enunciate and CXF to create a project with a REST API and generated HTML documentation. Enunciate is a very useful tool, allowing you to develop web services with JAX-RS and JAX-WS annotations and have all types of client libraries generated. For me, it seems very useful for developing the backend of SOFEA (a.k.a. modern) applications.
Back in March, Ryan Heaton published a nice article on Securing Web Services in an Enunciate application. I decided to take his tutorial a step further and not only secure my web services, but also to integrate with OAuth 2. In this tutorial, I'll show you how to create a new application with AppFuse WS, secure it, add OAuth support, and then use a client app to authenticate and retrieve data.
Create a New AppFuse WS Project
To begin, I visited the Create AppFuse Archetypes page and created a new application using the "Web Services Only" option in the Web Framework dropdown. Below is the command I used to create the "appfuse-oauth" project.
mvn archetype:generate -B -DarchetypeGroupId=org.appfuse.archetypes \
-DarchetypeArtifactId=appfuse-ws-archetype -DarchetypeVersion=2.1.0 \
-DgroupId=org.appfuse.example -DartifactId=appfuse-oauth
After doing this, I started the app using mvn jetty:run and confirmed it started OK. At this point, I was able to view the generated documentation for the application at http://localhost:8080. The screenshot below shows what the app looks like at this point.
NOTE: You might notice the REST endpoint of /{username}. This is a bug in AppFuse 2.1.0 and has been fixed in SVN. It does not affect this tutorial.
Integrate Spring Security and OAuth
I originally tried to integrate Spring Security with Enunciate's Securing Web Services Tutorial. However, it only secures endpoints and doesn't do enough filtering for OAuth support, so I ended up using a custom web.xml. I put this file in src/main/resources and loaded it in my enunciate.xml file. I also upgraded Spring Security and imported my security.xml file.
<?xml version="1.0"?>
<enunciate xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:noNamespaceSchemaLocation="http://enunciate.codehaus.org/schemas/enunciate-1.22.xsd">
...
<webapp mergeWebXML="src/main/resources/web.xml"/>
<modules>
...
<spring-app disabled="false" springVersion="3.0.5.RELEASE">
<springImport uri="classpath:/applicationContext-resources.xml"/>
<springImport uri="classpath:/applicationContext-dao.xml"/>
<springImport uri="classpath:/applicationContext-service.xml"/>
<springImport uri="classpath:/applicationContext.xml"/>
<springImport uri="classpath:/security.xml"/>
</spring-app>
</modules>
</enunciate>
Then I created src/main/resources/web.xml with a filter for Spring Security and a DispatcherServlet for OAuth support.
<?xml version="1.0" encoding="UTF-8"?>
<web-app xmlns="http://java.sun.com/xml/ns/javaee"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:schemaLocation="http://java.sun.com/xml/ns/javaee http://java.sun.com/xml/ns/javaee/web-app_3_0.xsd"
version="3.0">
<filter>
<filter-name>securityFilter</filter-name>
<filter-class>org.springframework.web.filter.DelegatingFilterProxy</filter-class>
<init-param>
<param-name>targetBeanName</param-name>
<param-value>springSecurityFilterChain</param-value>
</init-param>
</filter>
<filter-mapping>
<filter-name>securityFilter</filter-name>
<url-pattern>/*</url-pattern>
</filter-mapping>
<servlet>
<servlet-name>appfuse-oauth</servlet-name>
<servlet-class>org.springframework.web.servlet.DispatcherServlet</servlet-class>
<load-on-startup>1</load-on-startup>
</servlet>
<servlet-mapping>
<servlet-name>appfuse-oauth</servlet-name>
<url-pattern>/oauth/*</url-pattern>
</servlet-mapping>
</web-app>
Next, I created a src/main/resources/security.xml and used it to secure my API, specify a login page, supply the users and integrate OAuth (see the last 4 beans below).
<?xml version="1.0" encoding="UTF-8"?>
<beans:beans xmlns="http://www.springframework.org/schema/security"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xmlns:beans="http://www.springframework.org/schema/beans"
xmlns:oauth="http://www.springframework.org/schema/security/oauth2"
xsi:schemaLocation="http://www.springframework.org/schema/beans http://www.springframework.org/schema/beans/spring-beans.xsd
http://www.springframework.org/schema/security http://www.springframework.org/schema/security/spring-security.xsd
http://www.springframework.org/schema/security/oauth2 http://www.springframework.org/schema/security/spring-security-oauth2.xsd">
<http auto-config="true">
<intercept-url pattern="/api/**" access="ROLE_USER"/>
<intercept-url pattern="/oauth/**" access="ROLE_USER"/>
<intercept-url pattern="/**" access="IS_AUTHENTICATED_ANONYMOUSLY"/>
<form-login login-page="/login.jsp" authentication-failure-url="/login.jsp?error=true"
login-processing-url="/j_security_check"/>
</http>
<authentication-manager>
<authentication-provider>
<user-service>
<user name="admin" password="admin" authorities="ROLE_USER,ROLE_ADMIN"/>
<user name="user" password="user" authorities="ROLE_USER"/>
</user-service>
</authentication-provider>
</authentication-manager>
<!--hook up the spring security filter chain-->
<beans:alias name="springSecurityFilterChain" alias="securityFilter"/>
<beans:bean id="tokenServices"
class="org.springframework.security.oauth2.provider.token.InMemoryOAuth2ProviderTokenServices">
<beans:property name="supportRefreshToken" value="true"/>
</beans:bean>
<oauth:provider client-details-service-ref="clientDetails" token-services-ref="tokenServices">
<oauth:verification-code user-approval-page="/oauth/confirm_access"/>
</oauth:provider>
<oauth:client-details-service id="clientDetails">
<!--<oauth:client clientId="my-trusted-client" authorizedGrantTypes="password,authorization_code,refresh_token"/>
<oauth:client clientId="my-trusted-client-with-secret"
authorizedGrantTypes="password,authorization_code,refresh_token" secret="somesecret"/>
<oauth:client clientId="my-less-trusted-client" authorizedGrantTypes="authorization_code"/>-->
<oauth:client clientId="ajax-login" authorizedGrantTypes="authorization_code"/>
</oauth:client-details-service>
</beans:beans>
I used the OAuth for Spring Security sample apps to figure this out. In this example, I used authorizedGrantTypes="authorization_code", but you can see from the commented <oauth:client> elements above that there's a few different options. You should also note that the clientId is hard-coded to "ajax-login", signifying I only want to allow a single application to authenticate.
At this point, I'd like to give a shoutout to Ryan Heaton for creating both Enunciate and Spring Security's OAuth support. Nice work Ryan!
At this point, I needed to do a number of additional tasks to finish integrating oauth. The first was to modify the Jetty Plugin's configuration to 1) run on port 9000, 2) load my custom files and 3) allow jetty:run to recognize Enunciate's generated files. Below is the final configuration in my pom.xml.
<plugin>
<groupId>org.mortbay.jetty</groupId>
<artifactId>maven-jetty-plugin</artifactId>
<version>6.1.26</version>
<configuration>
<connectors>
<connector implementation="org.mortbay.jetty.nio.SelectChannelConnector">
<port>9000</port>
<maxIdleTime>60000</maxIdleTime>
</connector>
</connectors>
<webAppConfig>
<baseResource implementation="org.mortbay.resource.ResourceCollection">
<resourcesAsCSV>
${basedir}/src/main/webapp,
${project.build.directory}/${project.build.finalName}
</resourcesAsCSV>
</baseResource>
<contextPath>/appfuse-oauth</contextPath>
</webAppConfig>
<webXml>${project.build.directory}/${project.build.finalName}/WEB-INF/web.xml</webXml>
</configuration>
</plugin>
Next, I added the necessary OAuth dependencies for Spring Security to my pom.xml. Since the latest release is a milestone release, I had to add Spring's milestone repo too.
<repository>
<id>spring-milestone</id>
<url>http://s3.amazonaws.com/maven.springframework.org/milestone</url>
</repository>
...
<dependency>
<groupId>org.springframework.security</groupId>
<artifactId>spring-security-taglibs</artifactId>
<version>${spring.version}</version>
<exclusions>
<exclusion>
<groupId>org.springframework</groupId>
<artifactId>spring-web</artifactId>
</exclusion>
<exclusion>
<groupId>org.springframework</groupId>
<artifactId>spring-support</artifactId>
</exclusion>
</exclusions>
</dependency>
<dependency>
<groupId>org.springframework.security.oauth</groupId>
<artifactId>spring-security-oauth</artifactId>
<version>1.0.0.M3</version>
<exclusions>
<exclusion>
<groupId>org.springframework</groupId>
<artifactId>spring-beans</artifactId>
</exclusion>
<exclusion>
<groupId>org.springframework</groupId>
<artifactId>spring-context</artifactId>
</exclusion>
<exclusion>
<groupId>org.springframework</groupId>
<artifactId>spring-core</artifactId>
</exclusion>
</exclusions>
</dependency>
<dependency>
<groupId>org.springframework</groupId>
<artifactId>spring-webmvc</artifactId>
<version>${spring.version}</version>
</dependency>
<dependency>
<groupId>javax.servlet</groupId>
<artifactId>servlet-api</artifactId>
<version>2.5</version>
<scope>provided</scope>
</dependency>
<dependency>
<groupId>javax.servlet</groupId>
<artifactId>jstl</artifactId>
<version>1.1.2</version>
</dependency>
<dependency>
<groupId>taglibs</groupId>
<artifactId>standard</artifactId>
<version>1.1.2</version>
</dependency>
Since I named my DispatcherServlet "appfuse-oauth" in web.xml, I created a src/main/webapp/WEB-INF/appfuse-oauth-servlet.xml to configure Spring MVC. I had to create the src/main/webapp/WEB-INF directory.
<?xml version="1.0" encoding="UTF-8"?>
<beans xmlns="http://www.springframework.org/schema/beans"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xmlns:context="http://www.springframework.org/schema/context"
xmlns:mvc="http://www.springframework.org/schema/mvc"
xsi:schemaLocation="http://www.springframework.org/schema/beans http://www.springframework.org/schema/beans/spring-beans-3.0.xsd
http://www.springframework.org/schema/context http://www.springframework.org/schema/context/spring-context-3.0.xsd
http://www.springframework.org/schema/mvc http://www.springframework.org/schema/mvc/spring-mvc-3.0.xsd">
<!-- Scans the classpath of this application for @Components to deploy as beans -->
<context:component-scan base-package="org.appfuse.examples.webapp"/>
<!-- Configures the @Controller programming model -->
<mvc:annotation-driven/>
<!-- Resolves view names to protected .jsp resources within the /WEB-INF/views directory -->
<bean class="org.springframework.web.servlet.view.InternalResourceViewResolver">
<property name="viewClass" value="org.springframework.web.servlet.view.JstlView"/>
<property name="prefix" value="/"/>
<property name="suffix" value=".jsp"/>
</bean>
</beans>
In order to show the OAuth confirmation page, I needed to create src/main/java/org/appfuse/examples/webapp/AccessConfirmationController.java and map it to /oauth/confirm_access. I copied this from one of the sample projects and modified to use Spring's annotations.
package org.appfuse.examples.webapp;
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.security.oauth2.provider.ClientAuthenticationToken;
import org.springframework.security.oauth2.provider.ClientDetails;
import org.springframework.security.oauth2.provider.ClientDetailsService;
import org.springframework.security.oauth2.provider.verification.ClientAuthenticationCache;
import org.springframework.security.oauth2.provider.verification.DefaultClientAuthenticationCache;
import org.springframework.stereotype.Controller;
import org.springframework.web.bind.annotation.RequestMapping;
import org.springframework.web.bind.annotation.RequestMethod;
import org.springframework.web.servlet.ModelAndView;
import javax.servlet.http.HttpServletRequest;
import javax.servlet.http.HttpServletResponse;
import java.util.TreeMap;
/**
* Controller for retrieving the model for and displaying the confirmation page
* for access to a protected resource.
*
* @author Ryan Heaton
*/
@Controller
@RequestMapping("/confirm_access")
public class AccessConfirmationController {
private ClientAuthenticationCache authenticationCache = new DefaultClientAuthenticationCache();
@Autowired
private ClientDetailsService clientDetailsService;
@RequestMapping(method = RequestMethod.GET)
protected ModelAndView confirm(HttpServletRequest request, HttpServletResponse response) throws Exception {
ClientAuthenticationToken clientAuth = authenticationCache.getAuthentication(request, response);
if (clientAuth == null) {
throw new IllegalStateException("No client authentication request to authorize.");
}
TreeMap<String, Object> model = new TreeMap<String, Object>();
ClientDetails client = clientDetailsService.loadClientByClientId(clientAuth.getClientId());
model.put("auth_request", clientAuth);
model.put("client", client);
return new ModelAndView("access_confirmation", model);
}
}
This controller delegates to src/main/webapp/access_confirmation.jsp. I created this file and filled it with code to display Accept and Deny buttons.
<%@ page import="org.springframework.security.core.AuthenticationException" %>
<%@ page import="org.springframework.security.oauth2.common.exceptions.UnapprovedClientAuthenticationException" %>
<%@ page import="org.springframework.security.oauth2.provider.verification.BasicUserApprovalFilter" %>
<%@ page import="org.springframework.security.oauth2.provider.verification.VerificationCodeFilter" %>
<%@ page import="org.springframework.security.web.WebAttributes" %>
<%@ taglib prefix="authz" uri="http://www.springframework.org/security/tags" %>
<%@ taglib uri="http://java.sun.com/jsp/jstl/core" prefix="c" %>
<html>
<head>
<title>Confirm Access</title>
<link rel="stylesheet" type="text/css" media="all"
href="http://demo.appfuse.org/appfuse-struts/styles/simplicity/theme.css"/>
<style type="text/css">
h1 {
margin-left: -300px;
margin-top: 50px
}
</style>
</head>
<body>
<h1>Confirm Access</h1>
<div id="content">
<% if (session.getAttribute(WebAttributes.AUTHENTICATION_EXCEPTION) != null &&
!(session.getAttribute(WebAttributes.AUTHENTICATION_EXCEPTION) instanceof UnapprovedClientAuthenticationException)) { %>
<div class="error">
<h2>Woops!</h2>
<p>Access could not be granted.
(<%= ((AuthenticationException) session.getAttribute(WebAttributes.AUTHENTICATION_EXCEPTION)).getMessage() %>)</p>
</div>
<% } %>
<c:remove scope="session" var="SPRING_SECURITY_LAST_EXCEPTION"/>
<authz:authorize ifAnyGranted="ROLE_USER,ROLE_ADMIN">
<h2>Please Confirm</h2>
<p>You hereby authorize "<c:out value="${client.clientId}" escapeXml="true"/>" to access your protected resources.</p>
<form id="confirmationForm" name="confirmationForm"
action="<%=request.getContextPath() + VerificationCodeFilter.DEFAULT_PROCESSING_URL%>" method="POST">
<input name="<%=BasicUserApprovalFilter.DEFAULT_APPROVAL_REQUEST_PARAMETER%>"
value="<%=BasicUserApprovalFilter.DEFAULT_APPROVAL_PARAMETER_VALUE%>" type="hidden"/>
<label><input name="authorize" value="Authorize" type="submit"></label>
</form>
<form id="denialForm" name="denialForm"
action="<%=request.getContextPath() + VerificationCodeFilter.DEFAULT_PROCESSING_URL%>" method="POST">
<input name="<%=BasicUserApprovalFilter.DEFAULT_APPROVAL_REQUEST_PARAMETER%>"
value="not_<%=BasicUserApprovalFilter.DEFAULT_APPROVAL_PARAMETER_VALUE%>" type="hidden"/>
<label><input name="deny" value="Deny" type="submit"></label>
</form>
</authz:authorize>
</div>
</body>
</html>
Finally, I needed to create src/main/webapp/login.jsp to allow users to login.
<%@ page language="java" pageEncoding="UTF-8" contentType="text/html;charset=utf-8" %>
<%@ taglib uri="http://java.sun.com/jsp/jstl/core" prefix="c" %>
<%@ taglib uri="http://java.sun.com/jsp/jstl/fmt" prefix="fmt" %>
<%@ taglib uri="http://java.sun.com/jsp/jstl/core" prefix="c" %>
<html>
<head>
<title>Login</title>
<link rel="stylesheet" type="text/css" media="all"
href="http://demo.appfuse.org/appfuse-struts/styles/simplicity/theme.css"/>
<style type="text/css">
h1 {
margin-left: -300px;
margin-top: 50px
}
</style>
</head>
<body>
<h1>Login</h1>
<form method="post" id="loginForm" action="<c:url value='/j_security_check'/>">
<fieldset style="padding-bottom: 0">
<ul>
<c:if test="${param.error != null}">
<li class="error">
${sessionScope.SPRING_SECURITY_LAST_EXCEPTION.message}
</li>
</c:if>
<li>
<label for="j_username" class="required desc">
Username <span class="req">*</span>
</label>
<input type="text" class="text medium" name="j_username"
id="j_username" tabindex="1"/>
</li>
<li>
<label for="j_password" class="required desc">
Password <span class="req">*</span>
</label>
<input type="password" class="text medium" name="j_password"
id="j_password" tabindex="2"/>
</li>
<li>
<input type="submit" class="button" name="login" value="Login"
tabindex="3"/>
</li>
</ul>
</fieldset>
</form>
</body>
</html>
All the changes described in the above section are necessary to implement OAuth if you create a project with AppFuse WS 2.1. It may seem like a lot of code, but I was able to copy/paste and get it all working in an app in under 5 minutes. Hopefully you can do the same. I'm also considering adding it by default to the next version of AppFuse. Now let's look at integrating OAuth into a client to authenticate and retrieve data from this application.
Authenticate and Retrieve Data with Client
I originally thought my GWT OAuth application would provide a nice client. However, after 30 minutes of trying to get GWT 1.7.1 and the GWT Maven plugin (1.1) working with my 64-bit Java 6 JDK on OS X, I gave up. So I opted to use the Ajax Login application I've been using in my recent security tutorials.
In this example, I used OAuth2RestTemplate from Spring Security OAuth. While this works, and works well, I'd still like to get things working with GWT (or jQuery) to demonstrate how to do it from a pure client-side perspective.
To begin, I got the latest source of Ajax Login from GitHub (as of this morning) and made some changes. First of all, I added the Spring Security OAuth dependencies to pom.xml:
<repository>
<id>spring-milestone</id>
<url>http://s3.amazonaws.com/maven.springframework.org/milestone</url>
</repository>
...
<dependency>
<groupId>org.springframework.security.oauth</groupId>
<artifactId>spring-security-oauth</artifactId>
<version>1.0.0.M3</version>
<exclusions>
<exclusion>
<groupId>org.springframework</groupId>
<artifactId>spring-beans</artifactId>
</exclusion>
<exclusion>
<groupId>org.springframework</groupId>
<artifactId>spring-context</artifactId>
</exclusion>
<exclusion>
<groupId>org.springframework</groupId>
<artifactId>spring-core</artifactId>
</exclusion>
</exclusions>
</dependency>
Then I modified src/main/webapp/WEB-INF/security.xml and added an OAuth Token Service and defined the location of the OAuth server.
<?xml version="1.0" encoding="UTF-8"?>
<beans:beans xmlns="http://www.springframework.org/schema/security"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xmlns:beans="http://www.springframework.org/schema/beans"
xmlns:oauth="http://www.springframework.org/schema/security/oauth2"
xsi:schemaLocation="http://www.springframework.org/schema/beans http://www.springframework.org/schema/beans/spring-beans-3.0.xsd
http://www.springframework.org/schema/security http://www.springframework.org/schema/security/spring-security-3.0.xsd
http://www.springframework.org/schema/security/oauth2 http://www.springframework.org/schema/security/spring-security-oauth2.xsd">
...
<oauth:client token-services-ref="oauth2TokenServices"/>
<beans:bean id="oauth2TokenServices"
class="org.springframework.security.oauth2.consumer.token.InMemoryOAuth2ClientTokenServices"/>
<oauth:resource id="appfuse" type="authorization_code" clientId="ajax-login"
accessTokenUri="http://localhost:9000/appfuse-oauth/oauth/authorize"
userAuthorizationUri="http://localhost:9000/appfuse-oauth/oauth/user/authorize"/>
Next, I created a Controller that uses OAuth2RestTemplate to make the request and get the data from the AppFuse OAuth application's API. I created src/main/java/org/appfuse/examples/webapp/oauth/UsersApiController.java and filled it with the following code:
package org.appfuse.examples.webapp.oauth;
import org.appfuse.model.User;
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.beans.factory.annotation.Qualifier;
import org.springframework.security.core.context.SecurityContextHolder;
import org.springframework.security.oauth2.common.exceptions.InvalidTokenException;
import org.springframework.security.oauth2.consumer.*;
import org.springframework.security.oauth2.consumer.token.OAuth2ClientTokenServices;
import org.springframework.stereotype.Controller;
import org.springframework.web.bind.annotation.RequestMapping;
import org.springframework.web.bind.annotation.RequestMethod;
import org.springframework.web.bind.annotation.ResponseBody;
import java.util.ArrayList;
import java.util.List;
@RequestMapping("/appfuse/users")
@Controller
public class UsersApiController {
private OAuth2RestTemplate apiRestTemplate;
@Autowired
private OAuth2ClientTokenServices tokenServices;
private static final String REMOTE_DATA_URL = "http://localhost:9000/appfuse-oauth/api/users";
@Autowired
public UsersApiController(OAuth2ProtectedResourceDetails resourceDetails) {
this.apiRestTemplate = new OAuth2RestTemplate(resourceDetails);
}
@RequestMapping(method = RequestMethod.GET)
@ResponseBody
public List<User> getUsers() {
try {
List users = apiRestTemplate.getForObject(REMOTE_DATA_URL, List.class);
return new ArrayList<User>(users);
} catch (InvalidTokenException badToken) {
//we've got a bad token, probably because it's expired.
OAuth2ProtectedResourceDetails resource = apiRestTemplate.getResource();
OAuth2SecurityContext context = OAuth2SecurityContextHolder.getContext();
if (context != null) {
// this one is kind of a hack for this application
// the problem is that the sparklr photos page doesn't remove the 'code=' request parameter.
((OAuth2SecurityContextImpl) context).setVerificationCode(null);
}
//clear any stored access tokens...
tokenServices.removeToken(SecurityContextHolder.getContext().getAuthentication(), resource);
//go get a new access token...
throw new OAuth2AccessTokenRequiredException(resource);
}
}
}
At this point, I thought everything would work and I spent quite some time banging my head against the wall when it didn't. As I was composing an email to the Enunciate users mailing list, I realized the issue. It appeared to be working, but from the server side, and the redirect back to the client was not happening. The Ajax Login app uses UrlRewriteFilter (for pretty URLs) to redirect from /app/* to /$1 and this redirect was losing the code parameter in the URL.
<rule>
<from>/app/**</from>
<to last="true" type="redirect">%{context-path}/$1</to>
</rule>
To fix this, I added use-query-string="true" to the root element in src/main/webapp/WEB-INF/urlrewrite.xml:
<urlrewrite default-match-type="wildcard" use-query-string="true">
After making all these changes, I ran mvn jetty:run on both apps and opened http://localhost:8080/appfuse/users in my browser. It all worked and a smile crept across my face. I've checked in the client changes into ajax-login on GitHub and the appfuse-oauth example into AppFuse Demos on Google Code. If you'd like to see this example in action, I'd encourage you to checkout both projects and let me know if you find any issues.
If someone asked you to develop a REST API on the JVM, which frameworks would you use? I was recently tasked with such a project.
My client asked me to implement a REST API to ingest requests from a 3rd party. The project entailed consuming XML
requests, storing the data in a database, then exposing the data to internal application with a JSON endpoint.
Finally, it would allow taking in a JSON request and turning it into an XML request back to the 3rd party.
