How do I resolve AWS WAF mobile application integration SDK issues?

Resolution

Resolve missing dependency errors for Android

If your Android project fails to compile and you receive unresolved class errors, then the AWS WAF mobile SDK is missing required runtime dependencies. The SDK requires Gson v2.8 or later and Bouncy Castle v1.67 or later.

To resolve this issue, complete the following steps:

1. Open your app-level build.gradle or build.gradle.kts file.

2. Add the following dependencies inside the dependencies block:

   implementation 'com.google.code.gson:gson:2.8.9'
   implementation 'org.bouncycastle:bcprov-jdk15on:1.67'

3. Sync your Gradle project, and then rebuild it.

Note: Dependencies can change between SDK releases, so check the SDK README file for the latest required dependency versions.

Resolve runtime crashes from ProGuard/R8 code shrinking for Android

If your Android app crashes at runtime with ClassNotFoundException or NoSuchMethodException errors, then R8/ProGuard is removing classes that the SDK requires. These errors typically reference Bouncy Castle or AWS WAF classes. This occurs only in release builds where code shrinking is active. The AWS WAF mobile SDK uses reflection or dynamic class loading for cryptographic operations, so ProGuard removes classes that appear unused at compile time.

To resolve this issue, complete the following steps:

1. Open your proguard-rules.pro file in the app module.

2. Add the following keep rules:

   -keep class org.bouncycastle.crypto.** { *; }
   -keep class com.amazonaws.waf.* { *; }

3. Rebuild your release variant, and then confirm that the crash no longer occurs.

Note: Required keep rules can change between SDK versions, so review the SDK README file for the latest ProGuard configuration.

Resolve an AWS WAF token that isn't attached to network requests for Android and iOS

If your application successfully calls getToken() but your backend returns "403 Forbidden" responses, then no token is attached to your HTTP requests. A token might not be attached because the request initiated before the asynchronous token retrieval completes. Or, the network layer doesn't add the token to the correct header or cookie.

To resolve this issue, take the following actions:

• Verify that your code waits for the result of getToken() before it makes the network request.
• Confirm that you attached the token value as one of the following:
  The x-aws-waf-token HTTP header
  The aws-waf-token cookie
• To confirm that the token exists, use the Network Inspector in Android Studio, Xcode Instruments Network tool, or Charles Proxy to capture the outgoing request.
• For Android, review your App Activities, Fragments, or network layer code to confirm that you initialized the SDK before network calls.
• For iOS, review your AppDelegate, SceneDelegate, View Controllers, or network service classes to confirm that the initialization order is correct.

Resolve token validation failures from a domain mismatch

If AWS WAF rejects requests with the awswaf:managed:token:rejected:domain_mismatch label, then the request domain doesn't match your web ACL token domain list. AWS WAF scopes tokens to specific domains and rejects them when it's presented to a domain that isn't on the list.

To resolve this issue, complete the following steps:

1. Identify the domain that your app sends requests to, such as api.example.com.
2. Open the AWS WAF console.
3. Select your web ACL, and then choose Manage details.
4. In the Token domains section under Protection pack (web ACL) behavior, confirm that the list includes your app's domain. If the domain isn't listed, then add it to the list.
5. Wait a few minutes for the configuration to propagate, and then retry the token validation.

Resolve SDK version incompatibility for Android and iOS

If the SDK version doesn't support your target platform or operating system (OS) version, then the following issues occur:

• The SDK doesn't initialize.
• The SDK produces unexpected exceptions during getToken() calls.
• The SDK shows inconsistent behavior.

To resolve this issue for Android, complete the following steps:

1. Open your app-level build.gradle file, and then check the targetSdk and minSdk values in the defaultConfig block.
2. Identify your AWS WAF SDK version from the com.amazonaws.waf:waf-mobile-sdk:{VERSION} dependency declaration.
3. Cross-reference the values with the SDK README file to confirm compatibility.
4. If the app crashes, then copy the full stack trace from the Logcat window in Android Studio. To identify when the failure occurred, include all frames that relate to the application and the AWS SDK.

To resolve this issue for iOS, complete the following steps:

1. Choose Xcode, and then choose About Xcode to get your Xcode version.
2. Choose Settings, choose General, and then choose About to get the iOS version on your test device or simulator.
3. Identify the SDK version from the zip file that you downloaded from the AWS Management Console.
4. To check the compatibility, see AWS WAF mobile SDK specification.
5. If the app crashes, then open the Debug Navigator in Xcode and note the full stack trace. To get the complete trace, choose All Threads.
6. If you use CocoaPods, then review your Podfile and Podfile.lock for version conflicts. If you use Swift Package Manager, then check the resolved package versions in Xcode.

Related information

AWS WAF mobile application integration

How the AWS WAF mobile SDK works

Installing the AWS WAF mobile SDK

Code examples for the AWS WAF mobile SDK