Akamai Bot Manager. Android and ios BMP SDK

Akamai Bot Manager Android and ios BMP SDK Prabha Kaliyamoorthy January, 2018

Contents Bot Manager SDK 4 Identifying Protected Endpoints 5 Identifying the App OS and Version in the user-agent 5 Request Flow 6 Integrating with Android Apps 7 Installation 7 1. Install the SDK 7 2. Initialize the SDK 7 3. Collect Sensor Data 7 4. Send Sensor Data 8 5. Evaluate the Akamai Edge Response 8 Sample Code Getting and Sending Sensor Data 9 Android API 10 Logging 11 Integrating with ios Apps 12 Installation 12 1. Install the SDK 12 2. Edit the Build Settings 13 3. Collect Sensor Data 14 4. Send Sensor Data 14 5. Evaluate the Akamai Edge Response 14 Sample Code Getting and Sending Sensor Data 15 ios API 16 Logging 17 Akamai Edge 18 Application Identification 18 Akamai Edge Response 18

Bot Manager SDK Akamai Bot Manager automatically detects traffic generated by robots (bots) on web sites, using various strategies that detect human behavior. Akamai Bot Manager SDK (BMP SDK) takes this technology and applies it to native mobile apps. The Bot Manager mobile SDK is a necessary component for customers who have purchased Bot Manager Premier for Mobile product. The BMP SDK collects behavioral data while the user is interacting with the application. The behavioral data, also known as sensor data, includes the device characteristics, device orientation, accelerometer data, touch events, etc. Akamai BMP SDK provides a simple API to detect bot activities and defend against malicious bot and account takeover.

Identifying Protected Endpoints The first step is to identify which endpoints need to be protected. In order to prevent false positives, only requests that are triggered by users interacting with the application, and that may be abused by bots to carry out an attack, should be protected with this technology. Typical use cases include: Account login Account signup Search queries Add to cart Checkout Reward and gift card programs For each request you want to protect, you need to collect the full URL, the method, and any other parameters in the request (including in the body for POST requests) that will help identify the request. Identifying the App OS and Version in the user-agent In order to prevent false positives during the initial rollout, we need to be able to identify the application version so that we can conditionally apply bot detection logic to requests that are expected to send the behavior data. Once enough users have upgraded to the latest version of the application, this condition can easily be removed by updating the bot manager configuration in the Luna control center. Also, because the development lifecycle of the ios and the Android application may not follow the the same cadence and speed, we also need to be able to identify which requests come from ios and Android apps. This strategy may help mitigate bot traffic quicker without having to wait for both apps to be at the same level of maturity and user adoption. The edge server uses the User-Agent HTTP header to identify the application that is integrated with the SDK. So we recommend using a standard format like Application-Name/Version-Number (Platform-Information) for the User-Agent header in the REST API request. Examples: HelloApp/1.2.3 (iphone; ios 11.2.1) MyFirstApp/1.1.2 (Android 7.0; Build/NRD90U)

