Using Google OAUTH with MAF

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.

1. New Project.png

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.

2. Project Dashboard.png

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.

3. consent screen.png

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).

4. permissions screen.png

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

Field
Value
Product NameRubicon Red OAUTH Demo
Homepage URLLeave empty
Product LogoNeeds 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
Privacy PolicyTerms of ServiceGoogle+ PageWe’ll leave these as empty but it’s worth considering the effort to generate these if you are releasing a commercial app. They are also optional fields on the Play and Apple stores but are expected to be provided.

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.

5. credentials.png

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.

6. Create Client Id.png

There are only two fields to configure; Authorized Javascript origins and Authorized redirect URIs. This might be the point where you start to struggle and wonder what values need to be provided. For a web application it would logically be the domain name of the site and then the uri to redirect to after a successful login. However, as MAF is running as a web app in a container it isn’t obvious what these values should be….

… it actually doesn’t really seem to make much difference for the javascript origins field. The key thing we do need to ensure is that whatever is defined as the authorized redirect URI will need to match the value configured inside the MAF Security wizard.  So, for our example, let’s go with  https://rubiconred.com and a redirect uri of https://localhost/oauth2callback.  This leaves us with the values shown in the screenshot below.

7. Create Client Id Filled In.png

Selecting ‘Create Client ID’ will then generate the required configuration to use OAuth, with an example shown below.

8. Created Client Id.png

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.

9. Features.png

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.

10. Welcome.png

welcome page

11. Secured.png

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>.

12. Security.png

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.

13. MAF Oauth Wizard.png

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.

Field
Description
Value
Client IdCopy from the google project Client ID for the web application.728124431009-5l9rqpigm25t82amt521bl60t706g0qe.apps.googleusercontent.com
Client SecretCopy from the google project Client ID for the web application1r5pfimWlHYXlx1a0BjuFZNi
Authorization Endpointhttps://accounts.google.com/o/oauth2/auth
Token Endpointhttps://accounts.google.com/o/oauth2/token
Redirect EndpointThis 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 URLGoogle 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.

13ii. finalised.png

Scopes

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.

14. Switch security on.png

Unrelated topic

Note that by default the maf-application.xml will have the application id set to something like com.company.OAuthTest, as shown below.15. App Name.png

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.

16. Welcome Page.png

Select securedfeature in the bottom menu and the login page will appear.

17. Login.png

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.

18 . Permissions.png

[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.

19. secured page.png

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.

Summary

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.