Managing Android Application Registration Using Client Hub

1. Getting Started with Client Hub Application Installation and Initialization

The following tasks describe the steps to install and initialize the Client Hub application.

Installing the Client Hub Application

Install SAP Mobile Platform Native SDK - Client Hub component. By default, SAP Mobile Platform SDK components are installed in the ..\SAP\MobileSDKXXX directory. In this guide, SDK_HOME represents the SAP Mobile Platform SDK installation directory, down to the MobileSDKXXX folder. Client Hub gets installed under the ClientHub directory, where the project files for Client Hub applications, used for registering applications on Android devices is available. Ensure that you  unzip the ClientHub.zip file before importing the Client Hub project into Eclipse.

Setting Up the Development Environment

Importing Client Hub Project into Eclipse

1. Open Eclipse WorkSpace.
2. Click File > Import... > Android > Existing Android Code Into Workspace. Click Next.
3. In the Root Directory, click Browse..., select C:\SAP\MobileSDKXXX directory\ClientHub. Click OK. The Client Hub project is selected by default.
4. Click Finish. The ClientHub folder is displayed in your Eclipse Package Explorer.

Client Hub Application Signing

Build the Client Hub application, cosigned with the same developer certificate as the application using these steps:

1. Right-click ClientHub folder in the package explorer. Navigate to Android Tools > Export Signed Application Package.
2. In the Export Android Application wizard, the ClientHub project appears. Click Next.
3. In the Keystore selection window, select:
   1. Select existing keystore if you already have a keystore:
      1. Enter the location of the existing keystore.
      2. Enter the password.
      3. Click Next.
      4. Choose Use existing key. Enter the alias and password, click Next.
   2. Select new keystore to create a new key store.
      1. Enter the location where the new keystore should be created.
      2. Enter the password, then reenter the password for confirmation.
      3. Click Next.
      4. In the Key Creation window, enter the details. Click Next.
4. In the Destination and key/certificate checks window, enter the destination APK file name.
5. Click Finish.

   This process creates an Android Client Hub executable (.apk) that can be deployed on the device or emulator.

Customizing or Branding the Client Hub User Interface

After importing the ClientHub project, you can customize the look and feel of the Client Hub application. For example: the splash or welcome screen can be customized to include your company logo or image. Browse through the ClientHub > res folder and replace the resource files as per your requirement.

Setting the SSO Passcode in Client Hub Application

You must set your SSO passcode in the Client Hub application, and use this passcode in all your applications. Ensure that the SSO passcode is at least 8 characters, and contains at least one uppercase, lowercase, and numeric character.

1. Launch the Client Hub application on your device.

   The Create SSO Passcode window is displayed.

2. Enter the SSO passcode, then reenter the passcode to confirm the change.
3. Click Submit.

   A success message is displayed if the passcode is accepted and set correctly. Use this SSO passcode for all the applications.

4. Exit the Client Hub application.

Resetting the Client Hub SSO Passcode

If you forget the SSO passcode, platform security prevents you from using the applications. You must reset your SSO passcode in the Client Hub application, and use the new passcode in all your applications. Resetting the passcode deletes all data from the secure store.

1. Click Reset, then click OK to confirm.

   An alert box is displayed for confirmation. If you click OK, you are redirected to the Set passcode screen.

2. In the Create SSO Passcode screen, enter the new passcode, then reenter the passcode to confirm the change.
3. Click Submit.

   Use this new passcode for all the applications.

2. Configuring Business Application With Client Hub

The following tasks describe the steps to configure the business application using Client Hub.

Registering a New Application Using Client Hub

