Logon

Overview
Registering using the Logon Plugin
SAPUI5 and the Logon Plugin
Customizing the Logon Plugin’s UI
Timing and Performance
Registering using an X.509 Certificate on Android with SMP(SP15+)
Registering using an X.509 Certificate on Android with SAP Cloud Platform Mobile Services(SP15+)
Multiple Users

Overview

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

The server integrates with common security providers such as HTTP/HTTPS Authentication, Directory Service (LDAP), SAML, or x.509 User Certificate. The Logon plugin provides a registration screen where the user can enter values needed to connect to the server. The 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. A basic authentication challenge can be handled automatically by the AuthProxy plugin using the stored registration credentials retrieved from the Logon plugin’s data vault.

The data vault used by the Logon plugin 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.

For additional details on the Logon plugin, see C:SAPMobileSDK3KapselSDKdocsapisap.Logon.html or Using the Logon Plugin.

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.

Registering using the Logon Plugin

If you have not already done so, complete the previous section, Creating an Apache Cordova Project.

  • Add the Logon plugin and dialogs plugin.The following steps assume that a KAPSEL_HOME environment variable has been set to the location of the KapselSDK.
    Note the way to access an environment variable on windows is with a % sign while on a Mac it is a $. 
    on Windows cordova plugin add kapsel-plugin-logon --searchpath %KAPSEL_HOME%/plugins on a Mac cordova plugin add kapsel-plugin-logon --searchpath $KAPSEL_HOME/plugins cordova plugin add cordova-plugin-dialogs

    An added plugin can be removed by calling

    cordova plugin remove plugin_id
  • A list of the plugins now included in the project can be seen by entering the below command. 
    cordova plugins cordova-plugin-device 1.1.6 "Device" cordova-plugin-dialogs 1.3.3 "Notification" cordova-plugin-whitelist 1.3.2 "Whitelist" kapsel-plugin-authproxy 3.15.2 "AuthProxy" kapsel-plugin-corelibs 3.15.2 "CoreLibs" kapsel-plugin-i18n 3.15.2 "i18n" kapsel-plugin-inappbrowser 3.15.2 "InAppBrowser" kapsel-plugin-logon 3.15.2 "Logon" kapsel-plugin-ui5 3.15.2 "ui5"

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

    C:Kapsel_ProjectsKapselGSDemopluginskapsel-plugin-logonplugin.xml
  • This sample requires the application previously created in Configuring a Kapsel App in the Management Cockpit.
  • Replace wwwindex.html with the following contents. 
               
     
    Loading ...
     
         ​

    Create a file named serverContext.js in the www folder and copy the content from below.
    

    var appId = "com.kapsel.gs"; // Change this to app id on server // Optional initial connection context var context = { "serverHost": "10.7.168.212", //Place your SMP 3.0 server name here //"serverHost": "hcpms-i82XXXXtrial.hanatrial.ondemand.com", //SAP Cloud Platform Mobile Services "https": false, //true for SAP Cloud Platform Mobile Services "serverPort": "8080", //443 for SAP Cloud Platform Mobile Services //"multiUser": true, //"useLocalStorage": false, "user": "i82XXXX", //For demo purposes, specify the user name and password you wish to register with here to save typing on the device "password": "XXXXX", //Note, if you wish to use this user name and password to be passed to the backend OData producer, choose Basic as the SSO mechanism //The AuthProxy plugin with the Logon plugin can respond to 401 Authentication challenges if the same credentials used to register are also used to make OData requests //Once set the credentials can be changed by calling sap.Logon.changePassword() "passcode": "password", //Hardcoding passwords and unlock passcodes are strictly for ease of use during development //Passcode can be changed by calling sap.Logon.managePasscode() "unlockPasscode": "password", "passcode_CONFIRM": "password", "oldPasscode" : "password", "communicatorId": "REST", //"auth": [ { "type": "saml2.web.post" } ], //Indicates that a redirect to a SAML IDP should be used for registration //"refreshSAMLSessionOnResume": "skip", // Useful for offline apps when you may not wish for a saml check to be performed when the app is resumed since you may be offline "custom": { "hiddenFields": ["farmId", "resourcePath", "securityConfig", "serverPort", "https"] } }; 
    

    Edit the serverHost, user, and password variables in serverContext.js.
    

    Note if you are using an Android emulator and your server is running on the same machine, 10.0.2.2 can be used to reach the host machine from the emulator.
    

    Note, that the application ID is com.kapsel.gs 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) { ... applicationContext = result; showScreen("MainDiv") } 
    


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

  • If you are targeting Windows 10, add the following to your config.xml file.

     
    

    • 

  • Prepare, build and deploy the app with the following commands.

    cordova run android or cordova run windows -- --archs=x64 or cordova run windows --device -- --archs=arm --phone or cordova run ios 
    

    • 

  • Alternatively, use Android Studio, Xcode or Visual Studio to deploy and run the project after first running the below command.

    cordova prepare
    

    • 

  • The registration screen allows a user to enter the connection information for their SAP Mobile Platform server. As of SP15, this screen will return the following error messages.

      

    • Not connected to network.
      • 

    • Please check your credentials.
      • 

    • Server certificate failed validation.
      • 

    • Server unreachable.
      • 

    • Secure channel error. (occurs if http is used on an https port or vice versa)
      • 

    

    Getting Started with Kapsel – Part 2 — Logon (SP13+)
                              In serverContext.js, the context object can be used to set default values such as port to be used.
                              If you need to enter text on an Android device and wish to use your computers keyboard try the following.
    

    adb shell input text some_text_to_enter
    

    The hiddenFields which was added to the context object in SP 13 can be used to hide fields. Notice above that serverPort and whether to use HTTPS or not are not shown.
    

    var context = { "serverHost": "10.7.186.3", //Place your SMP 3.0 server name here "https": "false", "serverPort": "8080", "custom": { "hiddenFields": ["farmId", "resourcePath", "securityConfig", "serverPort", "https"] } }; 
    

    For additional security, the application can have a passcode screen. The client password policy such as password length and retry limit can be centrally managed in the management cockpit. It is also possible to disable this feature via the custom property disablePasscode as shown in the customization section below.
    

    Getting Started with Kapsel – Part 2 — Logon (SP13+)
    

    The Logon plugin’s data vault which stores the entered credentials needs to be unlocked when the application opens and is locked when it closes. The data vault will also lock if it the app is in the background for a certain length of time. This is configurable via the lock timeout setting.
                              Getting Started with Kapsel – Part 2 — Logon (SP13+)
    

    As of SP14, it is possible to use a fingerprint instead of a passcode to unlock the app. The following instructions demonstrate this on an Android 7.1 emulator. A few issues were found using an earlier emulator so it may be best to use the latest available emulator or a device. Note, a passcode is still required as a fallback in case the device is unable to successfully scan your fingerprint. For additional instructions see Understanding Fingerprint Authentication.
                              Settings > Security> Fingerprint.
                              Getting Started with Kapsel – Part 2 — Logon (SP13+)
                              Getting Started with Kapsel – Part 2 — Logon (SP13+)
    

    The following command simulates a fingerprint touch.
    

    adb -e emu finger touch 1
    

    Alternatively, from the emulators extended controls menu select Fingerprint > Touch Sensor.
    

    Getting Started with Kapsel – Part 2 — Logon (SP13+)
    

     
    

    Getting Started with Kapsel – Part 2 — Logon (SP13+)
                              Getting Started with Kapsel – Part 2 — Logon (SP13+)
                              Getting Started with Kapsel – Part 2 — Logon (SP13+)
    

    Provide the previously entered fingerprint to unlock.
    

    adb -e emu finger touch 1 
    

    It is possible to use the Logon plugin’s data vault without using its features for registering with an SMP server using the sap.Logon.initPasscodeManager method. See the index.html in the Encrypted Storage plugin for a complete example.
    

    • 

  • Try out the rest of the application. The following are a few more screenshots showing the lock screen and the results of performing a read.
                              Getting Started with Kapsel – Part 2 — Logon (SP13+)Getting Started with Kapsel – Part 2 — Logon (SP13+)                        
    • 

  • Note, if the server host, port or application id changes; sap.Logon.core.reset() must be called followed by calling init sap.Logon.init().In SP10 of the SMP server a new setting was added called Automatic Removal which means that registrations that have not been used for a specified time will be deleted automatically.
                              Getting Started with Kapsel – Part 2 — Logon (SP13+)                        
    • 

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

    https://SMP_Server_IP_Address:8080/sapui5/ or https://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.
    

    • 

  • 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, the unlock screen, or if the no passcode option is enabled, the first screen of the app.
    • 

  • Note that this example contains some additional logging and timing of events using the term EventLogging. Event listeners for pause, resume, onload, onunload, onbeforeunload, onSapResumeSuccess, on SapLogonSuccess and onSapResumeError events have been added. See also Events.
    • 

  • 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 and the Logon Plugin
    

    In SP14, a new plugin named kapsel-plugin-ui5 contains a minimal set of the SAPUI5 libraries that are used by the logon plugin.
    

    A change was also made to use the belize theme where in previous versions of the SDK, the blue_crystal theme was used. This is specified in the following file:
    

    C:SAPMobileSDK3KapselSDKpluginslogonwwwcommonassetsuiiab.html
    

    The plugin will install UI5 to the resources folder at the root of the www folder if the following file is not found.
    

    C:Kapsel_ProjectsKapselGSDemowww  esourcessap-ui-core.js
    

    If you want to use your own copy of UI5, delete the resources folder in the www folder and add your own copy of UI5 there. Run cordova prepare to update the platforms with that copy.
    

    If your application is always online and you wish to reduce the size of your app, you could change iab.html to load SAPUI5 from saoui5.hana.ondemand.com. This may also improve the speed of building and deploying your app during development.
    

    src="../../../resources/sap-ui-core.js" to src="https://sapui5.hana.ondemand.com/resources/sap-ui-core.js" 
    

    Note, this requires removing the logon plugin, then adding it back after making this change. Also delete the all the contents in the www
                          esources folder of your application and replace sap-ui-core.js with an empty file. The size of the app prior to making this change was about 12 MB vs 5 MB after.
    

    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.
    

    C:SAPMobileSDK3KapselSDKpluginslogonwwwcommonassetsi18ni18n_en.properties
    

    Make a change to the above file and then remove and add back the logon plugin as shown below.
    

    cordova plugin remove kapsel-plugin-logon cordova plugin add kapsel-plugin-logon --searchpath %KAPSEL_HOME%/plugins cordova run android 
    

    See also the Localization section of this guide.
    

    As of SP13, the custom field in the context object can be used to further customize the screens of the Logon plugin as shown in the following example context.
    

    var context = { "serverHost": "10.7.168.124", //Place your SMP 3.0 server name here "https": "false", "serverPort": "8080", "custom": { "hiddenFields": ["farmId", "resourcePath", "securityConfig", "serverPort", "https"], "backgroundImage": "../../../nightsky.jpg", "copyrightLogo":"../../../logo.png", "styleSheet": "../../../custom.css", "copyrightMsg": ["Copyright @2016 Mycompany Inc.", "All rights reserved."], "hideLogoCopyright" : false, "disablePasscode": true } } };
    

    Note, the above files such as nightsky.jpg should be placed in www folder and the ../ above is necessary as they are referenced from iab.html within the logon plugin.
    

    The contents of the custom.css file follow.
    

    /* company logo */ #panel_footer_hbox > .sapMFlexItem:not(#copyright) { /* uncomment to hide logo */ /*display: none;*/ /* uncomment to right align logo */ /*position: absolute; right: 0px;*/ } #logo { /* change size of logo */ height: 40px !important; } /* copyright message */ #copyright{ /* uncomment to hide copyright message */ /*visibility: hidden;*/ /* uncomment to right align text */ /*text-align: right;*/ /* uncomment to left align copyright message */ /*left: 0px;*/ } /* copyright message first line */ #copyright1{ /* change text color */ color: white; /* change text size */ font-size: 20px; } /* copyright message second line */ #copyright2 { /* change text color */ color: yellow; 
    

    The background and logo images and custom.css files should be placed in the www folder.
    

    Prepare, build and deploy the app with the following command.
    

    cordova run android or cordova run windows -- --archs=x64 or cordova run ios 
    

    Getting Started with Kapsel – Part 2 — Logon (SP13+)
    

    Notice that the background, and copyright logo and text have been customized. Also, note that the option to set a passcode screen is not shown after pressing the OK button due to the context option disablePasscode being set to true.
    

    Timing and Performance
    

    Note that this example contains some additional logging and timing of events using the term EventLogging. To enable the capturing of the time taken from the when the app is initially started till the datavault is unlocked, make the following modification.
                          On Android, modify the following file and change the below line to pass in to the index.html the time the app was started.
    

    C:Kapsel_ProjectsKapselGSDemoplatformsandroidsrccomkapselgsMainActivity.java
    

    //loadUrl(launchUrl); loadUrl(launchUrl + "?startTime=" + new java.util.Date().getTime()); 
    

    With this change, the time taken from the MainActivity which should occur shortly after the user clicks on the app icon till the time the logonSucccessCallback is called can be calculated. In the below example, the time taken is about 2 1/2 seconds.
                          Getting Started with Kapsel – Part 2 — Logon (SP13+)
    

    The time taken by the datavault to unlock can be reduced (using SP15 or greater is recommended for Android) by modifying the useLocalStorage setting in the serverContext.js file as shown below.
    

    "useLocalStorage": true,
    

    Getting Started with Kapsel – Part 2 — Logon (SP13+)
                          Notice above that the time taken from clicking on the app icon till the datavault unlocks has decreased from 2 1/2 seconds to 1.3 seconds.
                          For further details see Storing configuration data outside of the datavault.
    

    Registering using an X.509 Certificate on Android with SMP(SP15+)
    

    In SP15, a built in certificate provider was added to the Logon plugin for Android. The certificate provider enables the logon plugin to perform a registration against a SMP or SAP Cloud Platform Mobile Services server using a certificate to identify the user. The following instructions will demonstrate using it. Additional details are available at Using the X.509 Certificate Provider Interface to Integrate with Third-Party Certificate Providers.
    

      

    • Configure the app com.kapsel.gs to use the Certificate Authentication provider.
                                Getting Started with Kapsel – Part 2 — Logon (SP13+)
                                Set Validated Certificate Is Identity to ON and Certificate Attribute as Principal to be CN which is the Common Name field from the user’s certificate.
                                Getting Started with Kapsel – Part 2 — Logon (SP13+)                        
      • 

    • Configure the SMP server to trust certificates signed by the certificate authority that signed the user certificates by ensuring that the CA that signed the user certificates is listed in the Shared Keystore Entries.
                                Getting Started with Kapsel – Part 2 — Logon (SP13+)                        
      • 

    • Modify the serverContext.js file to use port 8082 and ensure the fully qualified machine name is used for the host.
      • 

    • Add the following code to the start of the JavaScript code in index.html just below the line var resumeTime = null;

      var operation = {}; var appConfig = {}; appConfig.appID = appId; appConfig.isForSMP = true; appConfig.certificate = "com.sap.SystemCertProvider"; var context2 = {}; context2.smpConfig = context; context2.appConfig = appConfig; context2.operation = operation; var appDelegate = { onRegistrationSuccess: logonSuccessCallback, onRegistrationError: logonErrorCallback, }; 
      

      • 

    • Comment out the sap.Logon.init method and replace it with the following code.

      operation.logonView = sap.logon.LogonJsView; sap.Logon.startLogonInit(context2, appDelegate); 
      

      • 

    • Run the app and notice that the user is prompted to select a certificate to be used for the registration.
                                Getting Started with Kapsel – Part 2 — Logon (SP13+)
                                Getting Started with Kapsel – Part 2 — Logon (SP13+)                        
      • 

    

    Registering using an X.509 Certificate on Android with SAP Cloud Platform Mobile Services(SP15+)
    

    The steps are the same as above except the Management Cockpit of the SAP Cloud Platform Mobile Services has a different UI and an additional step to upload the CA is required.
    

      

    • Configure the app com.kapsel.gs to use the Certificate Authentication provider.
                                Getting Started with Kapsel – Part 2 — Logon (SP13+)                        
      • 

    • Configure the server to trust certificates signed by the certificate authority that signed the user certificates.
                                Download the Neo Environment SDK from SAP Cloud Platform Neo Environment SDK.
                                For additional details see the following links.
                                Configuring X.509 Certificate Authentication
                                upload-keystore


       keytool -import -trustcacerts -alias sapsso -file c:certsSSO_CA.cer -keystore hcpms_trusted_ca.jks neo.bat upload-keystore --account i8XXXXtrial --application sapmobile:hcpms --user i82XXXX --location ./hcpms_trusted_ca.jks --host hanatrial.ondemand.com 
      

      Note above that the application name should not be changed as this is the name of the SAP Cloud Platform Mobile Service.
      

      • 

    • Modify the serverContext.js file and change the serverHost to use the new domain for the application.
                                Getting Started with Kapsel – Part 2 — Logon (SP13+)                        
      • 

    

    Multi User (SP14+)
    

    Implemented on iOS and Windows only.
                          Android has multi user built-in to the Android OS via Settings -> Users.
                          To try it out, follow the instructions below.
    

      

    • Uncomment the line “multiUser”: true in the context object in serverContext.js
                              Ensure that the disablePasscode option is either not present or set to false.
                              Ensure that the option useLocalStorage is either not present or set to false.
      • 

    • Add the following code to the start of the JavaScript code in index.html just below the line var resumeTime = null;

      var appConfig = {}; appConfig.appID = appId; appConfig.isForSMP = true; var operation = {}; var context2 = {}; context2.smpConfig = context; context2.appConfig = appConfig; context2.operation = operation; var appDelegate = { onRegistrationSuccess: logonSuccessCallback, onRegistrationError: logonErrorCallback, }; 
      

      • 

    • Comment out the sap.Logon.init method and replace it with the following code:

      operation.logonView = sap.logon.LogonJsView; sap.Logon.startLogonInit(context2, appDelegate); 
      

      • 

    • Add the following method:

      function signOutSuccessCallback() { console.log("signOutSuccess"); unlock(); //shows the pick user screen }
      

      • 

    • Add in a new button to enable the sign out.

      

      • 

    • Delete the app from the device or emulator before redeploying.
      • 

    

                          Back to Getting Started with Kapsel
    

    


    


    

    

    

    New NetWeaver Information at SAP.com
    

    

    Very Helpfull
    

                              
    

    

                                                                

    

    

    

    

                                User Rating:  Be the first one !