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.
There are a couple of options to prevent CORS errors from occurring.
Option 1 is to serve register.html and datajs-1.1.2.min.js from the web server that is part of the SMP Server. To do so, copy these files to the below folder.
C:\SAP\MobilePlatform3\Server\webapps\sapui5Then access register.html using http://ip_address_of_smp_server:8080/sapui5/register.html.
Option 2 is to disable CORS checks in Chrome by restarting Chrome after all instances of it are closed with the following flag.
"C:\Program Files (x86)\Google\Chrome\Application\chrome.exe" --disable-web-securityNote, a warning message should be shown indicating that the option was set when Chrome is restarted.
Enter your user name and password for the OData service.
https://sapes1.sapdevcenter.com/sap/opu/odata/IWFND/RMTSAMPLEFLIGHT
The registration ID can be seen in the management cockpit following a successful registration.
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), SAML, 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. When used the AuthProxy plugin, a basic authentication challenge made to a proxied connection on the SMP server can be handled automatically by the AuthProxy plugin using the stored registration credentials.
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. 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 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 C:\SAP\MobileSDK3\KapselSDK\docs\api\sap.Logon.html or Using the Logon Plugin.
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 create C:\Kapsel_Projects\LogonDemo com.mycompany.logon LogonDemo
cd C:\Kapsel_Projects\LogonDemo
cordova platform add android
or
cordova create ~/Documents/Kapsel_Projects/LogonDemo com.mycompany.logon LogonDemo
cd ~/Documents/Kapsel_Projects/LogonDemo
cordova platform add ios
Note that the platform add can also take a --searchpath argument which can be useful when adding a platform to a project that already includes Kapsel plugins. - 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 of Xcode.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
or
cordova plugin add %KAPSEL_HOME%/plugins/logon --searchpath %KAPSEL_HOME%/plugins
on a Mac
cordova plugin add kapsel-plugin-logon --searchpath $KAPSEL_HOME/plugins
or
cordova plugin add $KAPSEL_HOME/plugins/logon --searchpath $KAPSEL_HOME/plugins
cordova plugin add cordova-plugin-console
An added plugin can be remove by calling
cordova plugin remove plugin_id
Note that there is a known problem (Cannot read property 'buffer' of undefined) with not being able to remove the logon plugin from a project when the iOS platform is added. See also Plugin Un-install fails for iOS with plist strings.
Note that it is possible to specify the searchpath for the entire project rather than specifying each time a new platform or Kapsel plugin is added. This can be done by creating a JSON file that includes the searchpath.
C:\Kapsel_Projects\LogonDemo\.cordova
{
"plugin_search_path": "C:/SAP/MobileSDK3/KapselSDK/plugins/"
}
- A list of the plugins now included in the project can be seen by entering the below command.
cordova plugins
cordova-plugin-console 1.0.1 "Console"
cordova-plugin-device 1.0.1 "Device"
cordova-plugin-whitelist 1.1.1 "Whitelist"
kapsel-plugin-authproxy 3.10.0 "AuthProxy"
kapsel-plugin-corelibs 3.10.0 "CoreLibs"
kapsel-plugin-inappbrowser 0.6.0-patched "InAppBrowser"
kapsel-plugin-logon 3.10.0 "Logon"
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\kapsel-plugin-logon\plugin.xml
- If needed, follow the steps shown in Configuring a Kapsel App in the Management Cockpitto create an Application with the application id of
com.mycompany.logon
- Replace www\index.html with the contents of register2.html.Edit the serverHost, user, and password variables.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\kapsel-plugin-logon\www\common\modules\Utils.js
- Prepare, build and deploy the app with the following commands.
cordova run android
or
cordova run ios
- Alternatively, use Android Studio or Xcode to deploy and run the project after first running the below command.
cordova prepare
- Note, if you are using Xcode 7 and SP10 of the SDK, you may see the following error when linking the project.
kapsel-plugin-corelibs/libConnectiviity.a does not contain bitcode.
To correct this, disable bitcode for this target.
Choose Project > Build Settings > All > Build Options > Enable Bitcode > No - 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 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.
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.
- 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.
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.
- Prepare, build and deploy the app with the following command.
cordova run android
or
cordova run ios
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.
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.
- Note iOS apps built using the iOS 9 SDK by default do not allow communications using HTTP and must use at least TLS 1.2. For additional details see the following technote. App Transport Security Technote. Configuring the SMP server using HTTPSis covered later in this guide. If you wish to temporarily allow HTTP connections from your application on iOS (HTTP connections are not secure) add the following to the bottom of your applications plist file. In Xcode, expand Resources folder, right click on LogonDemo-Info.plist and choose Open As > Source Code. Paste the following above last two lines (</dict> </plist>) of the file.
<key>NSAppTransportSecurity</key>
<dict>
<!--Include to allow all connections (For development only, remove before release)-->
<key>NSAllowsArbitraryLoads</key>
<true/>
</dict>
SAPUI5 Used by the Logon Plugin
The Logon plugin uses the SAPUI5library when displaying the Registration and Passcode screens. The SAPUI5 library is located in the following folder.
C:\Kapsel_Projects\LogonDemo\plugins\kapsel-plugin-logon\www\common\assets\ui\resources\sapIf 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/resourcesand remove the resources\sap 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\plugins\kapsel-plugin-logon\www\common\assets\ui\iab.html
<script type="text/javascript" src="https://sapui5.netweaver.ondemand.com/resources/sap/ui/thirdparty/jquery/jquery-1.11.1.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>
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
C:\Kapsel_Projects\LogonDemo\plugins\kapsel-plugin-logon\www\common\assets\ui\resourcesfolder to the
C:\Kapsel_Projects\LogonDemo\wwwfolder and then modify the three references in the below file to use ../../../resources as shown below.
C:\Kapsel_Projects\LogonDemo\plugins\kapsel-plugin-logon\www\common\assets\ui\iab.html
<script type="text/javascript" src="../../../resources/sap/ui/thirdparty/jquery/jquery-1.11.1.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>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_en.propertiesSee also the Localization section of this guide.
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
C:\Kapsel_Projects\LogonDemo\plugins\kapsel-plugin-logon\www\common\modules\StaticScreens.jsFind the SCR_REGISTRATION screen and reorder/hide/show fields using visible:false or simply remove unneeded entries. Note some fields such as FLD_HOST and FLD_IS_HTTPS 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',
},
https: {
uiKey:'FLD_IS_HTTPS',
type: 'switch',
'default':false,
visible:false
}
}
Note the registration screen no longer displays these fields.
A developer can further customize the screens shown by the Logon plugin by adding the below code to index.html. This code will enable the passcode screen and optionally the registration 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;
}
Prepare, build and deploy the app with the following command.
cordova run android
or
cordova run ios
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.jswhich 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.jsThe following attached iab.html file is a minimal example that demonstrates how this could be accomplished. Replace C:\Kapsel_Projects\LogonDemo\plugins\kapsel-plugin-logon\www\common\assets\ui\iab.html with the above file.
Delete the folders containing SAPUI5.
C:\Kapsel_Projects\LogonDemo\plugins\kapsel-plugin-logon\www\common\assets\ui\css
C:\Kapsel_Projects\LogonDemo\plugins\kapsel-plugin-logon\www\common\assets\ui\img
C:\Kapsel_Projects\LogonDemo\plugins\kapsel-plugin-logon\www\common\assets\ui\resources
Delete the following two files which are now implemented in iab.html.
C:\Kapsel_Projects\LogonDemo\plugins\kapsel-plugin-logon\www\common\assets\ui\LogonForm.js
C:\Kapsel_Projects\LogonDemo\plugins\kapsel-plugin-logon\www\common\assets\ui\Notification.js
C:\Kapsel_Projects\LogonDemo\plugins\kapsel-plugin-logon\www\common\assets\ui\iab.js
Deploy and run the project and notice that the Logon pages are now shown without a UI library.
Back to Getting Started With Kapsel
- SAP Managed Tags:
26 Comments
