How To... Use the Kapsel Logon Plugin

www.sap.com/contactsap

www.sdn.sap.com/irj/sdn/howtoguides

How To... Use the Kapsel Logon Plugin

Applicable Releases:SAP Mobile Platform 3.0

Version 1.1October 2014

SAP How-to GuideMobility

SAP Mobile Platform

Copyright 2015 SAP AG. All rights reserved.No part of this publication may be reproduced or transmitted in any form or for any purpose without the express permission of SAP AG. The information contained herein may be changed without prior notice. Some software products marketed by SAP AG and its distributors contain proprietary software components of other software vendors. Microsoft, Windows, Excel, Outlook, and PowerPoint are registered trademarks of Microsoft Corporation. IBM, DB2, DB2 Universal Database, System i, System i5, System p, System p5, System x, System z, System z10, System z9, z10, z9, iSeries, pSeries, xSeries, zSeries, eServer, z/VM, z/OS, i5/OS, S/390, OS/390, OS/400, AS/400, S/390 Parallel Enterprise Server, PowerVM, Power Architecture, POWER6+, POWER6, POWER5+, POWER5, POWER, OpenPower, PowerPC, BatchPipes, BladeCenter, System Storage, GPFS, HACMP, RETAIN, DB2 Connect, RACF, Redbooks, OS/2, Parallel Sysplex, MVS/ESA, AIX, Intelligent Miner, WebSphere, Netfinity, Tivoli and Informix are trademarks or registered trademarks of IBM Corporation. Linux is the registered trademark of Linus Torvalds in the U.S. and other countries. Adobe, the Adobe logo, Acrobat, PostScript, and Reader are either trademarks or registered trademarks of Adobe Systems Incorporated in the United States and/or other countries. Oracle is a registered trademark of Oracle Corporation. UNIX, X/Open, OSF/1, and Motif are registered trademarks of the Open Group. Citrix, ICA, Program Neighborhood, MetaFrame, WinFrame, VideoFrame, and MultiWin are trademarks or registered trademarks of Citrix Systems, Inc. HTML, XML, XHTML and W3C are trademarks or registered trademarks of W3C, World Wide Web Consortium, Massachusetts Institute of Technology. Java is a registered trademark of Sun Microsystems, Inc. JavaScript is a registered trademark of Sun Microsystems, Inc., used under license for technology invented and implemented by Netscape. SAP, R/3, SAP NetWeaver, Duet, PartnerEdge, ByDesign, SAP BusinessObjects Explorer, StreamWork, and other SAP products and services mentioned herein as well as their respective logos are trademarks or registered trademarks of SAP AG in Germany and other countries. Business Objects and the Business Objects logo, BusinessObjects, Crystal Reports, Crystal Decisions, Web Intelligence, Xcelsius, and other Business Objects products and services mentioned herein as well as their respective logos are trademarks or registered trademarks of Business Objects Software Ltd. Business Objects is an SAP company.Sybase and Adaptive Server, iAnywhere, Sybase 365, SQL Anywhere, and other Sybase products and services mentioned herein as well as their respective logos are trademarks or registered trademarks of Sybase, Inc. Sybase is an SAP company.