Request Flow Once the SDK has been implemented and the protected endpoints added into the Bot Manager configuration, the protected request is processed as follows: 1. The user interacts with his mobile devices to login to the application. While this happens, the behavior data (devices orientation, device acceleration, device characteristics and touch event will be recorded by the SDK. 2. When the user presses the submit button: a. The application queries the SDK to retrieve the sensor data. b. The sensor data is added to the request as a header. c. The request is sent to the closest available edge server. 3. Akamai edge server evaluates sensor data and takes the predefined action on the request: a. If no threat is found in the sensor data, the request is classified as human and forwarded to the origin web server b. If a threat is detected, the bot manager rule will fire and the associated action executed.

Integrating with Android Apps This section describes the overall process used for Android apps. You start by installing and initializing the BMP SDK, and then you re ready to collect and send sensor data. Then you can determine what actions to take depending on the response codes from the edge. Installation The size of the SDK jar file is 65 KB and contains 512 Dex method counts. Requirements Android Studio Android API 15 (Android 4.0.4) and above 1. Install the SDK Install the SDK by downloading the SDK and copying AkamaiBMP.jar into your libs folder. 2. Initialize the SDK Initialize the SDK by calling CYFMonitor.initialize API from your main activity's oncreate method. // Import the class import com.akamai.botman.cyfmonitor ; public class MainActivity extends Activity { @Override protected void oncreate ( Bundle savedinstancestate ) { } } // Initialize Akamai BMP SDK CYFMonitor. initialize ( getapplication ()); 3. Collect Sensor Data The BMP SDK s sensor data contains serialized user behavioral data and device information. However, the device information doesn t contain any information that will identify this device uniquely.

You can retrieve sensor data from the SDK by calling the CYFMonitor.getSensorData method. Sensor data should be sent in the REST API request as detailed below. // Get the BMP sensor data String sensordata = CYFMonitor. getsensordata (); 4. Send Sensor Data After the sensor data is retrieved from the SDK, it should be sent in X-acf-sensor-data HTTP header as part your applications REST API (HTTP/S) request. We recommend using HTTPS for the REST API request to ensure the integrity of sensor data and prevent eavesdropping. // Set the sensor data header urlconnection. setrequestproperty ( "X-acf-sensor-data", CYFMonitor. getsensordata ()); 5. Evaluate the Akamai Edge Response Akamai edge server inspects sensor data and takes the predefined action on the request if the request is classified as BOT, otherwise Akamai sends the request to the origin server.

Sample Code Getting and Sending Sensor Data The following code snippet shows how to get the sensor data and send it in the HTTP request. // Import the class import com.akamai.botman.cyfmonitor ; public class LoginActivity extends Activity { @Override protected void oncreate ( Bundle savedinstancestate ) { } // Initialize Akamai BMP SDK CYFMonitor. initialize ( getapplication ()); protected void loginaction () { // Get the BMP sensor data String sensordata = CYFMonitor. getsensordata (); // Initialize HttpURLConnection URL url = new URL ( "https://bmpapi.akamai.com/samples/v1/login" ); HttpURLConnection urlconnection = ( HttpURLConnection ) url. openconnection (); // Set the sensor data header urlconnection. setrequestproperty ( "X-acf-sensor-data", sensordata ); // set the POST body and send the request } }

Android API CYFMonitor public class CYFMonitor java.lang.object +--> com.akamai.botman.cyfmonitor (added in Version 2.0.0) CYFMonitor provide methods to access the BMP SDK. All methods in this class are static methods and can be accessed from anywhere without initializing an instance and methods can be invoked from any thread. See the individual method details for more information. Public Constants Log Levels Type int int int int Public Methods Log Level INFO: Constant to log all messages from the SDK WARN: Constant to log all warning and error messages from the SDK ERROR: Constant to log only error messages from the SDK NONE: Constant to log no messages from the SDK Initialize static synchronized void initialize ( Application app ) Initialize the Akamai Botman SDK to capture user events for the specified application. getsensordata static synchronized String getsensordata() Get the serialized user behavior data, device events and device information to be sent with the REST api that needs to be protected.

Returns: String Serialized sensor data setloglevel static void setloglevel ( int loglevel ) Set the log level for the Akamai BMP SDK. See Logging below for a list of valid values. Parameters: loglevel int: A valid log level value Logging Akamai BMP SDK logs some messages at all log levels to verify the SDK initialization. These messages are helpful in identifying any integration issue and ensure the SDK is initialized successfully. In addition to these messages, the SDK logs additional messages at info, warn and error levels, to verify and debug that the SDK is working correctly. The default log level for the SDK is to log warning and error messages only. This behavior can be changed by calling setloglevel API. To set the log level, call CYFMonitor.setLogLevel API with one of the log levels specified below: CYFMonitor.INFO - Print all messages CYFMonitor.WARN - (Default) Print warning and error messages only CYFMonitor.ERROR - Print error messages only CYFMonitor.NONE - Turn off all log messages from the SDK For example, to see all messages: // Set the log level to Info CYFMonitor. setloglevel ( CYFMonitor. INFO );

Integrating with ios Apps This section describes the overall process used for Android apps. You start by installing and initializing the BMP SDK, and then you re ready to collect and send sensor data. Then you can determine what actions to take depending on the response codes from the edge. Installation The size of the SDK framework is 9.4 MB and contains armv7, arm64, i386 & x86_64 architectures. i386 and x86_64 architectures are used in the simulator and will not be included in the final AppStore distributed app. After including the SDK, the app binary size will be increased approximately by 300 KB. Requirements: Xcode 8 and above Akamai BMP SDK is supported in ios 8.0 and above 1. Install the SDK 1. Download the SDK and drag AkamaiBMP.framework into your XCode Project. 2. In the Choose Options dialog box, select Copy items if needed.

2. Edit the Build Settings Under Build Settings, navigate to Linking and then under Other Linker Flags add -ObjC. Note that the SDK is initialized automatically for ios, and so unlike Android, no explicit initialization step is required here.

3. Collect Sensor Data Now you can collect sensor data. Note that the device information doesn't contain any information that will identify this device uniquely. 1. Import the SDK header into your source file: // Import the SDK header #import <AkamaiBMP/CYFMonitor.h> 2. Akamai BMP's Sensor data contains serialized user behavioral data and device information. To retrive the sensor data from the SDK call the CYFMonitor getsensordata method. Sensor data should be sent in the REST API request as detailed below. // Get the BMP sensor data NSString * sensordata = [ CYFMonitor getsensordata ]; 4. Send Sensor Data After the sensor data is retrieved from the SDK, it should be sent in X-acf-sensor-data HTTP header as part your applications REST API (HTTP/S) request. We recommend using HTTPS for the REST API request to ensure the integrity of sensor data and prevent eavesdropping. // set the sensor-data header [ request addvalue: sensordata forhttpheaderfield: @"X-acf-sensor-data" ]; 5. Evaluate the Akamai Edge Response Akamai edge server inspects sensor data and takes the predefined action on the request if the request is classified as BOT, otherwise Akamai sends the request to the origin server. See Akamai Edge Response below for more details.

Sample Code Getting and Sending Sensor Data The following code snippet shows how to get the sensor data and send it in the HTTP request. // Import the SDK header #import <AkamaiBMP/CYFMonitor.h> //... //... // Example login button action - ( IBAction ) loginaction: ( id ) sender { // Get the BMP sensor data NSString * sensordata = [ CYFMonitor getsensordata ]; // Create the request. NSMutableURLRequest * request = [ NSMutableURLRequest requestwithurl:[ NSURL URLWithString: @"https://bmpapi.akamai.com/samples/v1/login" ]]; // set the sensor-data header [ request addvalue: sensordata forhttpheaderfield: @"X-acf-sensor-data" ]; } // send the request object using NSURLConnection or NSURLSession

ios API class CYFMonitor (added in Version 2.0.0) CYFMonitor provide methods to access the BMP SDK. All methods in this class are class methods and can be accessed from anywhere without creating an instance and methods can be invoked from any thread. See the individual method details for more information. Public Methods getsensordata + ( NSString * ) getsensordata ; Get the serialized user behavior data, device events and device information to be sent with the REST api that needs to be protected. Returns: NSString Serialized sensor data setloglevel + ( void ) setloglevel: ( CYFLogLevel ) loglevel ; Set the log level for the Akamai BMP SDK. See CYFLogLevel for a list of valid values. Parameters: loglevel CYFLogLevel: A valid log level value Enumeration

CYFLogLevel (added in Version 2.0.0) The log level to control the logging in the SDK. The values are used with CYFMonitor setloglevel method. Constants CYFLogLevelInfo CYFLogLevelWarn CYFLogLevelError Constant to log all messages from the SDK Constant to log all warning and error messages from the SDK Constant to log only error messages from the SDK CYFLogLevelNone Constant to log no messages from the SDK Logging Akamai BMP SDK logs some messages at all log levels to verify the SDK initialization. These messages are helpful in identifying any integration issue and ensure the SDK is initialized successfully. In addition to these messages, the SDK logs additional messages at info, warn and error levels, to verify and debug that the SDK is working correctly. The default log level for the SDK is to log warning and error messages only. This behavior can be changed by calling setloglevel API. To set the log level, call CYFMonitor setloglevel API with one of the log level specified below: // Set the log level to Info [ CYFMonitor setloglevel: CYFLogLevelInfo ]; These are the available logging levels: CYFLogLevelInfo - Print all messages. CYFLogLevelWarn - (Default) Print warning and error messages only. CYFLogLevelError - Print error messages only. CYFLogLevelNone - Turn off all log messages from the SDK. Akamai Edge

Application Identification Akamai edge server intercepts the REST API request and inspects X-acf-sensor-data header to determine if the request is from a BOT or a human user. The REST endpoint can be used by more than one application or platform or multiple version of the same application. The edge server uses the User-Agent HTTP header to identify the application that is integrated with the SDK. So we recommend using a standard format like Application-Name / Version-Number ( Platform-Information ) for the User-Agent header in the REST API request. Examples: HelloApp/1.2.3 (iphone; ios 11.2.1) MyFirstApp/1.1.2 (Android 7.0; Build/NRD90U) Akamai Edge Response When the app makes a request, Akamai evaluates the sensor data at the edge. If the request is classified as human, the traffic continues to the origin server and the response is sent back to the app. If the request is BOT, there are two possible actions, monitor and deny. If the action is monitor, the traffic is allowed and the request is sent to the origin server. If the action is deny, a 403 HTTP response is sent back to the app, and the app should handle the situation and take appropriate action. Hint: To differentiate a 403 response from your own origin server, check for AkamaiGHost in the Server HTTP response header, which would be a response from Akamai Edge server; your origin server will have a different value.

As the global leader in Content Delivery Network ( CDN ) services, Akamai makes the Internet fast, reliable, and secure for its customers. The company s advanced web performance, mobile performance, cloud security, and media delivery solutions are revolutionizing how businesses optimize consumer, enterprise, and entertainment experiences for any device, anywhere. To learn how Akamai solutions and its team of Internet experts are helping businesses move faster forward, please visit www.akamai.com or blogs.akamai.com, and follow @Akamai on Twitter. Akamai is headquartered in Cambridge, Massachusetts in the United States with operations in more than 57 offices around the world. Our services and renowned customer care are designed to enable businesses to provide an unparalleled Internet experience for their customers worldwide. Addresses, phone numbers, and contact information for all locations are listed on www.akamai.com/locations. 2018 Akamai Technologies, Inc. All Rights Reserved. Reproduction in whole or in part in any form or medium without express written permission is prohibited. Akamai and the Akamai wave logo are registered trademarks. Other trademarks contained herein are the property of their respective owners. Akamai believes that the information in this publication is accurate as of its publication date; such information is subject to change without notice. Published 01/18.