Managing iOS 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 iOS devices is available. Ensure that you uncompress the ClientHub.zip file before importing the Client Hub project into Xcode.

Setting Up the Development Environment

Customizing or Branding the Client Hub User Interface

Open the ClientHub project in Xcode to 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 ClientHub > Targets and replace the icons and launch image files compliant with iOS standards as per your requirement.

Client Hub Application Signing

1. Create a certificate signing request file to use for authenticating the creation of the SSL certificate:
   1. Launch the Keychain Access application on your Mac (usually found in the Applications > Utilities folder.
   2. Select Keychain Access > Certificate Assistant > Keychain Access.
   3. Enter your e-mail address and name, then select Save to disk, and click Continue. This downloads the .certSigningRequest file to your desktop.
2. Create a new App ID for the application:
   Note: As a convention, the App ID is in the form of a reversed addresse, for example, com.example.MyPushApp. The App ID must not contain a wildcard character ("*").
   1. Go to the  Apple Developer Member Center Web site, log in, if required, and select  Certificates, Identifiers & Profiles.
   2. Select Identifiers > App IDs, and click the +.
   3. Enter a name for your App ID, and, under App Service, select Push Notifications. This string should match the Bundle Identifier in your iOS app's Info.plist.
   4. Accept the default App ID prefix, or choose another one.
   5. Under App ID Suffix, select Explicit App ID, and enter your iOS app's Bundle ID. Verify that all the values are correct.
   6. Click Submit.
3. Create a provisioning profile to authenticate your device to run the app you are developing:
   Note: If you create a new App ID or modify an existing one, you must regenerate and install your provisioning file.
   1. Navigate to the  Apple Developer Member Center  Web site, and select  Certificates, Identifiers & Profiles.
   2. From the iOS Apps section, select  Povisioning File, and select the + button to create a new provisioning file.
   3. Choose iOS App Development as your provisioning profile type, then click Continue.
   4. From the drop-down, choose the App ID you created and click Continue.
   5. Select your iOS Development certificate in the next screen, and click Continue.
   6. Select which devices to include in the provisioning profile, and click Continue.
   7. Choose a name for your provisioning profile, then click Generate.
   8. Click Download to download the generated provisioning file.
   9. Double-click the downloaded provisioning file to install it. Xcode's Organizer opens in the Devices pane. Your new provisioning profile appears in the Provisioning Profiles section of your Library. Verify that the status for the profile is "Valid profile." If the profile is invalid, verify that your developer certificate is installed in your Keychain.
4. Deploy the Client Hub application on the Device:
   1. In the Client Hub Xcode project, change the bundle identifier in your iOS app’s Info.plist to the App ID created in Apple Developer Member Center.
   2. In the TARGETS > Build Settings > Code Signing, make sure that appropriate provisioning profile created in Step 3 is selected.

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

(Optional) If you forget the SSO passcode, platform security prevents you from using the applications. You must reset your SSO passcode 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 (OData or Kapsel) using Client Hub.

Registering a New Application

Prepare your applications using MAF Logon to work with Client Hub. Applications use a shared keychain. The keychain can be shared only between applications that are signed by the same certificate. Either use the same certificate that you used to sign your version of the Client Hub application, or re-sign the Client Hub using your application certificate.

1. To share a common keychain across two applications, add an entitlements file to your Xcode project:
   1. Create an entitlements file <PROJECT_NAME>.entitlement using Project target > Summary > Entitlements. Select Use Entitlements file.
   2. Add clienthubEntitlements keychain group to the entitlements file using Project target > Summary > Entitlements. Add clienthubEntitlements keychain group.
2. To register your application to the Client Hub, add a configuration descriptor file to your Xcode project.
   1. Create a file named clienthub.plist.
   2. In Xcode, go to File > New > File.
   3. In the Choose a template for your new file modal view, choose Resource > Property List.
   4. Right-click the new Property List > Open As > "Source Code".
   5. Add this XML snippet:

      <?xml version="1.0" encoding="UTF-8"?>
      <!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
      <plist version="1.0">
      <!-- Properties file to provide the application settings. Do not change the key names. -->
      <dict>
       <!--Mandatory Settings-->
              <!--Hostname of the server, example: xyz.sap.corp-->
              <key>Host</key>
              <string>FULLY_QUALIFIED_HOST_NAME</string>
              <!--Port of the server, example: 8080-->
              <key>Port</key>
              <string>PORT</string>
              <!--Security configuration of the application, example: SSO-->
              <key>SecurityConfiguration</key>
              <string>SECURITY_CONFIGURATION</string>
              <!--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. -->
              <key>UserCreationPolicy</key>
              <string>automatic/manual/certificate</string>
       <!--Optional Settings-->
              <!--URL suffix of the relay server or reverse proxy -->
              <key>URLSuffix</key>
              <string>URL_SUFFIX</string> 
              <!--Farm ID of the relay server in case it is used, example: xyz.farm -->
              <key>FarmID</key>
              <string>FARM_ID</string>
              <!--Domain of the application. Used in SAP Mobile Platform older versions. -->
              <key>Domain</key>
              <string>DOMAIN</string>
              <!--Connection type - HTTP or HTTPS. If no value is set, default is true (HTTPS)-->
          	<key>HTTPS</key>
          	<true/>
              <!--Property to set whether the credentials can be shared or not. If no value is set, default is true-->
          	<key>ShareCredentials</key>
      	    <true/>
      </dict>
      </plist>
      

      Replace the values (for example, SECURITY_CONFIGURATION) with values that are specific to your enterprise. If any of the optional settings are not applicable to your enterprise, leave the string value blank.

3. Deploy your project to your device.
4. Open your MAF Logon-based application. MAF Logon checks if you have Client Hub 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 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.plist 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.plist, 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.

Maintaining a Private Data Vault

NSDictionary *query = [NSDictionary dictionaryWithObjectsAndKeys:
                           kSecClassGenericPassword, kSecClass,
                           @"bundleSeedID", kSecAttrAccount,
                           @"", kSecAttrService,
                           (id)kCFBooleanTrue, kSecReturnAttributes,
                           nil];
    CFDictionaryRef result = nil;
    OSStatus status = SecItemCopyMatching((CFDictionaryRef)query, (CFTypeRef *)&result);
    if (status == errSecItemNotFound)
        status = SecItemAdd((CFDictionaryRef)query, (CFTypeRef *)&result);
    NSString *accessGroup = [(NSDictionary *)result objectForKey:kSecAttrAccessGroup];
    NSArray *components = [accessGroup componentsSeparatedByString:@"."];
    NSString *bundleSeedID = [[components objectEnumerator] nextObject];
    NSString *bundleIdentifier = [[NSBundle mainBundle] bundleIdentifier];
    NSString *defaultaccessGroup = [NSString     		stringWithFormat:@"%@.%@",bundleSeedID,bundleIdentifier];
    
#if !TARGET_IPHONE_SIMULATOR && !TARGET_IPAD_SIMULATOR
    [DataVault setAccessGroup:defaultaccessGroup];
#endif
    CFRelease(result);