How To Guide – The SAP Fiori Client and Certificate based Authentication (iOS)
In the past few months, I have been approached by 2 different customers, both wanting to clarify how they could achieve a solution where their users would benefit from certificates based SSO which they use on their lap/desktops in the context of Mobile usage.
Interestingly enough, a Swiss customer challenged us on the very same topic late in 2018. Obviously, this combination of app, platform and SSO is desired. So what better way to get the message out there than to write a blog / how-to guide detailing the steps.
In order to demonstrate this solution, the following landscape components are needed
- SAP Netweaver ABAP (to serve us the Fiori Launchpad)
- Configured for Principal Propagation.
- A Mobile Services tenant in the SAP Cloud Platform.
- SAP Cloud Connector
- An iOS device
- XCA (This is in lieu of a certificate authority. In a real world scenario, one would of course use the corporate CA)
- XCA is an open source tool, implementing openSSL with a GUI to simplify usage and is often used to replicate the enterprise certificate authority (CA herewith).
- This tool is our tool of choice and in no manner indicative of what should be used or to be taken as a recommendation.
- SAP Kapsel SDK (use the latest version available)
- From the download center at https://support.sap.com
- KapselSDK (the latest SP) from https://support.sap.com/downloads
- Macbook with XCode (this example uses Xcode 10)
- An iPhone
- XCA to create certificates & sign them if necessary.
- This example relies on the corporate certificates provisioned by SAP but installed manually on a test iOS device.
The Kapsel SDK
- Install the Long Term Support (LTS) version of node.js (http://nodejs.org/)
- sudo npm install -g email@example.com (this was the version for in my case)
The README.md file that is provided with your Kapsel SDK download will tell you which cordova version to use.
config.JSON – Your helper in building the project structure
The config.json file takes the parameters necessary to create the project structure and populates the appid fields.
Creating the Fiori Client Application
Once the parameters are maintained, run the “create_fori_client.js” script in a terminal.
Adding the OAuth method
The result is a folder structure within the specified folder here, the target folder being “rich”.
We are most interested in the appConfig.js file within the www folder at the root of the newly created structure.
It is here that we will add our method to invoke the OAuth flow as well as provide configuration for the integration layer.
Open the appconfig.js in your favorite text editor and add the following to the file. Note that placement of the code is not important but syntactical correctness is an absolute requirement.
**(for some reason the formatting in the provided editor is sh&%¤# when inserting code)**
“oauth2.redirectURL”: “com.sap.demo.pp.rich://oauth2”, //must match the redirect url configured in SCP mobile service
“oauth2.useExternalBrowser” : true
Screenshot of an actual file with this code contained within it.
At this point you may be wondering where the values for these parameters are picked up from.
These details are to be found in the Oauth client entry in your application proxy with your Mobile Services instance in your SAP Cloud Platform tenant. DO NOT worry about these values for the moment. We will come back to this step at a later stage.
Going back to the terminal, Change directory to the newly created directory (in our case ´rich´)
There run the command ´cordova prepare´
Which will result in the platform directory being populated with the changes you have made in the appConfig.js file.
The finished product.
The platform that you have built for, in this case iOS will contain the project file as well as the workspace. In our case, the “projectname”.xcodeproj and “projectname”.xcworkspace
Double clicking on either of these will start the IDE where we will finish the rest of the tasks.
Your Project in Xcode
Clicking on the “projectname”.xcodeproj file gives us the following view in the IDE.
Depending on your local setup the presentation may vary.
Here, simply clicking on the large grey arrow next to the three coloured buttons on the top left should be enough to build, deploy and run your application on a simulator which is chosen in the same menu bar, a few icons to the right.
Deploying to the simulator
- At this point we could theoretically run the application on a simulator by pressing the grey arrow button.
- However, we are not ready to do that yet.
- Remember the OAuth flow configuration values we were going to come back to?
- If we deploy now, the values in the code copied and pasted will not match the values of your cloud tenant so the authentication flow will fail.
- Remember the OAuth flow configuration values we were going to come back to?
Deploying to a device
- The process of deploying to a device is slightly different from the process we used for the simulator.
- The Apple ecosystem requires that one have a valid profile to deploy to an iOS device.
Even if it is only a developer device.
The deployment target is changed by clicking on the target device and choosing the physical phone, that has to be attached to the development environment with a physical connection.
NOTE: This is not a definitive explanation on how to handle the ios app development cycle. There are a number of methods to deploy apps to testers devices. It is not the scope of this blog to cover those, However, here is what apple say about beta testing.
Adding a certificate manually to the device keychain
- In the case where we want to simply add a certificate to the device
keychain, it is sufficient to send an email with the certificate attached to an email.
- Opening the attachment from the APPLE mail client will trigger the install process.
Configuring the OAuth flow
- SAP Cloud Platform Mobile Services
- The architecture of the SAP Cloud Platform (and its underlying services) is such that the platform provides some core services like authentication and connectivity, for example.
- Therefore if we were to be using a third party Identity Provider (IdP) like ADFS for example, then we would be obliged to create a trust relationship in the Trust Cockpit on the tenant level.
- In this example, we are simply using the SAP default IdP, accounts.sap.com, thus no such configuration is necessary.
- Application (in the SCPMS Admin Cockpit)
- The application is a placeholder if you will that adds features like authentication, offline capabilities, SSO etc..
- In this case we will configure the application to adhere to a particular SSO mechanism as well as to use a specific type of SSO to the backend.
- In this case, the Authentication method is set to OAuth and the IdP is set to require certificates as the preferred authentication mechanism.
- When the OAuth settings are maintained, the redirect URL shall point to the application ID, in this case ´com.spp.demo.rich´ and refer to the schema, thus, ´://oauth2´ resulting in ´com.sap.pp.demo.rich://oauth2´
And if you remember what we said when writing the code in our appjs.config,
- Destinations are the mechanism that are used extensively within the Cloud Platform and its services to reach data
Destinations can either point to on-premise systems
or to systems within the various cloud platforms.
- Since the identity of the user is being validated at the platform
level (based on the settings in the Trust cockpit), this identity
needs to be the crux of the call being made to the data source,
thus ensuring that data is retrieved and returned in the context of the authenticated user. In order to achieve this we use a technique called Principal Propagation.
Running the application
The easiest part in this process is of course running the app. Simply tap on the icon on the device.
And there we have it. Seamless SSO with x.509 certificates placed in the iOS system keychain using OAuth.
As a footnote, while this guide is focused on the iOS version of the fiori client, the steps up until the point where one runs the project in Xcode are universal so no matter what platform you choose (well… in today’s reality the only other platform is Android I suppose…), you may safely replicate these steps.