Amazon WAF mobile SDK specification
This section lists the SDK objects, operations, and configuration settings for the latest available version of the Amazon WAF mobile SDK. For detailed information about how the token provider and operations work for the various combinations of configuration settings, see How the Amazon WAF mobile SDK works.
WAFToken
-
Holds an Amazon WAF token.
getValue()
-
Retrieves the
String
representation of theWAFToken
.
WAFTokenProvider
-
Manages tokens in your mobile app. Implement this using a
WAFConfiguration
object.getToken()
-
If background refresh is enabled, this returns the cached token. If background refresh is disabled, this makes a synchronous, blocking call to Amazon WAF to retrieve a new token.
loadTokenIntoProvider(WAFToken)
-
Loads the specified token into the
WAFTokenProvider
, replacing any token that the provider was managing. The token provider takes ownership of the new token and handles refreshing it going forward. This operation also updates the token in the cookie store, ifsetTokenCookie
is enabled in theWAFConfiguration
. onTokenReady(WAFTokenResultCallback)
-
Instructs the token provider to refresh the token and invoke the provided callback when an active token is ready. The token provider will invoke your callback in a background thread when the token is cached and ready. Call this when your app first loads and also when it comes back to an active state. For more information about returning to an active state, see Retrieving a token following app inactivity.
For Android or iOS apps, you can set
WAFTokenResultCallback
to the operation that you want the token provider to invoke when a requested token is ready. Your implementation ofWAFTokenResultCallback
must take the parametersWAFToken
,SdkError
. For iOS apps, you can alternately create an inline function. storeTokenInCookieStorage(WAFToken)
-
Instructs the
WAFTokenProvider
to store the specified Amazon WAF token into the SDK’s cookie manager. By default, the token is only added to the cookie store when it's first acquired and when it's refreshed. If the application clears the shared cookie store for any reason, the SDK doesn't automatically add the Amazon WAF token back until the next refresh.
WAFConfiguration
-
Holds the configuration for the implementation of the
WAFTokenProvider
. When you implement this, you provide your web ACL’s integration URL, the domain name to use in the token, and any non-default settings that you want the token provider to use.The following list specifies the configuration settings that you can manage in the
WAFConfiguration
object.applicationIntegrationUrl
-
The application integration URL. Get this from the Amazon WAF console or through the
getWebACL
API call.Required: Yes
Type: App-specific URL. For iOS, see iOS URL
. For Android, see java.net URL . backgroundRefreshEnabled
Indicates whether you want the token provider to refresh the token in the background. If you set this, the token provider refreshes your tokens in the background according to the configuration settings that govern automatic token refresh activities.
Required: No
Type:
Boolean
Default value:
TRUE
domainName
-
The domain to use in the token, which is used in token acquisition and cookie storage. For example,
example.com
oraws.amazon.com
. This is usually the host domain of your resource that’s associated with the web ACL, where you’ll be sending web requests. For the ACFP managed rule group,AWSManagedRulesACFPRuleSet
, this will usually be a single domain that matches the domain in the account creation path that you provided in the rule group configuration. For the ATP managed rule group,AWSManagedRulesATPRuleSet
, this will usually be a single domain that matches the domain in the login path that you provided in the rule group configuration.Public suffixes aren't allowed. For example, you can't use
gov.au
orco.uk
as the token domain.The domain must be one that Amazon WAF will accept, based on the protected host domain and the web ACL's token domain list. For more information, see Amazon WAF web ACL token domain list configuration.
Required: Yes
Type:
String
maxErrorTokenRefreshDelayMsec
-
The maximum time in milliseconds to wait before repeating a token refresh after a failed attempt. This value is used after token retrieval has failed and been retried
maxRetryCount
times.Required: No
Type:
Integer
Default value:
5000
(5 seconds)Minimum value allowed:
1
(1 millisecond)Maximum value allowed:
30000
(30 seconds) maxRetryCount
-
The maximum number of retries to perform with exponential backoff when a token is requested.
Required: No
Type:
Integer
Default value: If background refresh is enabled,
5
. Otherwise,3
.Minimum value allowed:
0
Maximum value allowed:
10
setTokenCookie
Indicates whether you want the SDK’s cookie manager to add a token cookie into requests and in other areas.
With a
TRUE
value:The cookie manager adds a token cookie to all requests whose path is under the path specified in
tokenCookiePath
.The
WAFTokenProvider
operationloadTokenIntoProvider()
updates the token in the cookie store, in addition to loading it into the token provider.
Required: No
Type:
Boolean
Default value:
TRUE
tokenCookiePath
-
Used when
setTokenCookie
isTRUE
. Indicates the top-level path where you want the SDK’s cookie manager to add a token cookie. The manager adds a token cookie to all requests that you send to this path and to all child paths.For example, if you set this to
/web/login
, then the manager includes the token cookie for everything sent to/web/login
and any of its child paths, like/web/login/help
. It doesn't include the token for requests sent to other paths, like/
,/web
, or/web/order
.Required: No
Type:
String
Default value:
/
tokenRefreshDelaySec
-
Used for background refresh. The maximum amount of time in seconds between background token refreshes.
Required: No
Type:
Integer
Default value:
88
Minimum value allowed:
88
Maximum value allowed:
300
(5 minutes)