Developer

Configuring Business Application with Client Hub

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.

Context

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.

Procedure

  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, replacing 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.
      <?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>
      
  3. For applications running on iOS9 and above devices, the following URLScheme must be included, or the application does not recognize the ClientHub. Add the following to the Info.plist of the application:
     		
    <key>LSApplicationQueriesSchemes</key>
    <array>
        <string>CLIENTHUBSCHEME</string>
    </array>
  4. Deploy your project to your device.
  5. 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.
  6. 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 performed 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, click 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.
  7. 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.
  8. 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.

Procedure

  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 and then reinstall the application on the device. When the Client Hub is detected after re-launch, the application shares its credentials 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.

Procedure

  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

If a business application needs to maintain a private data vault, then you should add (CFBundleIdentifier) as the first keychain group prior to clienthubEntitlements keychain group in the entitlements file.

Procedure

  1. Ensure to set the access group to default access group <bundleseedID.bundleID> before performing any operations on the private data vault like creating or retrieving data vault.
  2. Use the following code snippet example to set the default access group programmatically:
    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);