Getting Started with AeroGear Mobile Services

Introduction

This guide will bring you through all the required steps to get up and running with Mobile Services. By the end of this guide you will have learned how to:

  • Set up AeroGear Mobile Services on OpenShift

  • Create a Mobile Client and a Mobile Service

  • Set up a local development environment

  • Configure and run the AeroGear Showcase App on your platform of choice

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 https://www.openshift.org/.

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 https://github.com/minishift/minishift/issues/1287.

Prerequisites

  • MacOS or Linux

  • A system running OpenShift oc cluster up as described in Local Cluster Management

    • Use OpenShift client tools version 3.9 or later

      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.
  • A Docker Hub account

  • 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

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.

    DockerHub Tag (Defaults to latest):
    DockerHub Organisation (Defaults to aerogearcatalog):
    Cluster IP (Defaults to < Network IP Address >)
    Wildcard DNS Host (Defaults to nip.io):

    The first two values configure the location of the APBs used for the service-catalog in the cluster you are creating.

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

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

    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. Open a browser and login (accepting the self-signed certificate):

      https://192.168.37.1:8443/console/

      The developer login credentials are:

      username: developer
      password: password
    2. At the top of the catalog package, find the Mobile category that indicates that the mobile features of AeroGear Mobile Services are successfully installed.

catalog mobile clients

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

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.

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

  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 provisioning an Identity Management service, you are prompted to set the following 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.

Once the wizard steps are completed, navigate to the Project Overview in OpenShift to see the newly provisioned 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 once it’s done, your mobile app can use that service immediately.

The association between a Mobile Client and Identity Management Service uses the Service Broker bind feature.

To associate a Mobile Client with a mobile service:

Procedure

  1. Navigate to the Overview of your OpenShift project.

  2. Click on the Mobile Client and navigate to Mobile Client view.

    Your mobile app will be represented by two items in OpenShift, an item in the Mobile Clients list and an item in the Provisioned Services list. Make sure to click on the item in the Mobile Clients list.
  3. Navigate to Mobile Services tab.

    mobile clients services all unprovisioned
  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.

  6. Choose the Keycloak client type. The default is public which allows the client to request tokens while type bearer should be used to bind to services that only need to verify tokens.

    The public client type should be used to bind to Mobile Clients because they only need to request tokens, but not verify them. When binding to other services you should use client type bearer unless they also need to authenticate.

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.

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

The schema of the redirect url should be http://localhost/*.

Xamarin

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

Configuring Keycloak

  1. Expand the Identity Management Service by clicking the > icon.

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

  3. Log in to the Administration console using the credentials you specified at Provisioning (defaults to admin:admin)

  4. Open Clients from the menu.

  5. Open your client. 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.

  6. Add <schema>:/callback to Valid Redirect URIs.

  7. Add <schema> to Web Origins.

  8. Save your changes.

You must create a new user account before you can log into the Showcase App. To create a new user, follow the steps here and to setup a new users credentials, follow the steps here.

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. For information on how to set up your local development environment for these technologies, please see the links below:

Running your First Mobile App

Clone 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

Using Self-Signed Certificates in Mobile Apps

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

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

Cordova

Locate this file in your application project and import it using require.

const aerogearConfig = require("./mobile-services.json");

Alternatively you can create a JavaScript object and use directly:

const aerogearConfig = /* Paste here the contents of the clipboard */;
Xamarin

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

Resources/mobile-services.json

Building and Running the Mobile App in an Emulator

Build the app:

Android
$ ./gradlew assembleDebug
iOS

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

Run the app in an emulator:

Android

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

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.