Getting Started with AeroGear Mobile Services

Introduction

AeroGear Mobile Services provides solutions to common development challenges faced by mobile developers. With OpenShift’s Container technology providing a secure, scalable backend platform, mobile developers can use the AeroGear SDK which supports a range of native (iOS & Android) and hybrid (Xamarin & Cordova) platforms to create secure, high quality apps and makes it easy to add features such as Push Notifications or Authentication.

Mobile Apps in OpenShift allow you to perform Cloud Native Mobile App Development using OpenShift as the back-end for your mobile apps. A Mobile App is a representation of the mobile app that you are developing locally. Mobile Apps allow you to bind your mobile app to mobile services such as Identity Management, Push Notifications, Mobile Metrics and others. This makes many of the common tasks associated with mobile development much easier and quicker to implement.

A configuration file named mobile-services.json acts as the link between your Mobile App in OpenShift and your local app in development. This configuration file is used to initialize the AeroGear SDK in your mobile app and to connect to the back-end Mobile Services you have provisioned on OpenShift.

Mobile Developer Console is part of AeroGear Mobile Services and allows you to:

  • create representation of your mobile application in OpenShift

  • bind Mobile App with mobile services

  • build your mobile app (requires Mobile CI/CD service)

  • get mobile-services.json configuration file for AeroGear SDK

AeroGear Mobile Services is currently in a development phase. This makes it unsuitable for production deployment. Use this community release as an evaluation environment for developing and deploying mobile applications on Openshift.

This guide shows you how to:

  • Set up AeroGear Mobile Services on OpenShift

  • Create a Mobile App and a Mobile Service (Identity Management)

  • Set up a local development environment

  • Configure the AeroGear showcase app for your mobile platform (Android, iOS, Cordova or Xamarin).

  • Run the showcase app and make calls to the Identity Management service.

Setting up AeroGear Mobile Services on OpenShift

Mobile Services run natively on OpenShift. The installation script in the following steps installs Mobile Services on OpenShift.

Prerequisites

  • OpenShift 3.11 instance

    • This instance must have Service Catalog, Ansible Service Broker and Template Service Broker services installed.

    • You need to have full access to this OpenShift instance, i.e. user with cluster-admin privileges.

      If you don’t have OpenShift instance you can use oc cluster up or Minishift to setup OpenShift locally.
  • OpenShift client tools version 3.11

  • Docker

  • A local mobile development environment for the platform you want to develop on.

Procedure

  1. Clone the Mobile Developer Console repository:

    The repository contains installation script for AeroGear Mobile Services.

    Clone this repo to your local machine and check out the 1.0.0 tag using:

    git clone https://github.com/aerogear/mobile-developer-console.git
    cd mobile-developer-console
    git checkout 1.0.0
  2. Login to your OpenShift instance as user with cluster-admin privileges:

    $ oc login <OPENSHIFT_MASTER_URL>
  3. Change directory SELinux security context (RHEL/Fedora):

    This step is only required on RHEL/Fedora with SELinux enabled.
    $ chcon -Rt svirt_sandbox_file_t .
  4. In the same directory, run the installer:

    $ ./scripts/post_install.sh
  5. Verify the installation:

    1. Browse to the Web console of your OpenShift instance and log in.

    2. Check that the Mobile tab is displayed in the service catalog. If this tab is not displayed, wait a few minutes to make sure that the installation process has completed.

Additional resources

Local OpenShift setup

You can run OpenShift locally on your machine. There are two scripts in Mobile Developer Console repository which will create the cluster using Minishift or oc cluster up, and enable AeroGear Mobile Services.

On Mac only Minishift is currently supported.

Prerequisites

Minishift
oc cluster up
  • Linux

  • OpenShift client tools version 3.11

  • Docker

  • Firewall configured:

    firewall-cmd --permanent --add-port=8443/tcp
    firewall-cmd --permanent --add-port=8053/tcp
    firewall-cmd --permanent --add-port=53/udp
    firewall-cmd --permanent --add-port=443/tcp
    firewall-cmd --permanent --add-port=80/tcp
    firewall-cmd --reload