1. To get connection settings for Client Hub, add a configuration descriptor file to your Eclipse project.
   1. Create a file named clienthub.properties and place it into the/res/raw folder of your Android project.
   2. Add this content:

      #Properties file to provide the application settings. Do not change the key names.
      
      #Mandatory Settings
      
      
      #Hostname of the server, example:xyz.sap.corp 
      Host=<FULLY_QUALIFIED_HOSTNAME>
      #Port of the server, example: 8080
      Port=<PORT>
      #Farm ID of the relay server in case it is used. Example: xyz.farm. If relay server is not used, set the value to 0.
      FarmID=<FARM_ID>
      #Security configuration of the application, example: SSO
      SecurityConfiguration=<SECURITY_CONFIGURATION>
      #Property to set the user creation policy. The user creation policy defines the authentication method for the user: automatic, manual or certificate.
      The manual and automatic is for the password based authentication. The certificate is for the X.509 based authentication. 
      If no value is set, default is certificate.
      UserCreationPolicy=<automatic/manual/certificate>
      
      #Optional Settings
      
      
      #URL suffix of the relay server or reverse proxy.
      URLSuffix=<URL_SUFFIX>
      #Domain of the application. Used in SAP Mobile Platform older versions.
      Domain=<DOMAIN>
      #Connection type, HTTP or HTTPS. If no value is set, default is true (HTTPS).
      HTTPS=<true/false>
      #Property to set whether the credentials can be shared or not. If no value is set, default is true.
      ShareCredentials=<true/false>
      

      Replace the values (for example, SECURITY_CONFIGURATION) with values that are specific to your enterprise.
2. Ensure that the following permission is present in the MAF Logon-based application's androidManifest.xml file within the <manifest> tag. If not, add the permission:

    <uses-permission android:name="com.sap.mobile.clientHub.CLIENTHUB_ACCESS_PERMISSION"/> 
   

3. Deploy the MAF Logon-based application to your device.
4. Open your MAF Logon-based application. MAF Logon checks whether Client Hub is installed on your device, and if the SSO password is specified by the user.
5. MAF Logon displays the Client Hub Logon UI screen, where you can either enter your Client Hub SSO password, or choose skip:
   • To use the app with Client Hub, enter your SSO passcode and tap Next. Once all the prerequisites are fulfilled, the Set Passcode screen appears, which indicates that the registration is successful. The registration is preformed based on the credentials stored in the Client Hub application shared Data Vault, and the connection data is read using the Client Hub libraries built into the application.
   • If you do not want to use your application with Client Hub, tap Skip. You are opted out from using Client Hub to share credentials and connection data with this application. MAF Logon does not present the SSO Passcode UI on subsequent application starts, unless the application is reinstalled.
6. If you enter the SSO Passcode, MAF Logon checks whether it can open Client Hub with the specified password, then stores the password in its own Secure Store.
7. MAF Logon opens Client Hub and requests credentials and connection data from the Client Hub libraries. If the UserCreationPolicy, HTTPS, and ShareCredentials values are not provided, the Client Hub libraries use the default values for the application, from the clienthub.properties file.

   If there are no shared credentials yet, MAF Logon presents the Logon UI with only two fields for providing the back-end username and password. When the registration succeeds with these new credentials and the connection data provided by the clienthub.properties, it stores the credentials in Client Hub.

Enabling an Application Registered Using Client Hub

To reenable an application that is registered with Client Hub, relaunch the application.

1. MAF Logon checks whether the Client Hub is still present on the device.
   • If it is not, MAF Logon decouples your application from the Client Hub. If you intentionally skip the Client Hub screen, your application never again checks for Client Hub, and cannot share credentials or connection information, even via a new Client Hub installation. To recouple your application with Client Hub, you must delete, then reinstall, the application on the device. When the Client Hub is detected after re-launch, the application shares its credential with Client Hub.
   • If the Client Hub is still available, MAF Logon checks whether the SSO passcode is still valid.

     If the SSO Passcode is invalid, the MAF Logon UI prompts the device user for a new SSO passcode. MAF Logon then opens Client Hub and fetches the credentials stored there.

2. MAF Logon compares the back-end user name and password with the user name and password stored in the secure store of the application.
   • MAF Logon writes the credentials into Client Hub application if:
     • Client Hub does not contain any credentials, or
     • credentials stored in the secure store of the application are newer than those in Client Hub.
   • MAF Logon writes the credentials into the secure store of the application if the credentials stored in the secure store of the application are older than those in Client Hub version.
3. Once the passwords are identical, MAF Logon launches the application process.

Changing the Back-end Password

If there is an authentication error or when the backend password is changed, follow these steps to update the back-end password.

1. MAF Logon presents the Backend Password screen to get the new password.
2. Provide the new password.
3. MAF Logon verifies the password, then shares the new password with other applications through the Client Hub.