Hello API Community.
This tutorial will show you how to run the Android sample app, shipped with the Mobile API Gateway (MAG) 3.0.01 Software Development Kit (SDK). Before being able to run the Android app, please, make sure the following requirements are attended:
- A Gateway 9.0 with OTK 3.3 and MAG 3.0.01 is required. I'm assuming you have the gateway and MAG piece working fine. Please refer the the official wiki documentation to know how to install those components;
- You will need an updated Android Studio and an Android Emulator running at least Android 5 (API level 23);
- You will also need the MAG 3.0.01 Android SDK. During the time this tutorial was written, this is the Android SDK file used: MAG-Android-SDK-3.0.01-b1057.zip. If you don't have the SDK, please reach out to your CA sales contact or look internally for someone on your team with access to the download portal, where you can download all the CA APIM solution.
Let's get started then!
1. Unzip the MAG Android SDK. You should see something like this, inside the unzipped folder:
2. Now open your Android Studio and then select the "Open an existing Android Studio project" and point to the unzipped folder/samples/SingleSignOnSample, as follows:
3. Hit OK on the Gradle Sync pop up and wait until Android Studio finishes the project indexing, which can take few minutes depending on your computer;
4. When Android Studio finished the indexing you will be able to see the project folder:
5. Navigate to the SingleSignOnSample/assets and you will find a file called msso_config.json which is the SDK's configuration file. This file can be obtained from your OAuth Manager. During the MAG installation you can deploy the test data. These test data will provide you some test OAuth clients, we call App A, B and C. You can use either one to test your Android sample app. You can also create a new OAuth client and use it, just make sure you have the proper scopes in place and also enable the master key, otherwise the device registration process will fail. Please refer to this documentation if you don't have your OAuth client: Export Configuration as JSON Message - CA API Management OAuth Toolkit - 3.3 - CA Technologies Documentation and Initialize SDK with JSON Message - CA Mobile API Gateway - 3.0 - CA Technologies Documentation
6. This is how the exported JSON file will look like:
7. Copy all the content of the exported JSON file, making sure you scroll down to copy the whole file. Now go back to your already opened Android Studio, double click on the msso_config.json and paste the exported file:
8. That's all you have to do to use the Android SDK sample app. Now you can run your project and select the desired Android emulator. I'm going to use a Nexus 5 with Android 5 (API 23):
9. Depending on your computer the Android emulator start can take some time.
10. If you are using a local gateway without a DNS name that could be resolved by your emulator, you will need to push a hosts file to your emulator so it will be able to resolve the name. To do so, open up your terminal or CMD on Windows and type these commands:
adb root
adb remount dab push hosts /system/etc/ |
|---|
Your hosts file should have the IP address and the name of your gateway. It's important that the hostname and the gateway name (inside your msso_config.json file) matches, otherwise the mutual SSL will fail.
11. To make sure your Android emulator can resolve the name, open up the native internet browser and hit the gateway address and either the HTTP (8080) or HTTPS (8443) port of it. It should connect and present an error from the gateway saying the service couldn't be found, which is fine, as long as you can reach out to the gateway.
12. After the building process finishes, you should see the sample app:
13. Hit the List Items button. It will start the device registration and user authentication process. You will need to allow the location and phone access and also provide a PIN to be used by the keystore
14. After defining a PIN, the MAG SDK will challenge you for credentials. You can use anything you may have defined in your OTK User Authentication policy. If you haven't defined anything, just use any internal gateway user. I'm going to use the admin:
15. After providing the correct credentials, you will be seeing a list of 6 items, coming from a demo endpoint created on the gateway during the MAG solution kit installation
16. I f you want to run the Enterprise Browser, click on the menu located on the right top corner and then hit the Enterprise Browser:
In order to get Enterprise Browser working in your sample app, make sure you follow this documentation to add the required tags inside your AndroidManifest.xml file in order to identify your native app, running the MAG SDK: Enterprise Browser SDK - CA Mobile API Gateway - 3.0 - CA Technologies Documentation
Now you can duplicate this project to have several different apps and then being able to use the Mobile Single Sign On (MSSO) between native apps built with our SDK.
That's it. I hope it helps. Let me know your feedbacks on the comments below.
Reference and documentation: