+49 228 5552576-0


info@predic8.com

OAuth2 Tutorial using Google as Authentication Service

Help needed?

Do you need any help for this tutorial. Then contact us using the Membrane Google Group or send an email to membrane@predic8.com.

Membrane Service Proxy can be used to authorize HTTP requests based on the RFC 6749 OAuth 2.0 Authorization Framework.

To use the exact terms, Membrane Service Proxy can act as a authorization proxy to the resource server. (Skip ahead to the description of the workflow to check out the architecture overview graphic.)

This tutorial consists of two sections:

  1. Setup Google as Authorization Server
  2. Perform a sample OAuth2 request authorization.

This tutorial takes about 10 minutes to complete. A Google account, internet connection and Membrane Service Proxy 4.0.7 or higher is required.

1. Setup Google as Authorization Server

Step 1: Open the Google API console

Go to https://console.developers.google.com/start and login to your Google account, if necessary. You are now in the developer console

Step 2: Creating a project

Click on Enable and manage APIs in the blue box in the middle.

A new window for project creation will open. Fill in a project name for example My Secret Resource.

Now wait for projection creation, this can take a bit.

Following the project creation a menu will appear on the left side. Here click on Credentials and following that click on OAuth consent screen.

Choose a product name, for example My Secret Resource.

The product name will be shown to users together with the question "Do you want to share your email address and identifying information with this app?"

It should inspire trust for the user to answer "Yes".

Enter the Membrane's public URL as the Home Page URL.

The public URL is the URL your users will be using to access Membrane (or, to be more specific, the secret resource via Membrane). In our case, we used http://localhost:8080/. For production use, one might use a publicly registered domain name. This means that only users accessing Membrane from the same host as Membrane is running on will be able to seamlessly login. (Note that other users might still be able to login via manual URL manipulation.)

Click on Save

Creating an OAuth 2.0 Client ID

Click on Credentials in the top navigation bar and then on New credentials in the new window followed by OAuth client ID.

Choose Web application as the application type. Type in the name for this client, then public URL of membrane in Authorized JavaScript origins and then callback URL in Authorized redirect URIs. The callback URL is the public URL with a callback path: http://localhost:8080/oauth2callback.

Click on Create. Another window with your client id and client secret will open

Leave this browser tab open, as we later need the first part of the Client ID (without .apps.googleusercontent.com) and the Client secret for Membrane's configuration.

Step 3: Configure Membrane Service Proxy

Download the Membrane Service Proxy distribution version 4.0.7 or above.

Extract the .zip archive and go to the /examples/authorization/oauth2/google directory.

Open Membrane's configuration file, proxies.xml, for editing.

The <router>...</router> element has got following configuration:

    <serviceProxy port="8080">
    		
      <headerFilter>
        <exclude>X-Authenticated-Email</exclude>
      </headerFilter>
		<!-- this is for browsers that request a favicon. The request is dropped because it would change the session id -->
		<if test="exc.getRequestURI().endsWith('favicon.ico')">
			<groovy>
				Response.notFound().build()
			</groovy>
		</if>
    		
      <oauth2Resource loginLocation="dialog" publicURL="http://localhost:8080/">
        <google clientId="805666043677-j57t71jqppa2ps2gifsoaug2bm540vqk" clientSecret="vMwoiK1df5oQGm510LTPHj2j" />
      </oauth2Resource>
    		
      <groovy>
    			def email = exc.request.header.getFirstValue("X-Authenticated-Email")
    			exc.response = Response.ok("Hello " + email + ".").build()
    			RETURN
	  </groovy>
    		
			<!--
			Use the <target> instead of the <groovy> interceptor to forward requests to another host:
			
			<target host="membrane-soa.org" port="80" />    
			 -->
    </serviceProxy>
Listing 1: Sample oauth2 Configuration

Replace the clientId and clientSecret by the ones from your Google API Project.

Step 4: Start Membrane Service Proxy

Go back to your file explorer to the /examples/authorization/oauth2/google directory of Membrane.

Start Membrane by double clicking service-proxy.bat.

The console shows Membrane's log messages.

As configured, Membrane is now listening on port 8080 for incoming HTTP connections. In the next section, we will connect to it using a browser and follow the OAuth2 steps to access our simulated "secret resource".

2. Perform a sample OAuth2 request authorization

As the full OAuth2 workflow is quite complex, we only describe a relevant subset in this tutorial.

Step 5: Try to access the "secret resource"

Keep Membrane running (the console open).

Open a browser and go to http://localhost:8080/.

Click on here.

Click on Accept to allow Membrane to retrieve your email address.

Congratulations, you have successfully completed an OAuth2 authorization setup.

Enjoy the simulated "secret resource", a personalized "hello" message from Membrane. ;)

Notes

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.

Closing Comments

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

As the communication between the OAuth2 authorization server (Google) and the resource server (Membrane and the secret resource) is not covered by the OAuth2 specification, this is Google-specific.

But as Membrane's oauth2 feature is modular in its source code design, it is easy to implement additional adapters connecting to other authorization services: For example, Amazon, Dropbox, Facebook, GitHub, Microsoft and Twitter all support OAuth 2.

Please let us know, if you run into any problems.

Copyright © 2008-2015 predic8 GmbH
Moltkestr. 40, 53173 Bonn, Tel. +49 (228) 555 25 76-0