Procedure

  1. Clone the Mobile Developer Console repository:

    git clone https://github.com/aerogear/mobile-developer-console.git
    cd mobile-developer-console
    git checkout 1.0.0
  2. Run the installation script:

    Minishift
    $ ./scripts/minishift.sh
    oc cluster up
    $ ./scripts/oc-cluster-up.sh
  3. Copy cluster self-signed certificate:

    When the script finishes it will save OpenShift’s self-signed certificate to /tmp/oc-certs/localcluster.crt. Copy this file so you can later install it to your mobile device.

    This is needed so that your mobile app can communicate with OpenShift.

  4. Browse to the Web console of your local OpenShift instance, accept self-signed certificate and log in.

    You can get OpenShift URL with:

    $ oc status
    Browser may redirect you to localhost. If that happens just enter the URL again and make sure to add /console at the end.

Provisioning Mobile Developer Console

To provision the Mobile Developer Console:

  1. Log into the OpenShift console.

  2. Create a new project or choose an existing project.

  3. Select Catalog from the left hand menu.

    You can filter the catalog items to only show mobile specific items by selecting the Mobile tab.
  4. Choose the Mobile Developer Console service.

  5. Follow the wizard for provisioning that service.

    If prompted to Create a Binding, choose Do not bind at this time.

Once the wizard steps are completed, navigate to the Project Overview in OpenShift to see the newly provisioned service. Provisioning a service may take some time.

Registering a Mobile App

After provisioning Mobile Developer Console, the next step is to register a Mobile App for the mobile application that you are going to develop.

Procedure

To create a Mobile App:

  1. Log into the OpenShift console.

  2. Choose project where you have previously deployed Mobile Developer Console.

  3. Open Mobile Developer Console by clicking on its route in Overview screen.

  4. Log into the Mobile Developer Console.

  5. Click on Create Mobile App button.

  6. Enter name of your mobile application.

  7. Click Create button.

Provisioning your First Service

Mobile Services provide commonly required features for mobile app development.

This section introduces the procedures for using Mobile Services by guiding you through the process using the Identity Management service. For a full list of available services, see Mobile Services

To provision the Identity Management mobile service:

  1. Log into the OpenShift console.

  2. Choose a project where you have previously provisioned Mobile Developer Console.

  3. Select Catalog from the left hand menu.

    You can filter the catalog items to only show mobile specific items by selecting the Mobile tab.

  4. Choose the Identity Management service.

  5. Follow the wizard for provisioning that service.

    If prompted to Create a Binding, choose Do not bind at this time.
When completing the Identity Management provisioning wizard, you are prompted to enter configuration data. For the purposes of this guide, keep the default values. For more information about the Identity Management provisioning wizard fields, see Identity Management Configuration.

Once the wizard steps are completed, navigate to the Project Overview in OpenShift to see the newly provisioned service. Provisioning a service may take some time.

Additional resources

Identity Management Configuration

  • Keycloak admin username: Username for Keycloak administration

  • Keycloak admin password: Password for the Keycloak admin user

  • Name of the Keycloak realm: Name of the keycloak realm. (defaults to current namespace)

A realm manages a set of users, credentials, roles, and groups. A user belongs to and logs into a realm. Realms are isolated from one another and can only manage and authenticate the users that they control.
  • Connect to an existing shared service: Select if you want to use an existing service and you have the URL and credentials to use that service.

  • URL of the shared service: Enter a value if you want to use an existing shared service.

Binding a Mobile App with the Identity Management Service

To use mobile services, you must represent your mobile app in OpenShift using a Mobile App, and that Mobile App must be associated with the mobile service. This association is called binding and it is necessary for your mobile app to use that service.

To bind a Mobile App with a mobile service:

Procedure

  1. Navigate to the Overview of your OpenShift project.

  2. Select the Mobile App name listed in the Mobile Apps section.

  3. Navigate to Mobile Services tab.

    mobile clients services all unbound
  4. Click Create Binding and follow the Create Binding wizard to associate the Mobile App with the Identity Management Service.

  5. Fill out the binding parameters required by the Identity Management Service.

    Use public when binding a Mobile App to a Identity Management. When binding mobile services to each other, use bearer.

The Identity Management service will now be expandable, details about the service can be viewed.

mobile clients services all idm provisioned

Configuring the Service

The following section will guide you through configuring the schema of the redirect url and web origin for a client in Keycloak. This is required to enable OpenID authentication. For an explanation of these terms, see Keycloak Documentation.

Choose the schema of a redirect url

Android

It is recommended to use the package name of the Android app as the schema of the redirect url to avoid conflicts. (e.g. com.aerogear.androidshowcase)

iOS

It is recommended to use the Bundle Identifier of the iOS app as the schema of the redirect url. (e.g. org.aerogear.ios-showcase-template)

Cordova

Redirect url is http://localhost/*, without :/callback. Web Origin is http://localhost/*.

Xamarin

Depending on the platform, set the redirect as described in either the Android or the iOS tab.

Configuring Keycloak

  1. Log into the OpenShift console and navigate to the Project Overview.

  2. Navigate to the Mobile App screen.

  3. Select the Mobile Services tab.

  4. If a binding to the Identity Management service is in progress, a spinning icon is displayed to the right of the Identity Management entry. Wait for the binding process to complete.

  5. If the Keycloak Realm URL URL is not visible, expand the Identity Management Service by clicking the > icon.

  6. Click on the Keycloak Realm URL link to open the Keycloak Administration Console.

  7. Log in to the Administration console using the credentials you specified when Provisioning the service (defaults to admin:admin).

  8. Select Clients from the left navigation menu.

  9. Select your client from the list of clients. The name of your client is derived from the name of the Mobile App, the name of the mobile development platform and the client type, for example myapp-android-public.

  10. Add <schema>:/callback as an additional entry to Valid Redirect URIs. See Choose the schema of a redirect url to determine the value for <schema>.

  11. Add <schema> as an additional entry to Web Origins. See Choose the schema of a redirect url to determine the value for <schema>.

  12. Save your changes.

  13. Create a new user account as described in Creating a New User.

  14. Set up credentials for the new user as described in User Credentials.

Setting Up your Local Development Environment

Supported Environments

In order to perform local development, you will need to have set up a local development environment or IDE. Mobile Services supports mobile app development across iOS Native, Android Native, Cordova and Xamarin.

You can only use the AeroGear Xamarin SDK to create iOS and Android Apps.
Android

You need the following installed on your machine:

  • Android SDK or Android Studio from Google

  • (Recommended) The latest version of OpenJDK

For information on how to set up a local Android development environment, see the Android Studio documentation.

iOS

You need the following installed on your machine:

The AeroGear SDK for iOS is available using the CocoaPods package manager. If you have not installed CocoaPods, install it by running the command:

$ gem install cocoapods

For information on how to set up a local iOS development environment, see the Swift documentation.

Cordova

You need the following installed on your machine:

For information on how to set up a local Cordova development environment, see the Cordova documentation.

Xamarin

You need the following installed on your system:

  • Visual Studio Tools for Xamarin from Microsoft

  • (Optional) The latest version of OpenJDK, if you would like to install the showcase app on an Android device or emulator

  • (Optional) The latest version of XCode and command line tools for XCode available from Apple, if you would like to install the showcase app on an iOS device or emulator

For information on how to set up a local Xamarin development environment, see the Xamarin documentation.

Running your First Mobile App

Cloning the Showcase App

Android
$ git clone https://github.com/aerogear/android-showcase-template.git
$ cd android-showcase-template
$ git checkout 1.0.0
iOS
$ git clone https://github.com/aerogear/ios-showcase-template.git
$ cd ios-showcase-template
$ git checkout 1.0.0
Cordova
$ git clone https://github.com/aerogear/cordova-showcase-template.git
$ cd cordova-showcase-template
$ git checkout 1.0.0
Xamarin
$ git clone https://github.com/aerogear/xamarin-showcase-template.git
$ cd xamarin-showcase-template
$ git checkout 1.0.0

Downloading the Mobile Services Configuration File

  1. Open your Mobile App in Mobile Developer Console.

  2. Copy the mobile-services.json configuration to your clipboard.

  3. Save the contents of the clipboard to a new file called mobile-services.json.

    The mobile-services.json file is the link between your provisioned services on OpenShift and the mobile app you are developing. This file provides all required configuration to initialise the various SDKs and get them hooked up/connected to the back-end services.
  4. Follow the platform-specific instructions:

Android

Move mobile-services.json to the following location in your application project:

app/src/main/assets/mobile-services.json

iOS

Move mobile-services.json to the following location in your application project:

<app directory>/mobile-services.json

Ensure that mobile-services.json is a member of the project in the Xcode Project Navigator.
Cordova

Move mobile-services.json to the following location in your application project:

src/mobile-services.json

Xamarin

Move mobile-services.json to the following location in your application project:

Resources/mobile-services.json

Building the app

Android
$ ./gradlew assembleDebug
iOS

Run this command to install dependencies:

  1. Install CocoaPods as described in https://cocoapods.org/ if it is not already installed.

  2. Run this command to install dependencies:

    $ pod install
Cordova
$ npm install
$ npm run ionic:build
Xamarin

Run this command to install dependencies (optional):

$ nuget restore

Using Self-Signed Certificates in Mobile Apps

Before you can run a mobile app and connect to Mobile Services, you must configure self-signed certificates on the mobile device.

Throughout the development lifecycle of a mobile app, a common requirement is to integrate and connect with back-end services in a secure manner. This is achieved using SSL/TLS.

However, in order for the client device to connect over SSL/TLS, it needs to trust the certificates used by the back-end services, which are signed by a certificate authority. Most client devices have a list of well-known and trusted certificate authorities pre-installed and this allows the client devices to verify the certificates used by the back-end services.

However, this normally doesn’t work in a development environment, such as a local OpenShift cluster as it uses self-signed certificates which are not signed by any of the trusted certificate authorties. This means by default the client devices won’t be able to establish secure connections with the back-end services that are running on a local OpenShift cluster.

To work around the problem, you must manually extract the root certificate from the cluster, install it on the device and mark it as trusted.

1. Extracting the OpenShift Root Certificate Authority Cert

  1. Log into OpenShift as the admin user:

    $ oc login -u system:admin
  2. Run the following command:

    $ oc get secret router-certs --template='{{index .data "tls.crt"}}' -n default  |  \
    base64 --decode | sed -e '1,/^-----END RSA PRIVATE KEY-----$/ d'  > /tmp/localcluster.crt

    The resulting file is located in the /tmp directory.

2. Installing the OpenShift Root Certificate Authority Cert on a Device

Android
  1. Set screen lock on the mobile device to ensure the certificate can be installed.

  2. Copy the file to your device using one of the following methods:

    • Email attachment (Recommended) - Simply email the certificate to an address accessible from the device and download the attachment.

    • Cloud service - Use a cloud storage service such as Dropbox or Google Drive which is accessible from the device, browse to the certificate and proceed to download it.

    • USB - Attach the device to the machine hosting OpenShift via USB and drag the certificate to a devices file system. Here is an example guide for Google Nexus devices. It may be different for other devices.

    • Android Debug Bridge (adb) - Use the adb push command to push the certificate to device or emulator:

      $ adb push /tmp/localcluster.crt /sdcard/Download/localcluster.crt
  3. Add the certificate to your device:

    If you are using the email or cloud service approach, once the certificate file is downloaded, you will be prompted by the Android system automatically to install the file. You can simply follow the instructions to complete the process.

    However, if you are using the USB approach, you will need to install the certificate manually: go to Settings > Security > Install from storage, tap on the copied certificate file and Android system should detect the certificate and let you add it to the device. Here is a sample guide for Google Nexus devices.

iOS
  1. Enable Passcode or TouchID protection on the mobile device to ensure the certificate can be installed.

  2. Copy the file to your device using one of the following methods:

    • Email attachment (Recommended) - Simply email the certificate to an address accessible from the device and download the attachment.

    • Cloud service - Use a cloud storage service such as Dropbox or Google Drive which is accessible from the device, browse to the certificate and proceed to download it.

  3. Add the certificate to your device:

    When you download the certificate, the device should automatically detect a profile. Simply follow the on screen instructions to install it.

    Versions iOS 10.3 and later require an additional step to trust the now installed certificate. Instructions can be found on the Apple support site

Running the app in an emulator

Android

To run an Android app in an emulator, see the following documentation.

The AeroGear SDK supports API level 21 or later.
iOS

To run an iOS app in an emulator, see the following documentation.

Cordova

Cordova cross-platform applications can be run in the following emulators:

  • Android

  • iOS

    A running emulator on macOS is required to run an iOS application.
Xamarin

Xamarin cross-platform applications are run in the following emulators:

  • Android

  • iOS

    A running emulator on macOS is required to run an iOS application.

From the showcase app:

  1. Press the Authenticate menu item. A login screen is displayed.

  2. Log in using the credentials you set up with setting up the service.

    Once the login is successful, you will be taken back to the showcase application where you can see the roles and basic information of the user you have just logged in with.