Getting Started with Kapsel - Part 2 -- Logon

[Dan_vL]

Logon

If you are using SP13 or higher please see Logon SP13+


The Logon plugin manages the onboarding or registration process to the SMP 3.0 server.  When an application onboards to the SMP server, it receives a registration ID (also known as an application connection ID).  In all subsequent requests to the SMP server, the registration id is sent via a header named X-SMP-APPCID or through a cookie that is set following a successful registration.  This enables tracing functionality for each app instance.

Registering using HTTP/HTTPS POST
Registering using the Logon Plugin
Accessing the Values Stored by the Logon Plugin
SAPUI5 Used by the Logon Plugin
Customizing the Logon Plugin's UI

Registering using HTTP/HTTPS POST

The process to onboard to the SMP server can be seen by examining or trying out register.html.  Before trying it out, ensure that an application with an id of com.mycompany.logon has been configured as described in Configuring a Kapsel App in the Management Cockpit and a copy of datajs-1.1.2.min.js is placed into the same folder where register.html is loaded from.  For additional details on datajs and OData see Appendix A:  OData.
Note that since the application com.mycompany.logon uses the No Authentication Challenge provider, any user name and password will work.

The registration ID can be seen in the management cockpit following a successful registration.

If the registration fails one quick test to verify basic connectivity to the SMP 3.0 server from the device or emulator is to open the following URL from a browser on the device or emulator.

http://SMP_Server_IP_Address:8080/sapui5/ or http://SMP_Server_IP_Address:8080

If the above URL opens correctly in a browser on the machine that the SMP server is running on but not from the browser on another machine or on a mobile device there is likely something such as a firewall preventing communication over port 8080.

Another way to register with the SMP server is via REST calls using a plugin to Chrome such as the Advanced REST client.  This is explained in the following post in more detail.  SMP 3.0 : REST API Application Development.

Registering using the Logon Plugin

The SMP server integrates with common security providers such as HTTP/HTTPS Authentication, Directory Service (LDAP), or x.509 User Certificate.  The Logon plugin provides a registration screen where the user can enter values needed to connect to an SMP 3.0 server.  The SMP 3.0 server will validate the registration using one of the security providers and the connection details will be stored in the Logon plugin's secure data vault.  This data vault is separate from storage provided with the Encrypted Storage plugin and is used to store user names, passwords, keys and certificates while the Encrypted Storage plugin is better suited to storing application data.  Another feature of the Logon plugin is the ability to specify a client password policy such as password length and retry limit, which can be centrally managed.  The next sample, register2.html, provides similar functionality to the previous sample except that it uses the Logon plugin which uses native code to communicate to the SMP server and the UI portions are handled by HTML screens created using SAPUI5.  For additional details on the Logon plugin see the JavaScript file in a project that includes this plugin at

project_name\plugins\com.sap.mp.cordova.plugins.logon\www\common\modules\LogonControler.js

or the JS Documentation at Kapsel Logon API Reference.

Note, this example demonstrates using HTTP, however all production apps should use HTTPS.

Note, the Logon plugin can share credentials between apps by interfacing with Client Hub.

The Logon plugin can also receive settings or a certificate from a mobile management solution such as SAP Afaria or SAP Discovery Service.
For additional information on the underlying component that is exposed via the Logon plugin the Developing with MAF Logon section explains how to use the MAF Logon in a native application. 
Perform the following steps to create and run a new Apache Cordova project which includes the Logon plugin.  If you completed the section, Creating an Apache Cordova Project, skip the below step which creates the project.

• Create the project.

  cordova -d create C:\Kapsel_Projects\LogonDemo com.mycompany.logon LogonDemo "{\"plugin_search_path\":\"C:/SAP/MobileSDK3/KapselSDK/plugins/\"}"
  
  cd C:\Kapsel_Projects\LogonDemo
  
  cordova -d platform add android
  
  
  
  cordova -d create ~/Documents/Kapsel_Projects/LogonDemo com.mycompany.logon LogonDemo "{\"plugin_search_path\":\"/Users/i826567/SAP/MobileSDK3/KapselSDK/plugins/\"}"
  
  cd ~/Documents/Kapsel_Projects/LogonDemo
  
  cordova -d platform add ios