All other product and service names mentioned are the trademarks of their respective companies. Data contained in this document serves informational purposes only. National product specifications may vary. The information in this document is proprietary to SAP. No part of this document may be reproduced, copied, or transmitted in any form or for any purpose without the express prior written permission of SAP AG. This document is a preliminary version and not subject to your license agreement or any other agreement with SAP. This document contains only intended strategies, developments, and functionalities of the SAP product and is not intended to be binding upon SAP to any particular course of business, product strategy, and/or development. Please note that this document is subject to change and may be changed by SAP at any time without notice. SAP assumes no responsibility for errors or omissions in this document. SAP does not warrant the accuracy or completeness of the information, text, graphics, links, or other items contained within this material. This document is provided without a warranty of any kind, either express or implied, including but not limited to the implied warranties of merchantability, fitness for a particular purpose, or non-infringement. SAP shall have no liability for damages of any kind including without limitation direct, special, indirect, or consequential damages that may result from the use of these materials. This limitation shall not apply in cases of intent or gross negligence. The statutory liability for personal injury and defective products is not affected. SAP has no control over the information that you may access through the use of hot links contained in these materials and does not endorse your use of third-party Web pages nor provide any warranty whatsoever relating to third-party Web pages. SAP How-to Guides are intended to simplify the product implementtation. While specific product features and procedures typically are explained in a practical business context, it is not implied that those features and procedures are the only approach in solving a specific business problem using SAP NetWeaver. Should you wish to receive additional information, clarification or support, please refer to SAP Consulting.Any software coding and/or code lines / strings (Code) included in this documentation are only examples and are not intended to be used in a productive system environment. The Code is only intended better explain and visualize the syntax and phrasing rules of certain coding. SAP does not warrant the correctness and completeness of the Code given herein, and SAP shall not be liable for errors or damages caused by the usage of the Code, except if such damages were caused by SAP intentionally or grossly negligent.DisclaimerSome components of this product are based on Java. Any code change in these components may cause unpredictable and severe malfunctions and is therefore expressively prohibited, as is any decompilation of these components.Any Java Source Code delivered with this product is only to be used by SAPs Support Services and may not be modified or altered in any way.

Document HistoryDocument VersionDescription

1.00First official release of this guide

1.10Upgraded for SMP 3.0 SP4 and SDK 5

Typographic ConventionsType Style Description

Example TextWords or characters quoted from the screen. These include field names, screen titles, pushbuttons labels, menu names, menu paths, and menu options.Cross-references to other documentation

Example textEmphasized words or phrases in body text, graphic titles, and table titles

Example textFile and directory names and their paths, messages, names of variables and parameters, source text, and names of installation, upgrade and database tools.

Example textUser entry texts. These are words or characters that you enter in the system exactly as they appear in the documentation.

Variable user entry. Angle brackets indicate that you replace these words and characters with appropriate entries to make entries in the system.

EXAMPLE TEXTKeys on the keyboard, for example, F2 or ENTER.

IconsIconDescription

Caution

Note or Important

Example

Recommendation or Tip

Table of Contents1.Business Scenario12.Background Information13.Prerequisites14.Step-by-Step Procedure24.1Create the Cordova Project24.2Add the Kapsel Logon Plugin24.3Implement Logon24.4Prepare the Platforms and Open the Project and Test5

Business ScenarioYou want to create a Cordova based application that logs the user onto SAP and retrieves some flight data that is then displayed to the user. To do this you decide to use the Kapsel Logon plugin along with SAP UI5.

Background InformationThe logon plugin is a component of the SAP Mobile Application Framework (MAF) exposed as a Cordova plugin. The basic idea is that it provides a login screen where the user can enter the values needed to connect to an SMP 3.0 server 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. In an OData based SMP 3.0 application, a client must onboard or register with the SMP 3.0 server to receive an application connection ID for a particular app. The application connection id must be sent along with each request that is proxied through the SMP 3.0 server to the OData producer.

Prerequisites1. Windows or Mac OS X system.1. Apache Cordova 3.5 installed1. Have installed the SAP Mobile SDK 3.0 SP51. Java SDK Installed - http://www.oracle.com/technetwork/java/javase/downloads/index.html3. JAVA_HOME environment variable defined.1. Eclipse Kepler1. Android Eclipse Plugins1. Android SDK (API 19) Installed - http://developer.android.com/sdk/index.html1. Android SDK added to PATH environment variable.7. Add \tools to PATH environment variable.7. Command to do so on OS X: export PATH=$PATH:/tools1. Android Emulator (API 19) downloaded and configured.1. Xcode installed with iOS 6+ configured (Optional)1. Xcode Command Line Tools installed (Optional comes with GIT and ANT which are required).1. Windows GIT installed: http://msysgit.github.io 1. Windows ANT installed: http://ant.apache.org/manual/install.html 1. Install Node.js - http://nodejs.org/download/ - Node.js and its package manager npm can be used to install Apache Cordova. The version installed can be seen by the following node command13. node v13. Configure npm to use your http proxy if need be using following commands:1. npm config set proxy http://proxy_host:port1. npm config set https-proxy http://proxy_host:port 13. Config GIT to use your http proxy if need be using the following commands:2. git config --global http.proxy http://proxy_host:port2. git config --global https.proxy http://proxy_host:port

