Logon

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.  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
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.1.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/

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 a mobile device or emulator there is likely something such as a firewall preventing communication over port 8080.

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 logon screens where the user can enter values needed to connect to an SMP 3.0 server using one of these providers and will store those values in its own secure data vault.  This data vault is separate from the one provided with the encrypted storage plugin and is used to store user names, password, keys and certificates while the encrypted storage plugin is better suited to storing application data.  As well, the client password policy such as password length and retry limit, 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 device management solution named SAP Afaria.

For additional information on the underlying component that is exposed via the logon plugin see the following topic which explains how to use the MAF Logon in a native application.  Developing with MAF Logon

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
  cd C:\Kapsel_Projects\LogonDemo
  cordova -d platform add android
  
  cordova -d create ~/Documents/Kapsel_Projects/LogonDemo com.mycompany.logon LogonDemo
  cd ~/Documents/Kapsel_Projects/LogonDemo
  cordova -d platform add ios

• Add the logon plugin which includes the Cordova console plugin among others.

  cordova -d plugin add C:\SAP\MobileSDK3\KapselSDK\plugins\logon
  
  cordova -d plugin add ~/SAP/MobileSDK3/KapselSDK/plugins/logon
  

  If the error message "Plugin com.sap.mp.cordova.plugins.logon is not in git repository" appears, the following steps should correct this problem.

  cd  C:\SAP\MobileSDK3\KapselSDK\plugins
  or 
  cd ~/SAP/MobileSDK3/KapselSDK/plugins
  
  git init
  

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

  cordova plugins

  
  
  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;
  }

• Copy the files to the platform directory by running

  cordova -d prepare

• 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.
  
  Unregister will delete the registration ID.
  
  
  
  
• Note, if the server host, port or application id changes; Logon.core.deleteRegistration() must be called.
  
  

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.1.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, endpoint URL and registration ID (all provided from a successful registration).
  
  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.
  
  
  
  

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:\SAP\MobileSDK3\KapselSDK\plugins\logon\www\common\assets\i18n\i18n.properties
or
platforms\android\assets\www\smp\logon\i18n\i18n.properties

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.

fields: {    user : {        uiKey:'FLD_USER'    },    password : {        uiKey:'FLD_PASS',        type: 'password'    },    serverHost : {        uiKey:'FLD_HOST',    },    serverPort : {        uiKey:'FLD_PORT',        type: 'number',    }
}

The Logon plugin's screens use the UI library named SAP UI5.  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 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 SAP UI5.

www\smp\logon\ui\css
www\smp\logon\ui\image
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.

Note, 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

Back to Getting Started With Kapsel