• Add the Logon plugin and optionally the console plugin so that the results of console.log can be seen when run on an iOS device in the All Output view.

  cordova -d plugin add com.sap.mp.cordova.plugins.logon
  cordova -d plugin add org.apache.cordova.console
  
  

  Note, it is possible to use Cordova 4.3.0 with SP08 of the SDK but it requires using the following format when adding Kapsel plugins.

  cordova plugin add com.sap.mp.cordova.plugins.logon --searchpath C:\SAP\MobileSDK3\KapselSDK\plugins
  
  or
  
  cordova plugin add C:\SAP\MobileSDK3\KapselSDK\plugins\logon --searchpath C:\SAP\MobileSDK3\KapselSDK\plugins
  
  or
  
  cordova plugin add com.sap.mp.cordova.plugins.logon --searchpath %KAPSEL_HOME%\plugins
  
  

• A list of the plugins now included in the project can be seen by entering the below command.

  cordova plugins
  
  com.sap.mp.cordova.plugins.authproxy 3.8.1 "AuthProxy"
  
  com.sap.mp.cordova.plugins.corelibs 3.8.1 "CoreLibs"
  
  com.sap.mp.cordova.plugins.logon 3.8.1 "Logon"
  
  org.apache.cordova.device 0.3.0 "Device"
  
  org.apache.cordova.inappbrowser 0.6.0-patched "InAppBrowser"
  
  

  
  Notice that the plugins that the Logon plugin depends on are added if they are not present.  This is defined in

  C:\Kapsel_Projects\LogonDemo\plugins\com.sap.mp.cordova.plugins.logon\plugin.xml

• If needed, follow the steps shown in Configuring a Kapsel App in the Management Cockpit to create an Application with the application id of

  com.mycompany.logon

• Replace www\index.html with the contents of register2.html.  Either right-click and choose Save link as or View page source after clicking on the link and copy and paste the contents.
  
  Note, that the application ID is com.mycompany.logon and is passed in as a parameter to the method sap.Logon.init().  The logonSuccessCallback method stores an object containing the logon parameters into the applicationContext variable.

  function logonSuccessCallback(result) {
  
      alert("Successfully Registered");
  
      applicationContext = result;
  
  }
  
  

• The Logon plugin on Android can write a lot of debugging info to the LogCat.  To reduce this, the console.log line in the method log in the following file can be commented out.

  C:\Kapsel_Projects\LogonDemo\plugins\com.sap.mp.cordova.plugins.logon\www\common\modules\Utils.js

• Copy the files to the platform directory by running

  cordova -d prepare
  
  

  Note, if you are only using one platform when initially developing the application you can modify the platform specific versions of the file and skip the above step.
  To do this using Xcode modify the files under Staging\www.
  To do this using the Android IDE, right click on the project, choose Properties > Resource Filters and delete the two filters.  After this, the folder Assets/www appears where the platform specific files can be modified.
  Note, if you do at some point run cordova prepare, any changes made to the platform specific files will be overwritten.
• Use the Android IDE or Xcode to deploy and run the project.
  
  Note, in Android, the HTML files appear under the folder named assets\www.
  
  Note, if there is a compile error for Android, it may be necessary to select the API level 16 or higher.
  
  
  Note, if the Afaria client is opening after calling sap.Logon.init(...), it can be disabled by modifying the file MAFLogonManagerOptions.plist. In Xcode this can be found under Resources > MAFLogonManagerNG.bundle > MAFLogonManagerOptions.plist. Set keyMAFUseAfaria to false.
  
  Note, if the app on iOS successfully registers in the simulator but not on the device, you may need to add the clienthubEntitlements to the Keychain Groups.  See Sharing Credentials for additional details.
  
  The registration screen allows a user to enter the connection information for their SAP Mobile Platform server.  The specified values are stored securely and are password protected.  The data vault these values are stored in can be locked and unlocked.  Note that as of SP03, it is possible to use the Logon plugin's data vault without using its features for registering using the sap.Logon.initPasscodeManager method. See the index.html in the Encrypted Storage plugin for a complete example.
  
  Unregister will delete the registration ID.
  
  
