CXF OAuth 1.0 extension

Note: This page describes the OAuth GSOC 2009 project led by Lucasz Moren. Please go to the JAX-RS OAuth page for an up-to-date information.

CXF OAuth 1.0 extension has been build during Google Summer of Code 2010 programme. It implements specification: The OAuth 1.0 protocol (RFC 5849)  and allows CXF users to build OAuth server

and perform OAuth 1.0 authorization on their JAXRS services in a easy manner, by hiding complex OAuth flow. 

Downloading CXF OAuth 1.0 module

OAuth Server basic configuration

CXF, provides implementation for three endpoints from OAuth 1.0 specification:

• Temporary Credentials Endpoint
• Authorization Endpoint
• Token Credentials Endpoint

which are usual JAX-RS resources. They allow client application to receive access token from the server required to access resources at that server.

Configuration is exatcly this same as for every JAX-RS service:

<!-- Publish OAuth endpoints-->
    <jaxrs:server id="oauthServer" address="/oauth/">
        <jaxrs:serviceBeans>
            <ref bean="oauthServices"/>
        </jaxrs:serviceBeans>
        <jaxrs:providers>
            <ref bean="dispatchProvider"/>
        </jaxrs:providers>
    </jaxrs:server>

    <!--Definitions of OAuth module endpoints-->
    <bean id="oauthServices"
          class="org.apache.cxf.auth.oauth.endpoints.OAuthDefaultServices">
        <property name="displayVerifierURL" value="http://www.example.com/app/displayVerifier"/>
    </bean>

    <!--Redirects from Resource Owner Authorization Endpoint to sign in page-->
    <bean id="dispatchProvider">
        <property name="resourcePath" value="/oAuthLogin.jsp"/>
    </bean>

OAuth Server requires to save and read an OAuth data (OAuth tokens, oauth_verifier, client identifier ...) from the persistence storage specific for the particural web application. 

To make that transparent to the developers, CXF uses:

org.apache.cxf.auth.oauth.provider.OAuthDataProvider

interface as an integration point between llibrary and the application. There is provided sample implementation of that interface that manages data stored in the memory:

org.apache.cxf.auth.oauth.provider.MemoryOauthDataProvider

that is located in core OAuth module and 

org.apache.cxf.auth.oauth.demo.server.oauth.SampleOAuthDataProvider

in OAuth demo server module.

OAuth Endpoints explained

Temporary Credentials

Client sends oauth required parameters in order to receive temporary request token. CXF handles request, validates it, reads required information about the client and

save state(request token returned to the client in the response) required in the next OAuth request. CXF returns OAuth 1.0a specification compliant response.

Resource Owner Authorization

To assure more flexible authorization and access control to the server resources there were added two custom parameters, through which client specifies
what resources would like to access (scope), and how will be it accessing (permission):

• x_oauth_scope - specifies comma separated server uri's to which client wants to have access
• x_oauth_permission - specifies comma separated list of permissions to x_oauth_scope uri's which client wants to have (every permission is associated with role, ROLE_USER, ROLE_ADMIN, etc..)

i.e.:
After granting permissions by the user to server resources, CXF saves this data that will be required in later access control evaluation, generates oauth_verifier and returns it to the client.

Examplar screen where server user allows/denies access for a scopes and permissions requested by a third party application

Location of above confirmation screen can be configured by registering dispatch provider as shown in OAuth Server basic configuration. CXF returns OAuth compliant errors in case of wrong client requests. 

Token Credentials

Client sends request to the Authorization Server in order to exchange received in previous step oauth_verifier for an access token. Similarly in this step CXF handles request and return suitable response.
If the request is correct client receives an OAuth access token.
Access token give the rights to the user on the particular client to access previously authorized scopes with associated permissions.
Client need to attach access token with every request to oauth protected resource. In this implementation access token, represented by a string consist information of:

• client application 
• resource owner which provides credentials to authorize client to the server
• list of scopes accepted by the resource owner
• list of permissions (list of roles)

Intercepting OAuth authenticated requests

OAuthSecurityFilter

org.apache.cxf.auth.oauth.interceptors.OAuthSecurityFilter

intercepts OAuth authenticated request perform basic OAuth validation and check if requested scope is not greater than authorized by the resource owner.

Initial http request is wrapped with overrided: getUserPrincipal and isUserInRole methods and passed further. OAuth security filter does not assure access control based on permissions associated with the scope. It needs to be done by developer or 

by using: SpringOAuthAuthenticationFilter

Spring Security Integration

SpringOAuthAuthenticationFilter

Spring Security extension provides integration of OAuth flow with security annotations like: @RolesAllowed or @Secured

The only thing that needs to be done is adding

org.apache.cxf.auth.oauth.integration.spring.security.SpringOAuthAuthenticationFilter

configuration in web.xml file following OAuthSecurityFilter. SpringOAuthAuthenticationFilter initializes SpringSecurityContext and allows to benefit from Spring Security framework.
Sample JAX-RS service could looks like:

@Path("/")
public class SampleResourceProvider {

    @GET
    @Produces("text/html")
    @Path("/person/get/{name}")
    @Secured ({"ROLE_USER"})
    public Response getInfo(@PathParam("name") String name, @Context HttpServletRequest request) {
        return Response.ok("Successfully accessed OAuth protected person: " + name).build();
    }
}

In above example getInfo resource can be invoked only by the client which attached access token that was authorized by the resource owner with
scope: /*, person/*, person/get/* or /person/get/$particular_name and with permission associated with role: ROLE_USER.

SpringSecurityExceptionMapper

This exception mapper converts Spring Security exceptions (i.e. AccessDeniedException) into http response that is compliant with OAuth 1.0 specification.

OAuth Demo Server

Sample implementation of an OAuth server, build with using CXF OAuth extension. Provides simple functionality for preregistering OAuth clients, viewing authorized clients and revoking access to the server.

OAuth Demo Client

OAuth 1.0 client web application that is able to make OAuth authenticated requests