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.

This guide shows you how to:

  • Set up AeroGear Mobile Services on OpenShift

  • Create a Mobile Client 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.

Make sure you satisfy all the requirements listed in the Prerequisites and that you have a mobile app development environment configured. Some experience with OpenShift administration would also be helpful.

Setting up AeroGear Mobile Services on OpenShift

To use Mobile Services, you must run OpenShift and install an add-on which enables Mobile Services. For more information about OpenShift, see OpenShift website.

AeroGear recommends running OpenShift using the method described in this document. However, there are many ways to run OpenShift, and Mobile Services is compatible with most of these methods. There is a known issue with Minishift that makes it unsuitable for mobile development. This issue is described in Issue 1287.

Prerequisites

  • MacOS or Linux

    Due to an OpenShift bug, Mobile Services will not run on RHEL/CentOS 7.4 or RHEL/CentOS 7.5.
  • A system running OpenShift oc cluster up as described in Local Cluster Management

    Installation on macOS with Docker Machine has not been tested, use the Docker for Mac instructions when installing OpenShift.
    • Use OpenShift client tools version 3.9

      OpenShift oc executable must be located in a system location that is known to all shells (e.g. /usr/local/bin)
      Ensure that you can run oc cluster up with no errors before moving on to the installation of AeroGear.
  • Access to a Docker Hub account. The installer uses Docker Hub as a source for AeroGear Docker images.

  • Ansible (version 2.6 or above)

  • For Linux (Fedora), add an extra port to the dockerc zone:

$ firewall-cmd --permanent --zone dockerc --add-port 443/tcp
$ firewall-cmd --reload
  • A local mobile development environment for the platform you want to develop on.

Procedure

  1. Clone the Mobile-core installer:

    The installer configures the local development installation of AeroGear Mobile Services using ansible scripts in our mobile-core repo.

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

    git clone https://github.com/aerogear/mobile-core.git
    cd mobile-core
    git checkout 1.0.0
  2. In the same directory, run the installer:

    $ ./installer/install.sh

    The installer checks that valid versions of Ansible, Docker and the OpenShift Client Tools are installed.

  3. Enter your Docker Hub login credentials when prompted. The installer checks these credentials are valid before continuing.

  4. Accept the default values for the next set of prompts, unless you have specific requirements and understand the implications of changing the values. For more information about these values, see the DockerHub, Cluster IP and Wildcard DNS Host values section in Additional Resources.

    If your Cluster IP address is reported as 127.0.0.1, the installation will not succeed. Check your network connection and restart the installer.
    DockerHub Tag (Defaults to latest):
    DockerHub Organisation (Defaults to aerogearcatalog):
    Cluster IP (Defaults to < Network IP Address >)
    Wildcard DNS Host (Defaults to nip.io):

    For more information, see the DockerHub, Cluster IP and Wildcard DNS Host values section in Additional resources.

    The following installation can take a while the first time it runs, as it pulls a number of Docker images. Once completed successfully, this results in an output similar to the following:

    TASK [output-oc-cluster-status : debug] ******************************************************************************************************************************************************
    ok: [localhost] => {
        "msg": [
            "Web console URL: https://192.168.37.1:8443/console/",
            "",
            "Config is at host directory /var/lib/origin/openshift.local.config",
            "Volumes are at host directory /var/lib/origin/openshift.local.volumes",
            "Persistent volumes are at host directory /var/lib/origin/openshift.local.pv",
            "Data is at host directory /path/to/mobile-core/ui/openshift-data"
        ]
    }
    
    PLAY RECAP ***********************************************************************************************************************************************************************************
    localhost                  : ok=44   changed=17   unreachable=0    failed=0

    The log above is displayed after a successful installation.

  5. Verify the installation:

    1. Browse to the Web console URL displayed at the end of the installation, and log in, accepting the self-signed certificate if displayed.

      The developer login credentials are:

      username: developer
      password: password

      The service catalog is displayed

    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. If the Mobile tab still is not displayed, follow the troubleshooting steps below.

catalog mobile clients

Additional resources

Troubleshooting

Firewall issues can occur with external devices trying to communicate with Mobile Services provisioned on a Linux machine. This is due to a number of Mobile Services using ports which are restricted to root users only. If you encounter these issues, you can add the ports to your firewall. Depending on the port your service uses, an example of the ports you may want to add to your firewall are:

The following command will only add the specified port for the current session. If you reload your firewall or restart your machine the specified port will be restricted again.
$ firewall-cmd --add-port 443/tcp
$ firewall-cmd --add-port 80/tcp

DockerHub, Cluster IP and Wildcard DNS Host values

Use DockerHub Tag and DockerHub Organisation to configure the location of the APBs used by the service-catalog in the cluster you are creating:

DockerHub Tag (Defaults to latest):
DockerHub Organisation (Defaults to aerogearcatalog):

The Cluster IP value defaults to the IP address of your primary network interface. If you want to connect to your OpenShift instance from a mobile device, ensure that your device is on the same network. Typically, you should ensure you are using the IP Address of your Wireless Adapter (if one exists):

Cluster IP (Defaults to < Network IP Address >)

The Wildcard DNS Host option alters the wildcard DNS host you want to use:

Wildcard DNS Host (Defaults to nip.io):

Registering a Mobile Client

After the setup is completed, the next thing you need to do is to register a Mobile Client for the mobile app that you are going to develop.

A Mobile Client in OpenShift is a representation of the mobile app that you are developing locally. Mobile Clients allow you to bind your mobile app to mobile services such as Identity Management, Push Notification, Mobile Metrics and others. This makes many of the common tasks associated with mobile development much easier and quicker to implement. For more information, please see Mobile Clients in OpenShift

Procedure

To create a Mobile Client in your OpenShift project:

  1. Log into the OpenShift console.

  2. Choose your project.

  3. Click Add to Project and choose Browse Catalog from the options.

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

    Available Mobile Clients

  4. Click the Apps tab and then choose the mobile platform (Android, iOS, Cordova or Xamarin) and follow the wizard.

    On the wizard’s configuration screen, it is recommended that you input the name of the showcase application into the Package Name text box.
    When registering an iOS app, you are prompted for a bundle id. See the description of bundle identifiers for more information.

After the Mobile Client is provisioned, you can navigate to it from Project Overview. The Mobile Client view displays a list of mobile services that you can associate with the Mobile Client, and offers to provision any mobile service that is in the service catalog but is not currently provisioned.

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. 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. Click Services and choose the Identity Management service.

    catalog mobile services
  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 Client

To use mobile services, you must represent your mobile app in OpenShift using a Mobile Client, and that Mobile Client 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 associate a Mobile Client with a mobile service:

Procedure

  1. Navigate to the Overview of your OpenShift project.

  2. Select the Mobile Client name listed in the Mobile Clients 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 Client with the Identity Management Service.

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

    Use public when binding a Mobile Client 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 Client 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 at Provisioning (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 Client, 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. Navigate to your project in OpenShift.

  2. On the Overview screen, expand your Mobile Client to view the CLIENT INFO.

  3. Copy the configuration to your clipboard.

  4. 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.
  5. Follow the next specific additional instructions depending on your platform:

Android

Locate this file at the following location in your application project:

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

iOS

Locate this file at the following location in your application project:

<app directory>/mobile-services.json

Make sure this file is visible in Xcode, add the file if necessary.
Cordova

Locate this file at the following location in your application project:

src/mobile-services.json

Xamarin

Locate this file at 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.