• Note, if the server host, port or application id changes; Logon.core.deleteRegistration() must be called.
• Note, the user name shown in the management cockpit under Registrations this time is nosec_identity.
  
  
• Note, it is also possible to use the Logon plugin to register against a SAP Netweaver Gateway server.  To do so, simply enter the host, user name, password, port and via the context object specify "communicatorId":"GATEWAY".  Note that when registering against SAP Netweaver Gateway the client password policy can be set by modifying Resources/MAFLogonManagerNG.bundle/MAFLogonOperationContextDefaultValues.plist on iOS.

Accessing the Values Stored by the Logon Plugin

Requests to access an OData source are typically handled by the datajs JavaScript library.  These requests can be proxied through the SMP 3.0 server and when they are, the Logon plugin can be used to provide some of the values required in the request.

sUrl = applicationContext.applicationEndpointURL + "/CarrierCollection?$format=json";  //JSON format is less verbose than atom/xml

var oHeaders = {};

oHeaders['Authorization'] = "Basic " + btoa(applicationContext.registrationContext.user + ":" + applicationContext.registrationContext.password);

oHeaders['X-SMP-APPCID'] = applicationContext.applicationConnectionId;

Perform the following steps to modify the previously created project to add functionality which makes an OData request.

• Replace www\index.html with the contents of register3.html.
• Place a copy of datajs-1.1.2.min.js into the www folder.  For additional details on datajs and OData see Appendix A:  OData.
• Modify the context variable in index.html.  Update the serverHost, user and password values.
• Copy the files to the platform directory by running

  cordova -d prepare
  
  

• Use the Android IDE or Xcode to deploy and run the project.
  Click on Unlock, Unregister, Register and then Read.  The app had to reregister so that the correct user name and password for the OData source was entered into the Logon plugin.
  
  When the app is opened, the deviceready event fires and the code in the init() method is called including a call to sap.Logon.init() which will open either the registration screen or the unlock screen.
  
  The read method will make an OData request to the application's endpoint and will use the user id, password and endpoint URL  (all provided from a successful registration).  It is useful to understand that one set of credentials are being used to register with the SMP server (MyUserName and MyPassword) and another set of credentials are provided by the SMP server when accessing the OData endpoint via the Technical User SSO mechanism configured in the management cockpit.  An alternate configuration would be to use the Basic SSO mechanism with an HTTP/HTTPS authentication provider and then the same user name and password provided to register with the SMP server would also be used to access the backend OData endpoint.
  
  Note the unlock screen appears after the app is opened after being closed or put in the background.  This ensures that any sensitive data that was displayed on the screen before the app was sent to the background cannot be viewed by someone who does not have the app's passcode.  If the setting Lock timeout is set to a value of 60, this means that if the app is in the background for one minute or more before being brought back to the foreground, the lock screen will appear.
  
  
• Note that on iOS versions greater than 6, the status bar can overlay the contents of the WebView.  The org.apache.cordova.statusbar plugin can be added to prevent this.  See iOS 7 Status Bar Overlays the App.
  
  

SAPUI5 Used by the Logon Plugin

The Logon plugin uses the SAPUI5 library when displaying the Registration and Passcode screens.  The SAPUI5 library is located in the following folder.

C:\Kapsel_Projects\LogonDemo\platforms\android\assets\www\smp\logon\ui\resources

If your application is used when the device is always online and you wish to minimize the size of the application, it is possible to load the SAPUI5 library from the public server at https://sapui5.netweaver.ondemand.com/resources and remove the resources folder from your application.  To do this, modify iab.html to load its resources from the public server as shown below.