Step-by-Step ProcedureThe following steps will guide you through creating a Cordova project, adding the Kapsel Logon plugin to it, and the coding required to use it.Configure the application in SAP Mobile PlatformNavigate to Start Menu -> SAP Tools [SMP] -> Start SAP Mobile Platform Server to start the server.Once the server is started, open the SAP Management Cockpit by clicking the SAP Management Cockpit icon on DesktopAccept the security warning and login to the server cockpit with the credentials: Username: smpAdmin Password: s3pAdmin

Go to the Applications tab and click New to configure a new application.

In the New Application view, provide the details for application configuration as shown below. The application ID will be com.sap.flight.kapsel, choose Hybrid as application Type. Click on Save after entering the details.

In the Overview pane, navigate to the Back End tab to configure the gateway backend from which we will obtain Flight information. Enter the following details:Endpoint: http://wdflbmt0783.wdf.sap.corp:51080/sap/opu/odata/IWFND/RMTSAMPLEFLIGHT/

Navigate to authentication tab. We will use HTTP authentication of the Back End to authenticate and register users with SMP. Enter the Profile Name as flightauth. Under authentication providers, click Add and select the Authentication Provider HTTP/HTTPS Authentication. Provide the Back End endpoint under URL: http://wdflbmt0783.wdf.sap.corp:51080/sap/opu/odata/IWFND/RMTSAMPLEFLIGHT/

Save the Application. The status of the configured application should be

Create the Cordova Project...Open a Command Prompt / Terminal.CD to the Kapsel working directory (your instructor should tell you where this is, or create your own if you have the exercise materials associated with this guide).Run the Cordova create project command:cordova -d create LogonExercise com.sap.logon.exercise LogonExercise "{\"plugin_search_path\":\"D:/SAP/MobileSDK3/KapselSDK/plugins/\"}" NoteThe plugin_search_path points to the local repository from where Kapsel plugins will be installed.

Add the Android Platform to your project. CD into the LogonExercise directory: cd LogonExerciseRun the command to add the Android platform: cordova -d platform add android NoteIf you have an OS X system, you can add the iOS platform: cordova -d platform add ios

Add the Kapsel Logon Plugin...Make sure you are in the LogonExecise directory.Add the standard Cordova plugins required: cordova plugin add https://git-wip-us.apache.org/repos/asf/cordova-plugin-device.gitcordova plugin add https://git-wip-us.apache.org/repos/asf/cordova-plugin-console.gitAdd the Kapsel Logon plugin:cordova -d plugin add com.sap.mp.cordova.plugins.logon NoteThe Logon plugin has dependencies to other kapsel plugins and open source Apache Cordova plugins. Watch the output of the command as it executes to see the plugins it is pulling in.

Check the list of installed plugins with the command: cordova pluginsSimple as that.

Implement Logon..

