AuthProxy

The AuthProxy plugin is useful if a Kapsel app needs to provide a certificate to the server to identify itself.  This is known as client authentication.  An example of this is if you are required to provide a client certificate as part of the onboarding process to register with an application or perhaps to access an OData source.  This occurs mostly in Business to Business (B2B) applications.  This is different from most business to consumer or B2C websites where it is only the server that authenticates itself to the client with a certificate that has been signed by a certificate authority (CA) such as an online banking site. For additional details on the AuthProxy plugin see the JavaScript file in a project that includes this plugin at

project_name\www\plugins\com.sap.mp.cordova.plugins.authproxy\www\authproxy.js

or the JS Documentation at Kapsel AuthProxy API Reference

Before continuing, it may be helpful to review the materials on HTTPS in the Security Appendix.

The following two examples demonstrate the functionality of the AuthProxy plugin.

Using Client Certificates

This example will demonstrate how to use the AuthProxy plugin to register with the SMP 3.0 server using a client certificate and how to use a client certificate in a request to access an OData endpoint.  The certificate authority used to sign the client certificate will need to be trusted by the SMP 3.0 server.  Since this example uses HTTPS, the SMP 3.0 server will need to be configured with a server certificate and the device or emulator running the mobile app will have to trust the certificate used to sign the server certificate.  The certificate authority used in this example to sign both the client and server certificate is called Server CA and is available from SAP for free to sign certificates for a period of eight weeks.

Note this example is not using the Logon plugin to perform the registration as the Logon plugin currently requires using SAP Afaria to provide a client certificate.  See SAP Afaria and Kapsel for additional details on how to use client certificates with the Logon plugin.

This example can be run on an Android device or emulator or an iOS device or an iOS 7 simulator.  The server certificate must be installed onto the device's system store which is not possible in an iOS emulator prior to version 7.0.

The first step will be to create the server and client certificates.  The SMP 3.0 server stores its certificates in a file named smp_keystore.

C:\SAP\MobilePlatform3\Server\configuration\smp_keystore.jks

The keytool command

which is part of the Java SDK or JRE stores public and private keys in a keystore or jks file.

For the two genkeypair commands below, note the cn or common name values.  For the server certificate enter the fully qualified domain name of the SMP 3.0 server and for the client certificate enter your first and last name.

keytool -genkeypair -alias serverkey -dname cn=YKFN00528072A.dhcp.ykf.sap.corp,o=mycompany.com,c=CA -keystore smp_keystore.jks -storepass changeit -keyalg RSA -validity 360 -keysize 2048
keytool -genkeypair -alias clientkey -dname cn="Dan van Leeuwen",o=mycompany.com,c=CA -keystore client.jks -storepass changeit -keyalg RSA -validity 360 -keysize 2048

• The server and client certificates must be signed by a certificate authority.  The following steps demonstrate how to have the SAP Certificate Authority sign the certificates (free and valid for eight weeks).  Alternatively the certificates can be made valid for one year with a purchase.
  
  There is also an SAP internal certificate authority that can be used which is available at https://security.wdf.sap.corp/onlineCA/
  
  Download the SAP SSL Test Server CA Certificate from SAP Trust Center Service - Root Certificates.
  
  The file is named getCert.cer by default.  Rename it to SAPServerCA.cer.
  Import it into the smp_keystore.jks and client.jks stores.

  keytool -importcert -alias sapserverca -file SAPServerCA.cer -keystore smp_keystore.jks -storepass changeit
  keytool -importcert -alias sapserverca -file SAPServerCA.cer -keystore client.jks -storepass changeit

  Generate a certificate signing request (CSR).

  keytool -certreq -keyalg RSA -alias serverkey -file server.csr -keystore smp_keystore.jks -storepass changeit

  Open the webpage SSL Test Server Certificates and click on the Test it Now button.
  Open server.csr and copy the contents to the form, select other web server and click continue.
  Copy the resultant string and place it in a file named server.rsp.
  The below command will import the signed certificate into the keystore.

  keytool -importcert -alias serverkey -file server.rsp -keystore smp_keystore.jks -storepass changeit

  At this point the certificate serverkey is now signed by the SAP SSL Test Server Certificate Authority as shown below.
  
  
  Perform the same set of steps for the client certificate.
  

  keytool -certreq -keyalg RSA -alias clientkey -file client.csr -keystore client.jks -storepass changeit

  Open the webpage SSL Test Server Certificates and click on the Test it Now button.
  Open client.csr and copy the contents to the form, select other web server and click continue.
  Copy the resultant string and place it in a file named client.rsp.
  The below command will import the signed certificate into the keystore.

  keytool -importcert -alias clientkey -file client.rsp -keystore client.jks -storepass changeit

