OAuth2 Tutorial: Google as Authentication Service for Web Applications
In this tutorial we will see how to communicate with Googles authorization server using Membrane Service Proxy to authorize HTTP requests based on the RFC 6749 OAuth 2.0 Authorization Framework, OpenID Connect Core and OpenID Connect Discovery .
This tutorial explains:
- Setup Google as Authorization Server
- Setup Membrane as Client
- Perform a sample OAuth2 request authorization.
You will need about 10 minutes to complete. A Google account, internet connection and Membrane Service Proxy 4.2.1 or higher is required.
1. Setup Google as Authorization Server
Step 1: Open the Google API Console
Step 2: Creating a Project
Click on Select a project and then on Create a project... in the top right corner.
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 then 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 use to access Membrane (or, to be more specific, the secret resource via Membrane). In our case, we use http://localhost:8080/. For production use, one might use a publicly registered domain name.
Click on Save.
Creating an OAuth 2.0 Client ID
Click on Credentials in the top navigation bar. Then click on New credentials in the new window followed by a click on OAuth client ID.
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
Install and download Membrane Service Proxy version 4.2.1 or above.
Go to the $MEMBRANE_HOME/examples/oauth2/google directory.
Open the proxies.xml for editing.
The <router>...</router> element has the following configuration:
<serviceProxy port="8080"> <headerFilter> <exclude>X-Authenticated-Email</exclude> </headerFilter> <oauth2Resource publicURL="http://localhost:8080/"> <google clientId="Enter client ID from Google here" clientSecret="Enter client Secret from Google here" /> </oauth2Resource> <!-- this will act as the secret resource to make the example simple. See below in the comments for an alternative --> <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>
Replace the clientId and clientSecret by the ones from your Google API Project.
Step 4: Start Membrane Service Proxy
Go back to the $MEMBRANE_HOME/examples/authorization/oauth2/google directory.
Start Membrane by running service-proxy.bat/.sh.
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"
Open a browser and go to http://localhost:8080/.
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. ;)
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.
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’s administrator should install SSL certificates and adjust the proxies.xml to use them for all HTTP exchanges that need to be secured.
- Membrane Service Proxy automatically takes care of using HTTPS for the HTTP exchanges 3, 4, 6 and 7.
- If potential users can connect via the open internet (or via any untrusted intermediary), use SSL for HTTP exchanges 1, 2, 5 and 10.
- Unless the network connection between Membrane Service Proxy and the web server hosting the secret resource is safe, use SSL for HTTP exchanges 8 and 9.
- 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.