The AuthProxy plugin can include a certificate in an HTTPS request that identifies the client to the server, allowing 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 the Logon plugin (this uses the same certificate that was used for registration).
Interception of Web Requests and Handling Challenges
The AuthProxy Plugin can intercept all web and data requests and handle basic authentication and X.509 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 recommended and all cases where it used to be required are now supported without interception. Continuing to use interception on Android is very likely to cause issues. You can enable or disable interception of web requests by setting theSAPKapselHandleHttpRequests preference setting in config.xml to true or false. The default value of this preference for Android is false. The default value of this preference for iOS is true.
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 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 reused 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.
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.
Note that this configuration does not apply to Android. Instead of having an application keychain like iOS, the Android has a 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. AuthProxy on 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 UI for the user to select a certificate unless it has to. On Android this behaviour is fixed and does not change based on the autoSelectSingleCert configuration.
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 a Hybrid SDK (Kapsel) project, you call the AuthProxy setAutoSelectCertificateConfig method on the onDeviceReady event.
- 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] )
- CertificateFromFile = function (Path, Password, CertificateKey)
- CertificateFromLogonManager = function( AppID ). Supported on iOS and Android.
- CertificateFromStore = function (CertificateKey)
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.