Using Google OAUTH with MAF
May 25, 2015
To use Google OAuth inside the MAF app you will require:
- setting up a project on the Google developer console
- configuring an API key for web applications
- configuring MAF to point to the OAuth service
Step 1. Create Project
The assumption here is that you have a registered account for Google Developer Console. If not, then see https://www.gmail.com/intl/en/mail/help/about.html for instructions on what is required.
Log into the Developer Console and navigate to https://console.developers.google.com/project. This will display a list of your current projects. We’ll use Create Project to generate a new one dedicated to our OAuth authentication. If your app will use other features, such as Google Maps, then you can also configure those APIs inside this project.
Creating a new project will ask for Project Name and will allocate a random project id (this is Google’s internal UNID for your project). Advanced options allows you to choose your Data Center for App Engine components, however we are not using those, so we’ll ignore and accept the basics.
Creation can take a couple of seconds but once the project has been created the Overview page is shown.
There are a couple of things we need to now do. When a user goes to log in, they will need to be presented with a screen detailing what information is being requested and by whom. We also have to configure the API key for the app to securely use. This requires configuring a Consent screen and then setting up the key.
Step 2. Configure Consent Screen
The Consent screen is located under APIs & auth as shown below.
There are various details that need to be provided and which will be shown in the same structure as provided in the example (as copied below).
The actual items being requested under 'Project Name would like to:' will be based on the scopes you enter (which will be covered off later in this blog post).
For our sample we’ll choose the default ‘Choose your email’ option and enter the following
|Product Name||Rubicon Red OAUTH Demo|
|Homepage URL||Leave empty|
|Product Logo||Needs to be a URL to an image available on the web and that is square. Let’s put https://pbs.twimg.com/profile_images/586105964/RR_twitter_400x400.PNG|
Hit Save and the Consent screen is generated.
Step 3. Create API Credentials
Our authentication requirement is to log into the MAF app using a Google account. For this to work requires setting up some configuration that tells Google who is requesting permissions. To do this we need to define a Client ID that the MAF app will use to connect to Google and request authentication.
Under APIs & auth – select the Credential screen to display a list of all configured credentials.
We need to create an OAuth client id for authentication. Select ‘Create new Client ID’ and this will display a list of the different types of credentials we can create – Web Application, Service account or Installed application. The trick here is to remember that MAF runs as a layer above the Android and iOS operating systems. To all intents and purposes it actually runs and appears as a web application [The same rule applies when configuring Google Maps]. The default dialog box is shown below.
Selecting ‘Create Client ID’ will then generate the required configuration to use OAuth, with an example shown below.
Note: These details should not be shared outside of your organisation as they allow someone to represent themselves as being ‘your company’. I have shown these here only because the project has been deleted and authentication will no longer work.
And that’s it for the Google side of things. We have configured an OAuth provider that we can now use within the app to handle authentication. The next step is to define security within the MAF app.
Step 4. Create MAF Project
We’re going to set up an app that has two pages – a default welcome screen and then a page that is secured with our Google Authentication. Step through the new MAF app Wizard – I have called my app OAuthTest and given it an application prefix of com.rubiconred.test.googleauth. Now let’s create two features, one called welcome and one called securedfeature, and then define each as being a simple .amx page with the same name.
Tick the enable security on the securedfeature – we’ll configure this later.
Edit the pages to set the header title, so that it is clear which page you are on when in the app.
secured feature page
Step 5. Configure Security
Now we need to configure the application and security settings. Open up maf-application.xml as this is where the settings are changed. Select Security from the left hand menu and this will display the security configuration. For this sample, the defaults are ok to leave as-is for the login page, etc. Notice that under Authentication and Access Control the feature we previously ticked is shown with <application login server>.
What we need to now do is to add a login configuration – so click the + sign next to the application/ configuration login server entry.
This will display the Create MAF Login Connection wizard which allows various security options to be configured.
Select OAuth and the set the Connection Name to GoogleOAuth .
Select the OAuth tab and this will display the fields required to configure OAuth.
See 29 Securing MAF Applications for a more detailed description around Authorization Code vs. Resource Owner Credentials and the required fields. Essentially we need to use Authorization Code as we are trying to log in as an intermediary - i.e. the user will access google to authenticate and google will tell us this is OK and return us a token.
The remaining fields need to be set according to the details provided during the Google Client ID configuration earlier.
|Client Id||Copy from the google project Client ID for the web application.||728124431009-5l9rqpigm25t82amt521bl60t706g0qe.apps.googleusercontent.com|
|Client Secret||Copy from the google project Client ID for the web application||1r5pfimWlHYXlx1a0BjuFZNi|
|Redirect Endpoint||This needs to match the value you configured in your project earlier. If this does not match then Google will return an error.||https://localhost/oauth2callback|
|Logout URL||Google doesn’t seem to support the concept of logout for OAuth. However a value needs to be provided as it is mandatory (even though the dialog box indicates it isn't).||https://accounts.google.com/o/oauth2/auth|
As we are not trying to do a single sign on across multiple apps or websites we can tick the Enabled Embedded Browser Mode setting. This makes the experience a bit ‘cleaner’ as the login screen appears in the app (similar to embedded web pages). The final set up is shown below.
We are only doing a login but you need to configure a minimal option as Google requires scopes to be requested. If you don’t provide a value then you’ll receive an error 400 – Missing required parameter: scope. https://developers.google.com/+/api/oauth#login-scopes contains details about standard scopes that are supported on login.
The basic login scope is https://www.googleapis.com/auth/plus.login, which can also be entered in the OpenID Connect standard format of profile . It is worth reading up on these to see what options and data becomes available according to the scope used. For our login example we’ll usehttps://www.googleapis.com/auth/userinfo.email.
Finally switch the securedfeature to use this newly configured security.
Ideally this should be changed to reflect your application package name. For our example we will switch the value to com.rubiconred.test.googleoauth.
Step 6. Test
OK. At this point we are done - Google has been configured, along with the app. Deploy and launch the app and this will show the Welcome Page by default.
Select securedfeature in the bottom menu and the login page will appear.
Notice from the URL bar that this page is served up by Google and it is not the standard login page that is defined as part of the app. This cannot be edited or changed and there is no option to disable the browser bar either. If you successfully login with a Google Account, then the authorization page will be shown to acknowledge acceptance of sharing information.
[The details requested here are as a result of using a scope set to https://www.googleapis.com/auth/userinfo.email].
Click 'Accept' and you will then be successfully logged in, as shown below.
Interestingly if you close the app and launch again, the login screen changes to ask whether you wish to allow ‘Have Offline Access’. There is no need to type the username and password in again. This seems to vary depending on what scope you have requested. For example, if the scope of email is used (a newer scope to the deprecated https://www.googleapis.com/auth/userinfo.email) then the credentials are not stored and you have to provide username and password each time.
This blog has taken you through how to configure a MAF application to use Google OAuth for authentication. It stepped you through the configuration required on Google and highlighted the settings you need to consider for it all to work correctly. Potential next steps would be to then use the returned token to access data (and perform actions as the user) on any of the Google Apps they have available.