AuthProxy Plugin

The AuthProxy plugin specifies to include a certificate in a HTTPS request that identifies the client to the server, also allows the server to verify the identity of the client. An example of where you might need mutual authentication is in the onboarding process, when you register with an application, or, to access an OData producer. You can make HTTPS requests with no authentication, with basic authentication, or by using certificates. Supported certificate sources include file, system key manager, and Afaria.

Interception of Web Requests and Handling Challenges

The AuthProxy plugin can intercept all web and data requests and handle basic authentication and X509 certificate challenges inside Cordova's embedded WebView. By default the WebView does not handle these challenges correctly. When the server challenges the client side authentication, the AuthProxy plugin shows the proper UI to let the user enter a username/password, or select from a list of installed certificates, for answering the challenge. Interception of web requests with Android devices is not particularly recommended, unless you have such a requirement. You can enable or disable interception of web requests using the SAPKapselHandleHttpRequests preference setting in config.xml. The default value of this preference for Android is false for backward compatibility. To enable the feature, edit config.xml and change the value to true. The default value of this preference for iOS is true.

On Android devices, there is the concept of an HTTPS conversion host, which is a list of host names for which AuthProxy always sends the request as HTTPS (regardless of the protocol of the intercepted request). The JavaScript can use HTTP in the URL (knowing that AuthProxy will send the request with HTTPS), and AuthProxy can still intercept the request and handle it. You can use the JavaScript function sap.AuthProxy.addHTTPSConversionHost(successCallback, errorCallback, url) to add a hostname to the list of HTTPS conversion hosts. Note that you do not need to do any configuration for SAP Fiori Client, which handles the HTTPS conversion host automatically.

For requests with basic authentication, if the credentials are not provided with the request’s open method, then if the application is registered with SAP Mobile Platform Server using basic authentication, the AuthProxy plugin uses the SAP Mobile Platform registration's credentials to authenticate the request. If there is no SAP Mobile Platform Server or if no valid credentials are available, then a dialog box prompts the user to enter a user name and password. The correct credentials are stored in the Logon Plugin datavault and are automatically used when presented with a server challenge. If the credentials are not correct, the user will be prompted to enter credentials until they are correct, or the user presses cancel.

For requests with an X.509 certificate challenge, a dialog box shows the list of client certificates already installed, and the user can select the correct certificate to answer the the server side challenge. The user is only prompted again for a certificate if the user entered an invalid certificate.

Note

On iOS, the client certificate must be already installed in the application's keychain, before running the application.
On Windows, add certificate to the client application and pass it to the certificate provider API.

Automatic Selection of Client Certificate

The AuthProxy plugin allows the client certificate to be automatically selected for mutual authentication without requiring the user to manually pick a client certificate from the available certificate list.

Instead of having an application keychain like iOS, the Android counterpart is the system keychain. It is not possible to automatically select a certificate from the system keychain the first time - the application needs permission from the user to use a keychain certificate. Android uses SharedPreferences to store the aliases the application has permission to use. When the application gets restarted, it remembers from previous sessions whether it has permission to use an alias and will not show the certificate picker unless it has to.

This method in the AuthProxy plugin allows you to configure this behavior in the application:

setAutoSelectCertificateConfig(successCB, errorCB, autoSelectSingleCert)

The parameter, autoSelectSingleCert, is a boolean type.

The default value for this property is false.

If you specify this property as true, and if there is only one client certificate available, the single available single certificate will always get selected automatically. This setting is similar in concept to the option in the Internet Explorer browser, "Do not prompt for client certificate selection when only one certificate exists."

For an SAP Fiori Client project, you can specify this property as a parameter in the Fiori URL, autoSelectSingleCert. You can specify this parameter in the appconfig.js file. This setting is then persisted in a similar way as the other application settings, such as Demo Mode, by the Application Preferences plugin.

Sending Requests

There are these functions for sending requests:

get = function (url, header, successCB, errorCB, user, password, timeout, certSource). This is a convenience function and provides no additional functionality compared to the sendRequest function. It just calls the sendRequest function with the method set to GET and no requestBody.
sendRequest = function (method, url, header, requestBody, successCB, errorCB, user, password, timeout, certSource).
sendRequest2 = function (method, url, header, requestBody, successCB, errorCB, [timeout], [authConfig] )

Constructor Functions

There are three constructor functions to make objects that you can use for certificates:

CertificateFromFile = function (Path, Password, CertificateKey)
CertificateFromLogonManager = function( AppID ). Supported on iOS and Android.
CertificateFromStore = function (CertificateKey)

Domain Whitelisting

Kapsel plugins support Apache Cordova's domain whitelisting model. Whitelisting allows you to control access to external network resources. Apache Cordova whitelisting allows you to whitelist individual network resources (URLs), for example, http://www.google.com.

For information about the whitelist rules, see http://docs.phonegap.com/en/3.3.0/guide_appdev_whitelist_index.md.html Information published on non-SAP site .