C:\Kapsel_Projects\LogonDemo\platforms\android\assets\www\smp\logon\ui\iab.html



<script type="text/javascript" src="https://sapui5.netweaver.ondemand.com/resources/sap/ui/thirdparty/jquery/jquery-1.10.2.js"></script>

<script type="text/javascript" src="https://sapui5.netweaver.ondemand.com/resources/sap/ui/thirdparty/jqueryui/jquery-ui-position.js"></script>

<script id="sap-ui-bootstrap" type="text/javascript"

     data-sap-ui-preload="none" data-sap-ui-libs="sap.m"

        data-sap-ui-theme="sap_bluecrystal" src="https://sapui5.netweaver.ondemand.com/resources/sap-ui-core-nojQuery.js"></script>

If you wish to make this change permanent so that the change persists after running cordova prepare, make the above changes to the Logon plugin directly.

C:\Kapsel_Projects\LogonDemo\plugins\com.sap.mp.cordova.plugins.logon\www\common\assets\ui

Note that when examining the files that the application has loaded, the SAPUI5 files are now being loaded from the public server.  This means that the device must be online when initially registering and online if the lock and unlock functionality it used and the first time the SAPUI5 files are loaded, the load time will be increased since the files have to loaded over a Wi-Fi or cellular network.

Alternatively if your application uses SAPUI5, you may wish to reference the already included SAPUI5 library from your application.  It may make sense to move the resources folder to the www folder and then modify the three references in the below file to use ../../../resources as shown below.

C:\Kapsel_Projects\LogonDemo\platforms\android\assets\www\smp\logon\ui\iab.html



<script type="text/javascript" src="../../../resources/sap/ui/thirdparty/jquery/jquery-1.10.2.js"></script>

<script type="text/javascript" src="../../../resources/sap/ui/thirdparty/jqueryui/jquery-ui-position.js"></script>

<script id="sap-ui-bootstrap" type="text/javascript"

     data-sap-ui-preload="none" data-sap-ui-libs="sap.m"

        data-sap-ui-theme="sap_bluecrystal" src="../../../resources/sap-ui-core-nojQuery.js"></script>

If you wish to make this change permanent so that the change persists after running cordova prepare, make the above changes to the Logon plugin directly.

C:\Kapsel_Projects\LogonDemo\plugins\com.sap.mp.cordova.plugins.logon\www\common\assets\ui

Customizing the Logon Plugin's UI

The text that is displayed as part of the Logon's UI can be modified as the strings are loaded from the file i18n.properties.  The changes can be made to either the original copy of the file so all future projects will contain the changes or on a project by project basis.

C:\SAP\MobileSDK3\KapselSDK\plugins\logon\www\common\assets\i18n\i18n.properties

or

platforms\android\assets\www\smp\logon\i18n\i18n.properties

In addition the strings can be localized by creating additional copies of the above file for different languages.  For example to add French language support make a copy the i18n.properties file and name it i18n_fr.properties.  Make a few changes to some of the text.  The changes can be seen after changing the default language on the device or emulator.  On Android Settings > Language & input > Language > Francais.  On iOS Settings > General > International > Language > Francais.  Redeploy the app.  Note, on Android, the app will have to be removed from memory before it detects the change to the language by pressing and holding the app icon, drag it to the App Info text and then choose Force stop.

If some of the fields that are displayed are not required, they can be removed or placed in a different order.  For example, if your application does not make use of a relay server, a reverse proxy server or connect to an SMP 2.x server, some of the fields can be removed such as URL Suffix, Company ID, and Security Config.  To do so modify the file

www\plugins\com.sap.mp.cordova.plugins.logon\www\common\modules\StaticScreens.js

Find the SCR_REGISTRATION screen and reorder/hide/show fields using visible:false or simply remove unneeded entries.  Note some fields such as FLD_HOST must be present but can be set to visible:false.

