Open Authentication Module

Name	Open Authentication Module
Author	Erwin 't Hoen
Company	FlowFabric
Type	Module
Latest version	1.4
Package name	OAuthModule_v1.4.mpk
Released	10-09-2020

##Description

The Open Authentication Module allows you to setup your app for authenticating users with their Google, Microsoft Azure, Linkedin or Facebook account. The module can easily be expanded to incorporate any OAuth 2 provider.

##What is OAuth?

OAuth 2 is an open standard to authorization. OAuth provides client applications a 'secure delegated access' to server resoources on behalf of a resource owner. It specifies a process for resource owners to authorize thrid-party access to their server resources without sharing their credentials. Designed specifically to work with HTTP, OAuth essentially allows access tokens to be issued to third-party clients by an end-user. The client then uses the access token to access the protected resources hosted by the resource server. OAuth is commonly used as a way for web surfers to log into third party web sites using their Google, Facebook or Twitter accounts, without worrying about their access credentials being comprimized.

##Services that support OAuth 2

- 37signals (draft 5) - Box - Beeminder - Campaign Monitor - DailyMotion - Do.com (draft 22) - Dropbox - Facebook (see here) - Foursquare - Geologi

- Github - Google - Linkedin - Mailchimp - Meetup - Nationbuilder - Paypal - Reddit - Salesforce - Scoop.it

- Sharefile Citrix - StockTwits - Soundcloud - Vimeo - Windows Live - WePay - Wordpress - Yahoo - Yammer

*For a complete list see here*

Typical usage scenario

If you want to have your users login to their Mendix app with their credentials from their favorite social network, Microsoft Azure account or cloud app. For example when using Chrome the user already logs in automatically into their Google account, then the Oauth module will allow the user to be logged in directly into their Mendix app (SSO).

If you need 2-factor authentication for accessing your app, then make use of the options that Google offers for this purpose in stead of build 2-factor authentication from scratch in your Mendix app.
Using a corporate Google account, users can be setup so that the login process will require 2-factor authentication. This is how you set this up on Google

Features and limitations

Authenticate users via Azure, Facebook, Google or Linkedin OOTB

Or use only one of these providers (pick and choose)

Use 2-factor authentication provided by the OAuth providers

Style your own fault pages

Logging for all access attempts

CSRF protection

English and Dutch supported

Easily add your own OAuth 2 provider

Determine how you identify your authorized users based on the data provided by the OAuth provider
   (OOTB this is done based on the email address)

Implement your own logic for authentication of users even add user provisioning with a simple microflow

If you do not implement user provisioning then the users have to be known in the app by integration to an    Active Directory or an Identity Management solution

Control if an Admin can login via the standard Mendix login circumventing the OAuth login via adaptation in    your theme directory

Javadoc for custom code provided in the custom directory

Installation & Configuration

1. Download the zip file from Github

2. Extract the zip

3. Import the module (.mpk) into you application as a new module

4. From the resources/Oauth directory copy all the files to your theme directory

5. Connect the page and microflow from the #Implementation folder to your navigation Assign the permissions to the userrole(s)

6. Import the Community Commons module from the app store if not already part of your project

7. Import the Model Reflection module from the app store if not already part of your project

8. Set the microflow AS_StartOAuthRequestHandlers as After Startup Microflow

9. Add the attribute Email to the Administration.Account entity and pages

10. Register your app with the OAuth provider, make sure that the callback URL is https://(yourapp)/callback/(OAuth_provider) For Google e.g. http://myfirstapp.mendixcloud.com/callback/google

11. Update the constants ClientId_(OAuth provider) and ClientSecret_(OAuth provider)

12. The next setup step for your OAuth module is: navigate to https://(yourapp)/login-without-sso.html and login with your Admin account

13. Synchronize your Model Reflection module and make sure that the data for the OAuthModule is created

14. Select the OAuth Config menu item and select the microflow ResolveUserByEmail

15. To allow your user to return to a logout page, implement the sign out button as found in the #implementation Oauth_Layout

16. Don't forget to set your requesthandlers in the cloud ('signin/','callback/' and 'logout/')

17. And you're done!

18. Wait, what if security requirements are more strict? Perform step 17

19. Delete the login-without-sso.html from your theme folder to make sure that OAuth is the only login option, and redeploy your app

20. Done!

If you want to use another OAuth provider than those that come with the module read the Add_OAuth_Provider_v1.2.pdf file on github. To implement your own resolve user logic either adapt the microflow ResolveUserByEmail or create your own microflow and link this in the OAuth config.

Dependencies

1. Mendix 8.5.0 environment
2. Mx Model Reflection module
3. Community Commons module
4. guava-27.0-jre.jar
5. jackson-annotations-2.9.5.jar
6. jackson-core-2.9.5.jar
7. jackson-databind-2.9.5.jar
8. java-jwt-3.1.0.jar
9. json-simple.jar
10. org.apache.commons.lang3.jar
11. org.apache.httpcomponents.httpclient_4.3.5.jar

Known bugs

• None so far

Frequently Asked Questions

Ask your question at the Mendix Community Forum

• None