• Copy the client's public key to smp_keystore.jks so that the server can authenticate the client.

  keytool -exportcert -file client.cer -keystore client.jks -storepass changeit -alias clientkey
  keytool -importcert -file client.cer -keystore smp_keystore.jks -storepass changeit -alias clientkey

• The contents of each keystore can be viewed using the following commands.

  keytool -list -v -keystore smp_keystore.jks -alias serverkey -storepass changeit
  keytool -list -v -keystore smp_keystore.jks -alias clientkey -storepass changeit
  keytool -list -v -keystore client.jks -alias clientkey -storepass changeit

• Create a new configuration for the SMP server to use port 443 with mutual authentication by modifying default-server.xml and adding the following entry.

  Server\config_master\org.eclipse.gemini.web.tomcat\default-server.xml<Connector protocol="com.sap.mobile.platform.coyote.http11.SapHttp11Protocol"       port="443" maxThreads="200"        scheme="https" secure="true" SSLEnabled="true"        keyAlias="serverkey"       clientAuth="true" sslProtocol="TLS"/>

• Both the client certificate (stored in the file client.p12 containing the public and private keys) and the certificate authority's certificate (SAPServerCA.cer) must be added to the mobile device.  SAPServerCA.cer should be added to the device's trust store.  The client certificate in this example for Android is placed in a location the application can access it from.  It could also be added to the device's trust store but on Android this results in the user having to accept that the application is using a certificate from the trust store.
  
  The public and private key of the client certificate must be imported to the mobile device so the PKCS12 format is used.

  keytool -importkeystore -srckeystore client.jks -srcstorepass changeit -srcalias clientkey -destkeystore client.p12 -deststorepass changeit -deststoretype PKCS12

  For Android

  adb push SAPServerCA.cer /mnt/sdcard/
  adb push client.p12 /mnt/sdcard/
  adb shell
  cd /mnt/sdcard
  ls
  exit

  Install SAPServerCA.cer to the Android trusted credential store via

  Settings -> Personal -> Security -> Install from SD card (requires Android 4.0+)

  For iOS
  When using the iOS 7.0 emulator, the SAPServer.cer certificate can be installed by simply dragging and dropping it onto the emulator.
  
  When using an iOS device the SAPServer.cer certificate can be installed into the device's trusted store by sending it via an e-mail, opening the device browser to a webpage that contains a link to the certificate, or by using the iPhone Configuration Utility.  The certificate can be viewed and uninstalled under

  Settings -> General -> Profiles

  The client.p12 certificate must be added as part of the application by right-clicking on the Resource folder, select the menu item Add Files to ‘Project Name’, select the certificate p12 file(s), and check the option of Copy items into destination group’s folder (if needed). Click the Add button to add client.p12 into the Xcode project.
  
  The client certificate can either be accessed directly from the file system via

  clientCert = new sap.AuthProxy.CertificateFromFile("/mnt/sdcard/client.p12", "changeit", "clientkey"); //Android
  clientCert = new sap.AuthProxy.CertificateFromFile("client.p12", "changeit", "clientkey"); //iOS

  On Android, the client certificate can be accessed from the trusted credential store. On iOS, the certificate must first be loaded into the application's keychain via a call to CertificateFromFile before using CertificateFromStore.
  

  clientCert = new sap.AuthProxy.CertificateFromStore("clientkey");

