Getting Started with Mobile Developer Services

Red Hat Managed Integration 1

on Red Hat Managed Integration 1.5

Red Hat Customer Content Services

Abstract

This tutorial guides you through the core features of Mobile Developer Services.

Chapter 1. Introduction

Red Hat Mobile Developer Services provides solutions to common development challenges faced by mobile developers.

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 Developer Services you have provisioned on OpenShift.

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

  • create a representation of your mobile application in OpenShift
  • bind Mobile App with mobile services
  • get the mobile-services.json configuration file for use in your local development environment

Chapter 2. Configuring your Mobile App and Mobile Service in OpenShift

2.1. Registering a Mobile App

After provisioning Mobile Developer Console, the next step is to register the Mobile App 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 the Overview screen.
  4. Log into the Mobile Developer Console.
  5. Click on Create Mobile App button.
  6. Enter a name for your Mobile App.
  7. Click Create button.

2.2. Binding a Mobile App with the Identity Management Service

To use mobile services, you must represent your mobile app in Mobile Developer Console, and that 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. Launch Mobile Developer Console
  2. Click on the Mobile App on the Overview screen
  3. Navigate to Mobile Services tab.

    mobile clients services all unbound down
    Note

    It is possible to bind a Mobile App with a mobile service in the OpenShift console, however such bindings are not valid for the purposes of this procedure.

  4. Press Bind to App in the Identity Management
  5. Fill out the binding parameters required by the Identity Management Service.

    mobile clients services idm parameters
    Note

    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

2.3. Configuring the Service

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

2.3.1. Configuring Red Hat Single Sign-On

  1. Log into the Mobile Developer Console and navigate to the Mobile App screen.
  2. Select the Mobile Services tab and if a spinning icon is displayed to the right of the Identity Management entry, wait for the binding process to complete.
  3. If the Red Hat Single Sign-On Realm URL URL is not visible, expand the Identity Management Service by clicking the > icon.
  4. Click on the Red Hat Single Sign-On Realm URL link to open the Red Hat Single Sign-On Administration Console.
  5. Log in to the Administration console (default admin/admin).
  6. Select Clients from the left navigation menu.
  7. 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.
  8. Add an additional entry to the Valid Redirect URIs input field.

    Set the additional value to http://localhost*.

  9. Add an additional entry to Web Origins.

    Set the additional value to http://localhost*.

  10. Save your changes.
  11. Create a new user account as described in Creating a New User.
  12. Create credentials for the new user as described in User Credentials.

Chapter 3. Setting Up your Local Development Environment

3.1. Supported Environments

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

Note

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

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.

3.2. Running your First Mobile App

3.2.1. Cloning the Showcase App

Ionic
$ git clone https://github.com/aerogear/ionic-showcase.git
$ cd ionic-showcase
$ git checkout0.8.0

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

    Note

    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:
Cordova

Copy the content of mobile-services.json file and paste it to the following location in your application project to replace the value of config

src/mobile-services.js

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

src/mobile-services.json

Chapter 5. Building and Running the Showcase App

  1. Build the Mobile App
Ionic
$ npm install
$ npm run ionic:build
  1. Run the Mobile App
Ionic

To run the showcase app, use these commands:

$ npm run ionic:android # to run on an Android device or emulator
$ npm run ionic:ios # to run on an iOS device or emulator

These commands would run the app on a device if connected or on the emulator if no device is connected.

Alternatively, you can use Cordova commands directly to specify the target:

$ ionic cordova run android --device      # run on a connected device
$ ionic cordova run android --emulator    # run on the Android emulator

Chapter 6. Using Self-Signed Certificates in Mobile Apps

Note

Before you can run a mobile app and connect to Mobile Developer 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.

A typical OpenShift development environment uses self-signed certificates that are not signed by any of the trusted certificate authorities. In such an environment, the client devices cannot establish secure connections with the back-end services that are running on a local OpenShift cluster.

The suggested workaround is to manually extract the root certificate from the cluster, install it on the device, and make sure your application trusts the new certificate.

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

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

Android

To install the cert on an Android emulator:

  1. Set screen lock on the mobile device to allow for the installation of the certificate.
  2. Click on the certificate file and drag it onto the emulator. It should be copied to the Downloads folder on the device.
  3. Install the certificate on your device:

    1. To choose a file, navigate to Settings > Security & location > Advanced > Encryption & credentials > Install from SD card. From here, navigate to the Downloads folder and you should see the certificate file.
    2. Navigate to the Downloads folder and choose the certificate file. The Android system detects the certificate and lets you install it. For more information, see the sample guide for Google Nexus devices.

To install the cert on a real Android device:

  1. Enable screen lock on the mobile device to allow for the installation of the certificate.
  2. Copy the file to your device using one of the following methods:

    • Email attachment (Recommended) - 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 that is accessible from the device, and download from the device.
    • USB - Attach the device to a computer and drag the certificate to a devices file system.

  3. Install the certificate on your device:

    If you are use the email or cloud service method, you are prompted by the Android system automatically to install the file. Follow the instructions to complete the process.

    If you are using the USB approach, you must install the certificate manually:

    1. Go to Settings > Security & location > Advanced > Encryption & credentials > Install from SD card. You are prompted to choose a file.
    2. Navigate to the Downloads folder and choose the certificate file. The Android system detects the certificate and lets you install it. For more information, see the sample guide for Google Nexus devices.

