Archive for July, 2013

Protect your REST resources using Membrane’s OAuth2 feature

July 22, 2013 2 comments


With the soon-to-be-published Membrane 4.0.7 you will be able to use OAuth2 with Google’s Authentication Service to restrict HTTP access to any REST resources.


This setup takes 5 minutes if you have a Google Account and Membrane Service Proxy already downloaded. Please note that Membrane Service Proxy 4.0.7 has not yet been released as of writing, but as it is Apache-licensed open source, you are free to get the source from and build it yourself (simply use mvn package -DskipTests) .

The Workflow

(If you want, you can skip straight to the “Brief Setup How-To” section.)

As the full OAuth2 workflow is a bit complex, we explain a simplified use case:


  1. The user requests the secret resource. (Think GET http://localhost:8080/secret/resource.) As she is not yet authorized, access is denied.
  2. The “denied” response contains a link to a login form (a redirect to
  3. The user tells Google that she wants Membrane Service Proxy to be able to authenticate her using her email address.
  4. Google returns an authorization token and a redirect to the original secret resource (http://localhost:8080/secret/resource).
  5. The user re-requests the secret resource. In contrast to step 1, the request now contains an authorization token.
  6. Membrane’s oauth2-google adapter verifies the authorization token.
  7. Google returns the user’s email address.
  8. As the user is now authorized, Membrane forwards the user’s HTTP request to the server hosting the secret resource.
  9. The secret response is received by Membrane and
  10. forwarded to the user without any further processing.

Brief Setup How-To

  1. Google Project setup
    1. Go to
    2. Create a new project.
    3. Under “API Access”, create an “OAuth2 Client ID…”.
    4. Fill in the “Branding Information”.
    5. Choose “Web Application” and enter the Membrane’s URL ( in our example “http://localhost:8080/“).
    6. Remember the “Client Id” (without the trailing ““) as well as the “Client Secret”.
  2. Membrane setup
      1. Download and unpack Membrane 4.0.7 or above.
      2. Change conf/proxies.xml to contain
    <spring:beans xmlns=""
        <serviceProxy name="localhost" port="8080" >
          <oauth2Resource publicURL="http://localhost:8080/">
            <google clientId="396[...]897-3g7[...]jkb" clientSecret="dTs[...]agb" />
            def email = exc.request.header.getFirstValue("X-Authenticated-Email")
            exc.response = Response.ok("Hello " + email + ".").build()
  3. Replace the publicURL in line 10 by the URL Membrane can be reached on. In our case this is already correct: http://localhost:8080/.
  4. Replace the clientId and clientSecret with the ones from the Google API console.
    (Note: the clientId might be numbers-only in your case.)
  5. Start Membrane Service Proxy by executing service-proxy.bat or
  6. Open http://localhost:8080/ in a browser.

Closing comments

You have seen how quickly OAuth2 authorization can be set up using Membrane Service Proxy.

In our setup, we used a simple, dynamically generated “Hello <your-gmail-address>.” page as the secret resource. The secret resource does not have to be hosted within Membrane, but can reside on any other HTTP server Membrane has access to, including localhost.

  • We did not perform any further checking of the user’s email address to protect our secret resource. In practice, you should do that, as getting possession of a valid gmail login is not really a challenge. ;)
  • The web server hosting the secret resource should probably be protected by a firewall so that the user cannot access the secret resource directly by circumventing Membrane.
  • You should use HTTPS for all untrusted network connections. Membrane Service Proxy automatically takes care of using HTTPS for steps 3, 4, 6 and 7. Membrane’s administrator should install SSL certificates and adjust the proxies.xml for all other steps, if necessary.
  • If the user (identified by a session ID cookie) issues any further requests, only steps 5, 8, 9 and 10 will take place.
  • If the session timed out, steps 3-5 might occur automatically, if Google decides that the user already has granted trust to access the user’s email address to Membrane.

Thank you for following us. If you are interested, you are welcome to read about all the other features of Membrane Service Proxy.

Categories: Router