fields: {

    user : {

        uiKey:'FLD_USER'

    },

    password : {

        uiKey:'FLD_PASS',

        type: 'password'

    },

    serverHost : {

        uiKey:'FLD_HOST',

    },

    serverPort : {

        uiKey:'FLD_PORT',

        type: 'number',

    }

}

Note the registration screen no longer displays these fields.

In SP03, a method was added that enables a developer to further customize the screens shown by the Logon plugin.  The following example code can be added to register3.html.  This code will enable the Registration screen and the passcode screen to be skipped.  Specifically replace the call to sap.Logon.init with the below code.

//The Logon UI can be customized by adding a custom method to handle showScreen

var logonView = sap.logon.IabUi;

logonView.onShowScreen = customShowScreen;

logonView.onShowNotification = customShowNotification;



sap.Logon.init(logonSuccessCallback, logonErrorCallback, appId, context, logonView);

Add the following two methods.

function customShowScreen(screenId, screenEvents, currentContext) {
    if (screenId =="SCR_SSOPIN_SET") {
        screenEvents.onskip();
        return true;
    }

else if (screenId =="SCR_UNLOCK") {

        var context = {

            unlockPasscode: "Password1@"

        }

        screenEvents.onsubmit(context);

        return true;

    }

    else if (screenId =="SCR_REGISTRATION") {
        screenEvents.onsubmit(currentContext.registrationContext);
        return true;
    }
    else if (screenId =="SCR_SET_PASSCODE_MANDATORY") {
          var context = {
                  passcode: "Password1@",
                  passcode_CONFIRM: "Password1@"
          }
          screenEvents.onsubmit(context);
          return true;
    }
    else if (screenId =="SCR_SET_PASSCODE_OPT_ON") {
        screenEvents.ondisable();
        return true;
    }
    else if (screenId =="SCR_SET_PASSCODE_OPT_OFF") {
        var context = {};
        screenEvents.onsubmit(context);
        return true;
    }
    return false;  //skip the default value
 }

 function customShowNotification(screenId, notificationKey) {
    if (screenId == "SCR_SSOPIN_SET" || screenId == "SCR_UNLOCK" || screenId == "SCR_REGISTRATION" || screenId == "SCR_SET_PASSCODE_MANDATORY" || screenId == "SCR_SET_PASSCODE_OPT_ON" || screenId == "SCR_SET_PASSCODE_OPT_OFF" ) {
        alert(notificationKey);
        return true;
    }
    return false;
 }

Copy the files to the platform directory by running

cordova -d prepare

Use the Android IDE or Xcode to deploy and run the project and notice that the registration and passcode screens are not shown.
Note, it is typically not a good idea to skip screens such as the registration screen that may require user intervention.

The Logon plugin's screens use the UI library named SAPUI5.  Some customization is possible by changing the CSS files.

www\smp\logon\ui\css\logonForm_debug.css

www\smp\logon\ui\resources\sap\me\themes\sap_bluecrystal

If your Kapsel app uses another UI library it may make sense to use that library to also render the UI screens of the Logon plugin to minimize the size of the application or to keep the UI throughout the application consistent.  The content of the screens are dynamically rendered in the method showScreen(uiDescriptor, context) of

www\smp\logon\ui\LogonForm.js

which is called from

www\smp\logon\ui\iab.html

The below file contains JSDoc comments that describe the parameters to the showScreen method in more detail.

C:\SAP\MobileSDK3\KapselSDK\plugins\logon\www\common\assets\ui\iab.js

The following attached iab.html file is a minimal example that demonstrates how this could be accomplished.  Replace www\smp\logon\ui\iab.html with the above file.
Delete the folders containing SAPUI5.

www\smp\logon\ui\css

www\smp\logon\ui\img

www\smp\logon\ui\resources

Delete the following two files which are now implemented in iab.html.

www\smp\logon\ui\LogonForm.js

www\smp\logon\ui\Notification.js

www\smp\logon\ui\iab.js (SP02+)

Deploy and run the project and notice that the Logon pages are now shown without a UI library.

Back to Getting Started With Kapsel