AAI for Mobile Apps

Please note that the information on this page is outdated in some areas and that the content on this page was created in 2013 only for a proof-of-concept, which has not been developed further due to low interest from the community. SWITCH is not running and currently has no plans to run a Mobile Proxy. Instead, we plan to support OAuth/OpenID Connect via the SWITCH edu-ID service.

Introduction

AAI was designed as a webbrowser based protocol. This makes it difficult to use AAI authentication for non-web browser based protocols. With the increasing usage of smart phones at universities there arises the need to use AAI authentication also for such mobile applications. However, mobile applications often are non-web browser applications and they are also different compared to web applications in other ways (like login/logout). To make use of AAI, mobile applications could emulate a web browser and ask the user for his university login name and password. However, depending on who created the app this might not be secure nor might the app be easy to maintain because it has to emuldate a web browser and parse AAI login pages to perform the AAI login. Therefore, the use of AAI in the context a mobile apps is generally non-trivial.

On this page we demonstrate and offer for download a prototype of a sample application that uses AAI authentication without emulating a web browser. A web browser is still needed, but only for initial authentication normally.

The architecture of this prototype consists of the following components:

Architecture
  • AAI Identity Provider(s): Regular Shibboleth Identity Providers configured according to the deployment guides for SWITCHaai.
  • Mobile Proxy: A small PHP application that is protected by a Shibboleth Service Provider. Includes an OAuth2 authentication service.
  • Smartphone app: App that provides services to users, who are authenticated with AAI.
  • Resource server (Optional): Custom service that provides additional data to the app, secured with OAuth2

The example Uni App was implemented for Android, but it should be very simple to create a version that works on other mobile operating systems too.

The example resource server is written in PHP, but can be implemented in any language as long as the authentication server is called to validate the login.

Features

  • Authenticate users with AAI using a web browser on the mobile phone
  • Users can also authenticate using a computer's with any web browser. Useful if login is difficult to complete on the mobile phone itself or if authentication methods other than username/password are used on AAI Identity Provider. User has to enter a token or take a picture of a QR code to login in the app.
  • AAI attributes are always updated on app start without involving a web browser or forcing the user to log in again via AAI
  • Administration of all active login sessions/devices through the browser
  • Data on Resource service is secured with OAuth2, a widely adapted standard

Requirements

The prototype has the following system requirements

Server(s)
Client
  • Android 2.2+

Demonstration

These are the steps to use the demo app with AAI login:

  1. The user downloads and installs the app
  2. On the first app start, the user has to log in using one of 2 methods
  3. A: Perform an AAI login using the phone's browser
    B: Perform a login using a computer as intermediate:
    • Open an app-specific URL on a desktop browser
    • Perform an AAI login
    • Import a login code by typing it into the phone or scanning a QR code
  4. Retrieve the user's AAI attributes from the Mobile Proxy via a REST JSON interface
  5. After retrieving the attributes, show the home screen of the app
  6. On the home screen, retrieve a timetable from a resource server using the Mobile Proxy authentication data

The above procedure is needed only when the App is installed, if the user wants to log out from the app or if the administrator of the mobile proxy administratively logs out users.

Screenshots
Login Alternative login Home Screen
login screen altlogin screen home screen
Administration page
admin page
Screencast

This screencast demonstrates the basic features and functionality the example Uni app provides.

  • Logging in using the mobile browser
  • Logging in using the web browser of a computer instead of the browser on the mobile phone
  • Logging out of the app

Developing

The source code of the mobile proxy, the sample app and the resource service is available as open source software in a frozen, unsupported .tgz archive: AAI-for-apps.tgz [Status as of 1. July 2014, 2 MBytes].

App

The mobile proxy Android app implements the basic login mechanism and is aimed to be a template for own apps. It is meant as a prototype to start an own application that makes use of AAI authentication. To start developing we recommend getting Eclipse Classic with the ADT plugin. Once it is installed, the Android SDK Platform for API level 16 needs to be installed - this can be achieved from the SDK manager that came with the ADT plugin: Window > Android SDK Manager

Alternatively, there are Android Eclipse Bundles available which should have everything preinstalled.

Once the environment is set up, import the project into Eclipse and start customizing the app. Start an Android emulatator right away to test the demo app.

Ideally it shouldn't be necessary to edit any files in the ch.SWITCH.uniapp package. Configure relevant parameters in res/values/strings.xml

Auth Server Installation
  • Make the auth-server folder accessible in a webserver.
  • Set up the database using DATABASE.sql
  • Create config.php from config.php.dist
  • Install dependencies with composer

More detailed instructions are here.

Resource Server

The process is practically the same as for the auth server. README

Media