Developer

Adding and Configuring the FederationProvider Plugin

Context

https://github.com/SAP/mobilesdk-certificateproviderInformation published on non-SAP site is a public GitHub repository that contains an example plugin implementation that can be used for testing.

Procedure

  1. Add the FederationProvider plugin by entering standard commands at the command prompt, or terminal. For example:

    $ cordova create fedsample com.sap.fedsample fedsample

    $ cd fedsample

    $ cordova platform add ios

    $ cordova platform add android

    $ cordova plugin add kapsel-plugin-federationprovider --searchpath KAPSEL_HOME/plugins

  2. Add the Certificate Provider plugin used to sign client certificates. For example:
    $ cordova plugin add https://github.com/SAP/mobilesdk-certificateprovider/federation/X509FileCertificateProvider
    You now have default Cordova content in an application which contains these plugins:
    • cordova-plugin-device 1.1.1 "Device"
    • cordova-plugin-whitelist 1.2.1 "Whitelist"
    • kapsel-plugin-authproxy 3.12.0 "AuthProxy"
    • kapsel-plugin-corelibs 3.12.0 "CoreLibs"
    • kapsel-plugin-federationprovider 3.12.0 "FederationProvider"
    • kapsel-plugin-i18n 3.12.0 "i18n"
    • kapsel-plugin-inappbrowser 1.0.1 "InAppBrowser"
    • kapsel-plugin-logon 3.12.0 "Logon"
  3. Configure the Federation Provider through the context passed to the Logon plugin. Verify appconfig variable naming in the index.html since these are passed to federation and file providers. For example:
    var context = { 
    	operation: {
    		logonView: sap.logon.IabUi
    	},
    	appConfig: {
    		appID: "com.example.federation.test.app",
    		isForSMP: true, //True in case mobile service for development and operations 
    		//Enables the Federation identity 
    		"certificate": {
    			"id": "com.sap.federationprovider", //in case federation you must exactly use this id 
    			"config": {
    				"federated_certificate": "<<CertificateProvider>>", //the id of the certificate provider to fetch the shared certficate from 
    				"property": "value", //add provider specifica key/value pairs here. 
    				... 
    				"propertyN": "valueN" //parameters will be also made available for the federated_certificate 
    			}
    		}
    	}, smpConfig: {
    		"serverHost": "<HOSTNAME_OF_THE_SERVER>",
    		"https": "true", //in case HTTPS protocol is used 
    		"serverPort": "<PORT_NUMBER>",
    		"communicatorId": "REST", //must be provided for iOS 
    	}
    };
    
  4. Configure the project:

    iOS - Xcode Project

    Android Project

    1. Open the Capabilities pane.
    2. Enable the Keychain Sharing option.
    3. Add a new value to the Keychain Groups: “federationEntitlements”
    4. Add necessary resources to your Xcode project. In case of example File Certificate Provider add the certificate in form of the .p12 file into your main bundle (for example, the root of your Xcode project).
    5. Verify that the .p12 file is added toStart of the navigation path Project Properties Next navigation step Build Phases Next navigation step Copy Bundle Resources End of the navigation path.
    1. Place the .p12 file into the assets folder of the generated Android project.
    2. Add the following lines to the AndroidManifest.xml file:
      <permission 
         android:name="<group_id>.FEDERATION_PERMISSION" 
         android:description="@string/federation_permission_description" 
         android:label="@string/federation_permission_label" 
         android:protectionLevel="signature" /> 
      <uses-permission android:name="<group_id>.FEDERATION_PERMISSION" />
  5. Use the federated certificate in your apps. The general flow is:
    1. Open the first app that uses the federated certificate.
    2. When you log in, enter a password that allows access to the datavault in which the federated credentials are stored.
    3. You can then select the .p12 user certificate used for authentication. For example, my.p12.
    4. Open the second app that uses the federated certificate.

      The app detects that another app already has credentials stored in the datavault, and you are prompted for the datavault password.

    5. After sucessfully entering the datavault password, you are asked whether want to use the existing federation provider certificate.