• In addition to accessing the certificate from the file system and the device's secure store, the client certificate can be provisioned to the device using SAP Afaria and then accessed from SAP Afaria using the Logon plugin using

  sap.AuthProxy.CertificateFromLogonManager("clientKey")

• Create a new project which will perform mutual authentication to the SMP 3.0 server.

  cordova -d create C:\Kapsel_Projects\AuthProxyDemo com.mycompany.authproxy AuthProxyDemo
  cd C:\Kapsel_Projects\AuthProxyDemo
  cordova -d platform add android
  
  cordova -d create ~/Documents/Kapsel_Projects/AuthProxyDemo com.mycompany.authproxy AuthProxyDemo
  cd ~/Documents/Kapsel_Projects/AuthProxyDemo
  cordova -d platform add ios

• Add the Cordova console plugin and AuthProxy plugin.

  cordova plugin add https://git-wip-us.apache.org/repos/asf/cordova-plugin-console.git
  cordova -d plugin add C:\SAP\MobileSDK3\KapselSDK\plugins\authproxy 
  
  cordova -d plugin add ~/SAP/MobileSDK3/KapselSDK/plugins/authproxy 

• Follow the steps shown in Configuring a Kapsel App in the Management Cockpit to create an Application with the application id of

  com.mycompany.authproxy 

  Set the endpoint to be

  https://sapes1.sapdevcenter.com/sap/opu/odata/IWFND/RMTSAMPLEFLIGHT

  The alias name should match the alias name of a certificate in the smp_keystore.jks that is used to access the OData source.
  
  
  Note that the operation will be processed in the context of the client's certificate (The SSL_CLIENT_CERT header is passed along in the request).
  
  Create a new security provider and add an x.509 User Certificate authentication provider.  Note that since the values for Trusted Cert Store are left blank they default to the default server's keystore file (smp_keystore.jks).
  
• Replace www\index.html with the contents of index.html.zip.  Either right-click and choose Save link as or View page source after clicking on the link and copy and paste the contents.
  
  Place a copy of datajs-1.1.1.min.js into the www folder
• Copy the files to the platform directory by running

  cordova -d prepare

• Use the Android IDE or Xcode to deploy and run the project.
  
  
  In order to successfully make OData requests using mutual authentication, the backend OData server would need to be configured which is not covered in this guide.
  
  
• Note, on Android if the error Certificate file does not exist occurs and the file does exist at the location specified, add the WRITE_EXTERNAL_STORAGE permission to the AndroidManifest.xml file as shown below.

  <uses-permission android:name="android.permission.WRITE_EXTERNAL_STORAGE" />

  Alternatively modify Settings -> Developer Options -> Protect SD Card -> Uncheck

Making an OData request through the AuthProxy Plugin

On, iOS there is an issue if an incorrect user id and password are provided via HTTPS.  The request will hang without invoking an error callback method.  This problem is not present if the AuthProxy plugin is used to make the request.

To illustrate this, the LogonDemo project will be modified to use the AuthProxy plugin.

• Run the sample from the Logon Plugin section.
  Choose Unregister, Register, provide an invalid username or password, and then Read.  Notice that no error message occurs and no data is returned.
  
  
• Open a command prompt or terminal session to the LogonDemo folder.
• Add the AuthProxy plugin

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

• Modify the www\index.html and change the username or password to be incorrect.
• Add the following line of code to the start of the read method.  This call enables the AuthProxy plugin to handle the OData request calls made by the datajs library.

  OData.defaultHttpClient = sap.AuthProxy.generateODataHttpClient();  //Works around a bug where the error callback is not called if an invalid user id or password is provided.  

• Copy the contents of the www folder to the platform specific www folder of the project using prepare.

  cordova prepare android
  
  cordova prepare ios

• Use the Android IDE or Xcode to deploy and run the project.  Notice that this time the error callback handler is correctly called.
  

The below links contain some additional information on SSL, certificates, configuring a Tomcat server to use client authentication and how to add an OData producer to Tomcat.
Mutual Authentication
Tomcat SSL How To
Tomcat Mutual Authentication
OData4J
Hosting OData4J in Tomcat

Back to Getting Started With Kapsel