Mobile RAD: Create a protected OData service on Cloud Foundry and consume it with an offline MDK app.
In this blog post I will share with you, end-to-end, how to develop a native cross-platform mobile app that makes use of a protected back-end service running on Cloud Foundry. Besides building the mobile app with our Mobile Development Kit (MDK), we will also create an OData service from scratch and deploy this as a protected service. The latter is the tricky part that most of the existing tutorials will avoid, as the configuration of the authentication flow is a non-trivial topic.
For this blog post we will be using a new trial account. You might have noticed that our trial experience has improved recently.
SAP Cloud Platform
To start using your trial account, open https://cockpit.hanatrial.ondemand.com. Go ahead and ‘Sign in’ if you already have an account, or register for a new one. Once you have access, go ahead and click the “Launch SAP Web IDE” button.
What you need to be aware of is that at this point in time some of our services are available on the SAP managed SAP Cloud Platform known as “Neo” running in SAP data centres, while others are available on SAP Cloud Platform on Cloud Foundry, running at one of the hyper scalers. This might cause confusion, so please follow the prerequisites and steps closely.
SAP Web IDE Full-Stack
Once we are in SAP Web IDE Full-Stack (which runs on Neo only), we need to configure the default settings for performing Cloud Foundry operations. You can use SAP Web IDE to work with multiple landscapes, so we need to tell it which one to pick. Please go to the menu Tools > Preferences > Cloud Foundry. Select the API Endpoint (this requires authentication), followed by the Organization and Space. For a trial landscape, the endpoint is most likely going to be https://api.cf.eu10.hana.ondemand.com .
We also need to enable an extension in SAP Web IDE. In the menu, please go to Tools > Preferences > Extensions and enable the extension called ‘Mobile Services App Development Tools’. This extension includes the Mobile Back-End Tools.
The extension is making use of a microservice that is currently part of SAP Mobile Services on Neo. This might change in future. The Mobile Back-End Tools extension in SAP Web IDE makes use of a SAP Cloud Platform Neo destination to find the service.
When you set up a new trial account, SAP Mobile Services on Neo is not enabled by default. Please go back to your SAP Cloud Platform trial account and select ‘Access Neo Trial’ from the “Environments” section. Go to Services and find the ‘Mobile Services, users’ service. If not yet enabled, please enable this service. When enabling the service, a destination called ‘mobileservices’ is automatically created for you in SAP Cloud Platform (Neo)
Besides a destination pointing to SAP Mobile Services on Neo, we also need two destinations that point to SAP Mobile Services on Cloud Foundry. We have to create these destinations in SAP Cloud Platform on Neo.
The first destination is for the Mobile Services App Development tools extension in SAP Web IDE. Give this destination a name (anything), select type HTTP, Proxy Type Internet and Authentication should be set to BasicAuthentication. Provide the credentials used to access SAP Cloud Platform on Cloud Foundry.
HandleRedirects : false
SkipSSOTokenGenerationWhenNoUser : true
WebIDEEnabled : true
WebIDEUsage : mobile
For the URL, we need to know the Service URL of the SAP Mobile Services instance on Cloud Foundry. Please go back to SAP Cloud Platform (in another browser/tab) and enter your (trial) account. Navigate to your space on the subaccount and select Services > Service Marketplace. Search for ‘mobile’. You should see a number of mobile related services listed. Pick for example Mobile App Update. Here you will find links to our SAP Mobile Services documentation and a link to Support. The latter will basically bring you to the admin cockpit where we kind find the URL we are looking for.
After authentication and selection of the Organization and Space, the cockpit will be visible. Select “Important Links” available at the bottom left.
We need to copy the admin api.
Back in the destination configuration on SAP Cloud Platform Neo, paste the URL in the URL field of the destination and save the destination. Now the Mobile extension in SAP Web IDE will be able to find SAP Mobile Services on Cloud Foundry.
The second destination is for the Mobile Back-End Tools extension to access SAP Mobile Services on Cloud Foundry. The destination name has to be in the format “mobileservices_cf_<account data centre>”. In our case, for trial, this would become “mobileservices_cf_eu10”. For this destination you only need the additional property WebIDEEnabled : true. The url is the same as for the first destination.
Creating the OData service
Those of you who have participated in the openSAP course “Build Mobile Application with SAP Cloud Platform Mobile Service” and followed the exercises in the MDK related section (week 4) should be familiar with the service we will build here.
For this blog I will use the same OData service as used in the openSAP course. Please go ahead and download the file openSAPNew.zip. Import this file into SAP Web IDE.
Once the project is imported, select it and right-click to bring up the context menu. In the context menu, select Project > Project Settings and navigate to the Mobile OData Service Generation section. Change the Authentication Method from ‘NONE’ to ‘XSUAA’ and Save the changes. For this case we will keep it simple and continue using the in-memory database option for the service.
Opening the file com.opensap.mobile.canteen.csdl.xml in SAP Web IDE will open the graphical modeller. We won’t change anything here now as this is good enough for this demonstration.
Next, we will generate the data service. Right-click on the file com.opensap.mobile.canteen.csdl.xml and select ‘Generate Mobile OData Service’.
Generating and deploying an OData service to Cloud Foundry was already possible with our tooling. However, binding this to a mobile application in SAP Mobile Services on Cloud Foundry and taking care of the security configuration is a non-trivial task that can go wrong in various places. We therefore introduce a new feature in our 1910 release that helps you in this tedious configuration process.
After generating the service from the CSDL file and customizing it (the latter is optional), you can select the project, right-click and in the context menu select Deploy > Deploy to Mobile Services.
Take note that the service is tailored for mobile consumption and supports delta tracking, which significantly optimizes the data synchronisation with mobile devices.
If you see an error reported regarding “No destination defined for OData service generator” then you have to enable Mobile Services on Neo as mentioned in the prerequisites.
In the first step of “Deploy to Mobile Services”, you will see a dialog showing you the mobile app configurations currently available in Mobile Services on Cloud Foundry. You might also see a browser popup dialog requesting credentials. You’ll need to provide the credentials for your SAP Cloud Platform on Cloud Foundry account. The username is typically the email address you’ve used to sign up for the SAP Cloud Platform account.
The dialog allows you to select the mobile app and its endpoint that you are going to bind to the OData service. You can also create a new mobile app configuration and endpoint in SAP Mobile Services on Cloud Foundry from this dialog.
For this case, please go ahead and create a new app and new endpoint. I’ve used the Name ‘openSAPApp’ and Display Name ‘openSAPApp’ here. You can use something else as well.
Note: if you would check your Mobile Services cockpit at this point, you will notice there is a destination created that is pointing to the Northwind OData test service. This will be replaced automatically in the next steps.
After clicking OK, the mta (multi target application) project will be built and deployed to Cloud Foundry. Once deployed successfully done, it will be bound to the specified endpoint of the mobile app.
You can test the endpoint by opening the SAP Mobile Services endpoint url shown in the SAP Web IDE console in a browser (see screenshot above). When opening the url in your browser, you will need to authenticate with your SAP Cloud Platform (on CF) credentials.
Note: for those using multiple accounts (e.g. SAP colleagues), please use the incognito mode of your browser to avoid automatically getting authenticated using your other account.
The result might surprise you… Although the authentication against the configured IDP was successful, the response is ‘Forbidden’. This is because your user is not yet allowed to access the service. So the service is indeed protected !
What we have not been able to automate (not yet) is the Role Collection and Trust Configuration on SAP Cloud Platform (to be clear: on Cloud Foundry).
In the generated service in your SAP Web IDE project, there is a file called xs-security.json. This file contains role-templates and scopes. You will notice the ‘Service user role’ with name ‘ServiceUser”.
In order to configure this role for your user, please go back to your SAP Cloud Platform account cockpit and select “Enter Your Trial Account”. This will open the cockpit for SAP Cloud Platform on Cloud Foundry. Select and open the subaccount ‘trial’. Select the ‘Security’ tab and select ‘Role Collections’. Create a new role collection with the name “ServiceUser”.
Once created, select the ServiceUser collection and select “Add Role”. Select the application identifier and select the Role Template ‘ServiceUser’. Save this configuration.
Next, go to Trust Configuration in the Security tab (next to Role Collection). Click on the SAP ID Service link. On the trust configuration: SAP ID Service – Role Collection Assignment page, enter the E-Mail Address you are using for SAP Cloud Platform on Cloud Foundry and select ‘Show Assignments’. If the ‘ServiceUser’ role collection is not yet assigned to you, please go ahead on select ‘Assign Role Collection’ to do so.
Now, let’s go back to the Mobile Service endpoint, reload it, and see whether we have access now.
Now that your user has the correct Role Collection assigned, you are able to access the service.
At a later stage we need the OData metadata description of this service endpoint. To get the metadata from the service, simply add ‘/$metadata’ to the url. In my case, the url becomes:
Save this metadata document to a file on your workstation. We’ll need it later, when creating the mobile application.
Creating the MDK mobile offline app
Now that we have the OData service up and running, let’s create a cross-platform mobile application with Mobile Development Kit. It is not my intention to create a fancy looking app. We will simply use an application template that can show the basic functionality, including the capability to continue using the app and the data while the device does not have a network connection.
In SAP Web IDE, right-click on the workspace and select New > Project from Template. Ensure the selected Environment is ‘Cloud Foundry’ and select Category ‘Mobile Services’. Select the template called ‘Mobile Development Kit CRUD Application’ and click Next.
In the next wizard steps, provide a Project Name and Application Name.
Next, we enter the Service Configuration. This is the tricky part where we need deviate from the usual flow. In case of unprotected services, we can use a destination to connect to mobile service on CF to find the correct app and endpoint. And with this information, the wizard is able to retrieve the metadata document of the service. However, this doesn’t work for protected services, as we are lacking the correct authentication mechanism.
The workaround is to provide the metadata document manually. Select ‘Local Metadata XML’ and find the file you’ve saved earlier.
Provide the Name of the service and using the destination defined earlier we automatically retrieve the Application ID and name of the endpoint we’ve created earlier.
In the next step, select all datasets and click Next.
We are going to use the default settings in the Customization as well. Click Next.
In the optional features, we can configure to initialize offline data. Use the default selection and click Finish.
When finished, you will have an MDK project added in your workspace.
Now we need to make some changes to ensure SAP Mobile Services on Cloud Foundry is used by our mobile app.
First of all, we need to know the Service URL of the SAP Mobile Services instance on Cloud Foundry. We’ve already done this in the prerequisites, but let’s check again and see what we’ve created. Please go back to SAP Cloud Platform and enter your (trial) account. Navigate to your space on the subaccount and select Services > Service Instances. You should be able to see your services listed. One of them is your Mobile App created in SAP Mobile Services. The other one is the xsuaa service which was created for your OData service. This is a SAP extension of the Cloud Foundry User Account and Authentication handler, which manages business users and enables them to authenticate to applications deployed in SAP Cloud Platform. SAP added a service broker, multitenancy, management API functions and some minor enhancements.
Click on the ‘mobile-services’ Service link. And click the Support link.
After authentication and selection of the Organization and Space, the cockpit will be visible. Select “Important Links” available at the bottom left and select “Copy Admin API”.
Go back to your project in SAP Web IDE and open the service definition. Change the Service URL to the Admin API you’ve copied from Mobile Services cockpit and save the changes.
Now that we were already in the Mobile Services admin cockpit, let’s go back and make a few necessary changes to the application configuration.
Select Mobile Applications > Native/Hybrid and open the mobile app created earlier.
Ensure to add the Mobile App Update feature and Mobile Offline Access. To be able to collect log files from the client, you can also add Mobile Client Log Upload.
Click on the Mobile Settings Exchange feature and tick the Biometric Authentication Allowed. This make life easier when accessing the app.
We also need to change the Security Configuration, which is by default set to SAML. For MDK client apps, we need to use OAuth. You can change this setting in the app’s Security tab.
On this same configuration page, you will notice that a file called xs-security.json was already uploaded. This was done during the Deploy to Mobile Services.
With these configuration steps done, we can go back to SAP Web IDE.
We will now deploy the application to SAP Mobile Services. This involves bundling all metadata, rules, actions etc. with Webpack, uploading it and activating the new version. The Webpack output will be visible in a separate folder in your workspace.
Bring up the project’s context menu and select MDK Deploy and Activate.
In the dialog leave all options default and select Next.
In the following step we select the Destination Name created in SAP Cloud Platform Neo that points to SAP Mobile Services on Cloud Foundry.
The Application Id should be the same as provided earlier. Click on the icon to the right of the dropdown box. This will show the mobile client Onboarding information. You can scan the QR code or send the Result URL via email to your device. Before doing this, let’s first deploy the app. Close this Onboarding dialog and select Next. In the SAP Web IDE console you will notice the bundling process is started and a few seconds later the bundle is uploaded, deployed and activated.
Once deployed successfully, let’s go back to the Onboarding dialog.
Now we need to open the url on a device that has the MDK client installed. You can build your own MDK client using our SDK. However, it is much easier for this case to grab the latest version available in the AppStore or Google Play. In the store, please search for SAP Mobile Services Client and install the app on your device. Once done, scan the QR code or open the Result URL you’ve sent yourself via email. For scanning the QR code you can simply use the camera app.
After onboarding the app, you will see the CRUD app running in the client. You can drill down to check the entries for each entity, change them, create new, delete them. After making changes, you can sync those changes to the OData service.
This concludes developing the offline native mobile app.
Future optimisation to the setup
Reading back the steps explained so far, there are quite a number of things to configure and change. We’ll probably be able to eliminate some of the steps with future releases of our tooling. I’ll update this blog as soon as these optimisations are available.
Rapid iterations from here onwards
At this point you can start changing the app to your needs. You can even add entities and new properties in your data model, redeploy the service, refresh the objects used in the app, modify the app accordingly and deploy a new version. All without actually building, signing and distributing the apps to your device(s). Being able to skip all these tedious tasks makes your development flow much more productive.
I am looking forward to your feedback and can’t wait to see what you’ve built with this.
Happy coding !
SAP Digital Workplace – Rapid Application Development