To verify the self-signed certificate is installed correctly, use a browser on the device to open the OpenShift web console. You should not see any warnings or errors relating to the certificate.

iOS

To install the cert on an iOS simulator:

  1. Drag and drop the certificate file to the simulator, and use Safari to download the certificate to the simulator.
  2. Install the downloaded certificate:

    1. Go to Settings > General > Profile. You should see a profile with a name similar to openshift-signer@xxxxxxx.
    2. Tap on the profile. An Install button appears in the top right corner of the screen.
    3. Tap the Install button to install the cert.
  3. Trust the installed certificate in iOS. Go to Settings > General > About > Certificate Trust Settings, and enable the newly installed root certificate. See the Apple support site for more instructions.

To install the cert on a real iOS device:

  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) - 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 that is accessible from the device, and download from the device.
  3. Add the certificate to your device:

    When you download the certificate, the device should automatically detect a profile. Follow the on screen instructions to complete the process.

  4. Trust the installed certificate in iOS. Go to Settings > General > About > Certificate Trust Settings, and enable the newly installed root certificate. See the Apple support site for more instructions.

To verify the self-signed certificate is installed correctly, use a browser on the deveice to open the OpenShift web console. You should not see any warnings or errors about the certificate.

6.3. 3. Trusting the Certificate In Your App.

In the previous procedures, you ensured that the operating system trusts the cert. However, if you are using newer versions of the Android or iOS operating systems, you also need to update your mobile app to make sure it trusts the certificate.

Android
  1. Create a network_security_config.xml file with the following code.

    <network-security-config>
      <base-config>
        <trust-anchors>
          <certificates src="user"/>
          <certificates src="system"/>
        </trust-anchors>
      </base-config>
    </network-security-config>

    Save this file in the following location: * the root directory of the project for JavaScript apps

  2. Update the manifest file of your Android application to use this configuration.

    1. If you are developing a Cordova application, add the following code the config.xml file in for the android platform:

      <resource-file src="network_security_config.xml" target="app/src/main/res/xml/network_security_config.xml" />
      <edit-config file="app/src/main/AndroidManifest.xml" mode="merge" target="/manifest/application">
          <application android:networkSecurityConfig="@xml/network_security_config" />
      </edit-config>

      You also need to add xmlns:android="http://schemas.android.com/apk/res/android" to the widget tag in the same config.xml file.

For more information, check the Android network security configuration guide.

iOS
  1. Add the NSAllowsArbitraryLoads key to the Info.plist file of your iOS project.
  2. Set the NSAllowsArbitraryLoads key to Yes to disable the App Transport Security (ATS) feature for your application.
Note

Only perform these steps for development or debug purposes, the resulting app will not pass the App Store review process.

For more information, see the Apple developer docs.

Chapter 7. Running the app in an emulator

Cordova

Install dependencies:

  1. npm install -g cordova@8 ionic@4
  2. npm install

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

  • Android: npm run ionic:android
  • iOS: npm run ionic:ios

    Note

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

Legal Notice

Copyright © 2019 Red Hat, Inc.
The text of and illustrations in this document are licensed by Red Hat under a Creative Commons Attribution–Share Alike 3.0 Unported license ("CC-BY-SA"). An explanation of CC-BY-SA is available at http://creativecommons.org/licenses/by-sa/3.0/. In accordance with CC-BY-SA, if you distribute this document or an adaptation of it, you must provide the URL for the original version.
Red Hat, as the licensor of this document, waives the right to enforce, and agrees not to assert, Section 4d of CC-BY-SA to the fullest extent permitted by applicable law.
Red Hat, Red Hat Enterprise Linux, the Shadowman logo, the Red Hat logo, JBoss, OpenShift, Fedora, the Infinity logo, and RHCE are trademarks of Red Hat, Inc., registered in the United States and other countries.
Linux® is the registered trademark of Linus Torvalds in the United States and other countries.
Java® is a registered trademark of Oracle and/or its affiliates.
XFS® is a trademark of Silicon Graphics International Corp. or its subsidiaries in the United States and/or other countries.
MySQL® is a registered trademark of MySQL AB in the United States, the European Union and other countries.
Node.js® is an official trademark of Joyent. Red Hat is not formally related to or endorsed by the official Joyent Node.js open source or commercial project.
The OpenStack® Word Mark and OpenStack logo are either registered trademarks/service marks or trademarks/service marks of the OpenStack Foundation, in the United States and other countries and are used with the OpenStack Foundation's permission. We are not affiliated with, endorsed or sponsored by the OpenStack Foundation, or the OpenStack community.
All other trademarks are the property of their respective owners.