Copy the contents of index.html from logon_ex folder to index.html under LogonExercise/www folder. This is the template you will use to implement your coding. All you have to do is implement the logon logic, but you should also take a close look at the readAirlines() method to see how the OData services is called using the SAPUI5 OData object.Open the index.html file (found in folder LogonExercise/www) and find the function init(){} methodit should look like the following:function init() { //Implement Logon //TODO: Create a variable with the application ID value //TODO: Create a context object with some default logon info //TODO: initialize the logon}

First TODO create a variable with the application ID as the value. The application ID is the ID of the hybrid app you created on the SMP 3.0 server.var appId = "com.sap.flight.kapsel";

Second TODO create a context object with some default logon info. This step is optional but it will make it easier for us to test later on. We will default the logon to use a host IP address, http port and to not use HTTPS.var context = { "serverHost": " Your SMP 3.0 Host IP ", //SMP 3.0 Server hostname or IP "serverPort": "8080", //SMP 3.0 Server port "https": "false", //Use HTTPS?};

Now lets start the logon process by calling sap.Logon.init() method. This Logon functionality comes from the Logon Plugin you added earlier. // Init the Logon componentsap.Logon.init(logonSuccessCallback, errorCallback, appId, context, null);

ImportantNotice the input values logonSuccessCallback, errorCallback these are functions that will be called on success and failure. The next step is to implement these two methods.

Your function init() {} method should now look like the following:function init() {

//Application ID on SMP 3.0 var appId = "com.sap.flight.kapsel"; // Optional initial connection context // Sets defaults on MAF Login Component var context = { "serverHost": "Your SMP 3.0 Host IP", //SMP 3.0 Server hostname or IP "serverPort": "8080", //SMP 3.0 Server port "https": "false", //Use HTTPS? }; // Init the Logon component sap.Logon.init(logonSuccessCallback, errorCallback, appId, context, null); }

Find the logonSuccessCallback() function. It should look like the following:

function logonSuccessCallback(result) { //TODO: check if result is not null, if not then... //set applicationContext equal to result //call the readAirlines() function }

Create an if statement checking that result isnt null.function logonSuccessCallback(result) { if (result) { }}

Inside the if statement set the global applicationContext variable equal to result. // Set the application Context // This has all the good stuff in it // Sent back by the SMP 3.0 server applicationContext = result;

Inside the if statement call the readAirlines() function. // Read the Airlines from Gateway and display readAirlines();

Your logonSuccesCallback() function should now look like the following:function logonSuccessCallback(result) { // If result is not null, we have successful login if (result) { // Set the application Context // This has all the good stuff in it // Sent back by the SMP 3.0 server applicationContext = result; // Read the Airlines from Gateway and display readAirlines(); }}

Now find and implement the errorCallback() function. It should look like the following:function errorCallback(e) { //TODO: Display an Alert of the error}

All you need to do is pop an error showing the error details. Your errorCallback() function should now look like the following:function errorCallback(e) { //Show an alert alert("An error occurred"); alert(JSON.stringify(e));}

Save your changes.Open config.xml found in the folder LogonExercise.Above the ending tag enter the following timeout config (sets timeout to 2 minutes for loading a resource):

NoteThis timeout config is only needed due to the slowness of the Android Emulator on virtualized OS.

Thats it for the implementation. Save your changes!

Prepare the Platforms and Open the Project and Test...Make sure you are in the LogonExercise directory.Run the command to prepare the android platform: cordova -d prepare NoteFor preparing a specific platform: cordova -d prepare

Open the corresponding Android Project in Eclipse.Run the application. Note: this could take some time to deploy and start the application in the Android Emulator.Once the application is started for the first time you should see something like the following:

Notice the Host and Port are pre populated and that the Secure switch it set to Off. Set the Host value to the host name of where the SMP 3.0 server is installed. If it is installed on the localhost where you are running the emulator use reserved IP address 10.0.2.2 (this IP is resevered by the Android emulator and points to the local OS that spawned the emulator).

Enter in the username and password for the SAP Gateway system you are connecting to. In this demo the Back End credentials are:Username: gwdemoPassword: welcomeClick the Register button. At this point the user is being authenticated against the Gateway system and then registered with SMP 3.0.After a successful first logon you should now see the following requesting you to enter a secure passcode:

Either enter a passcode or click the Disable Passcode button and then click Submit.

Enter a security passcode that you will remember it must be 8 characters in length.Click the Submit button.You should now see the list of Flights displayed:

Congrats! You have successfully used the Kapsel Logon plugin!Extra credit logon to the SMP 3.0 server and take a look at the registered user there.

How To... Use the Kapsel Logon Plugin

March 201512