Configuration Properties

This page lists all configuration properties for each In-App Protection component. Properties shared across components are listed first, followed by component-specific sections.

Shared Properties

The following properties are available in every component, with the exception of the Redis properties which are not available in the Insight API. Replace <COMPONENT> with the environment variable prefix of the component, i.e. CONSOLEAPI, DEVICEAPI, INTEGRATIONAPI or INSIGHTAPI, e.g. IAP_DEVICEAPI_R2DBC_URL.

Redis Topologies

In-App Protection components connect to Redis through Lettuce and support both a single Redis instance (standalone) and a Redis OSS cluster. Redis is configured through component-specific IAP_<COMPONENT>_REDIS_* environment variables, which map onto the underlying Spring Data Redis (spring.data.redis.*) properties.

[!IMPORTANT] Do not configure Redis with a connection URL (SPRING_DATA_REDIS_URL). Use the discrete host/port (or cluster nodes) properties instead. A Redis URL forces standalone mode and silently overrides IAP_<COMPONENT>_REDIS_CLUSTER_NODES, breaking OSS cluster deployments. It also embeds the access key in a single string, which the components deliberately avoid in favour of a separate IAP_<COMPONENT>_REDIS_PASSWORD.

The Lettuce client is forced to use the RESP2 protocol. This is required for managed Redis services (such as Azure Managed Redis with the OSS cluster policy) whose nodes reject the unauthenticated HELLO handshake that the default RESP3 protocol performs before authentication.

Authentication and TLS

The following properties apply to both topologies. Leave them unset for an unauthenticated local Redis; set them for managed Redis services (such as Azure Managed Redis).

Standalone

A standalone instance is the default. Point the components at it with IAP_<COMPONENT>_REDIS_HOST / IAP_<COMPONENT>_REDIS_PORT as listed in the shared properties above. This is also the correct topology for managed Redis using the Enterprise cluster policy, where a proxy hides cluster routing behind a single endpoint.

OSS Cluster

To run against a Redis OSS cluster (for example Azure Managed Redis with the OSS cluster policy), activate the redis-cluster Spring profile and provide the cluster nodes:

SPRING_PROFILES_ACTIVE=redis-cluster
IAP_<COMPONENT>_REDIS_CLUSTER_NODES=node1:6380,node2:6380

The cluster properties live in a profile-specific resource (application-redis-cluster.properties) that is loaded only when the redis-cluster profile is active. While the profile is inactive (the default), the cluster configuration is absent and the component runs standalone — so the same image serves both topologies. Activating the profile switches the components to cluster mode; IAP_<COMPONENT>_REDIS_HOST / IAP_<COMPONENT>_REDIS_PORT are then ignored. The authentication and TLS variables above apply to both topologies.

[!NOTE] Activating the redis-cluster profile without setting IAP_<COMPONENT>_REDIS_CLUSTER_NODES fails fast at startup. Set both together, or neither.

[!TIP] IAP_<COMPONENT>_REDIS_CLUSTER_NODES only needs seed nodes, not the full cluster. Lettuce performs cluster topology discovery from any reachable seed and then keeps the topology current through adaptive and periodic refresh (see the variables below). For managed Redis with the OSS cluster policy (such as Azure Managed Redis), the service exposes a single stable endpoint — point IAP_<COMPONENT>_REDIS_CLUSTER_NODES at that one endpoint and the remaining nodes are discovered automatically.

The following variables are honoured only when the redis-cluster profile is active:

Asynchronous APK Processing

APK processing work is distributed to background workers through per-provider Redis Streams. Each configured provider gets its own work stream, consumer group and dead-letter stream.

The pipeline spans two components:

• The Device API is the producer. It publishes processing commands (through an outbox) to the streams.
• The Integration API is the consumer. It hosts the provider connectors that process the commands.

The role switches (enable the infrastructure, run the consumers, run the scheduled jobs) are configured per component, see Device API and Integration API, so both can be deployed in the same servlet container with different roles. The tables below describe the shared topology and tuning, which uses IAP_CORE_* variables.

Global Switches

Provider Streams

Each provider stream is configured through variables of the form IAP_CORE_ASYNCPROCESSING_REDIS_PROVIDERS_<NAME>_<PROPERTY>, where <NAME> is one of: INTERNALSCORING, VIRUSTOTAL, KOODOUS, ALIENVAULT, INTEZER, POLYSWARM, GOOGLEPLAY, HUAWEI.

Defaults shared by all provider streams are set through the IAP_CORE_ASYNCPROCESSING_REDIS_PROVIDERDEFAULTS_* variables below; the corresponding per-provider variable (..._PROVIDERS_<NAME>_<PROPERTY>) overrides the default for that provider only.

Publish Path

The following variables are shared by the outbox-based publish path that feeds all provider streams.

Processing Handler

The following properties tune the shared dispatching handler that routes each provider stream’s commands to the registered per-ProcessingType connector (e.g. VirusTotal) and drives the iap_apk_processing state row around its work. The claim lease/retry budgets are resolved per ProcessingType: IAP_CORE_ASYNCPROCESSING_PROCESSING_DEFAULTS_* sets the template applied to every processing type, and the corresponding IAP_CORE_ASYNCPROCESSING_PROCESSING_TYPES_<NAME>_* variable (where <NAME> is the provider name, e.g. virustotal) overrides any of the three knobs for that processing type only; an unset knob, or a type with no entry at all, falls back to the default.

Asynchronous APK Package-Lookup Processing

Package-lookup work (checking whether an APK is still present in an app store, for example Google Play or Huawei AppGallery) is distributed to background workers through its own store-isolated Redis Streams, mirroring Asynchronous APK Processing field-for-field but bound under a separate prefix and consumer group. The feature is disabled by default and, like provider processing, its role switches are configured per component (see the package-lookup switches in the Device API and Integration API sections). Claim lease/retry/deferral budgets for the underlying iap_apk_processing state rows are shared with provider processing and configured through the IAP_CORE_ASYNCPROCESSING_PROCESSING_* variables above (<NAME> being GOOGLEPLAY or HUAWEI).

Store Streams

Each store stream is configured through variables of the form IAP_CORE_ASYNCPROCESSING_PACKAGELOOKUP_REDIS_PROVIDERS_<NAME>_<PROPERTY>, where <NAME> is one of: GOOGLEPLAY, HUAWEI.

Defaults shared by all store streams are set through the IAP_CORE_ASYNCPROCESSING_PACKAGELOOKUP_REDIS_PROVIDERDEFAULTS_* variables below; the corresponding per-store variable (..._PROVIDERS_<NAME>_<PROPERTY>) overrides the default for that store only. These share the same defaults as the Provider Streams above, including the STREAMKEYPREFIX (iap-async-processing-queue-) — override it if store and provider stream keys must not collide.

Publish Path

The following variables are shared by the outbox-based publish path that feeds all store streams, including the job that re-drives DEFERRED state rows (for example after a provider quota resets) once their deferred_until timestamp elapses.

Device API

The Device API collects security telemetry from mobile applications and triggers configurable callback.

Callbacks

Callbacks enables integration with external systems by delivering security events to configured endpoints. For each monitored application, one or more callback URLs can be registered to receive notifications about security events. When such an event is generated, it is first written to a Redis Stream for asynchronous delivery by the Integration API.

Redis Publisher Configuration

The following properties control the Redis Stream used to queue and redeliver outgoing callback messages.

Device event callback configuration

The following properties configure device event callbacks.

Malware callback configuration

The following properties configure malware callbacks.

Device API Asynchronous Processing Switches

The Device API and the Integration API are configured independently, even when deployed in the same servlet container. See Asynchronous APK Processing for the shared topology and tuning.

Threat Level Suggestion

The following properties configure the rules by which the Device API assigns suggested threat level to APKs.

Probe Handling

The following property configures retry behavior for probe request handling, which retries the whole request on a fresh transaction if concurrent probes race on a duplicate-key or optimistic-locking conflict.

Integration API

The Integration API consumes callback events from the Redis Stream and dispatches them as HTTP requests to external URLs registered per application. It also consumes email events from the Redis Stream and delivers them via the Gmail API.

Callbacks

Redis Consumer Configuration

The following properties control the Redis Stream consumer used to dispatch callback messages.

Web Client Configuration

The following properties control the HTTP client used to deliver callback requests, including timeouts and the circuit breaker that prevents repeated calls to unresponsive endpoints.

Event Queue

Write Configuration

The following properties control the bounded local retry applied when persisting an event into the queue.

Retention Configuration

The following properties control the scheduled job that purges event queue entries older than the retention window.

Truncate Configuration

The following properties control the on-demand event queue truncation triggered via the Integration API.

Emails

The Integration API consumes email events from the Redis Stream and delivers them via the Gmail API. Email delivery is enabled by default and requires Gmail API credentials to be configured. To disable it, set IAP_INTEGRATIONAPI_EMAIL_ENABLED=false.

Email Client Configuration

Google Mail Client

OAuth 2.0 credentials for the Google Mail API. These are required when email sending is enabled. The OAuth credential must be authorized with at least the gmail.send scope.

To obtain these credentials, create OAuth 2.0 credentials in the Google Cloud Console and request the refresh token.

Redis Consumer Configuration

The following properties control the Redis Stream consumer used to dispatch email messages.

Password Reset Email Content

You can customize both the subject line and the HTML body of the password reset email. These settings are optional, if not provided, the system will fall back to the default values.

If you provide a custom HTML template, it must include the ${PASSWORD_RESET_URL} placeholder to display the reset link to the user. Available placeholders are:

Integration API Asynchronous Processing Switches

The Device API and the Integration API are configured independently, even when deployed in the same servlet container. See Asynchronous APK Processing for the shared topology and tuning.

External APK Processing Connectors

The Integration API looks up APK signatures on external threat-intelligence providers as asynchronous APK processing sub-processings (see Asynchronous APK Processing). Each provider has its own connector and configuration section below.

VirusTotal

The Integration API can look up an APK’s SHA-256 signature on VirusTotal (API v3, lookup-only) as one of the asynchronous APK processing sub-processings. It is disabled by default and requires a VirusTotal API key to be configured.

Malware types and families are linked to an APK only when VirusTotal knows the file and either the VirusTotal verdict or the APK’s current suggested threat level is POTENTIALLY_UNWANTED_APP or worse. When no threat category or name resolves to a malware type or family, the existing VirusTotal relations are kept. Malware types come from the VirusTotal threat categories (mapping table iap_malware_type_vt_category), malware families from threat names matching a family name ignoring case and non-alphanumeric characters. An entry is selected when its engine count is at least max(floor, ceil(topCount * ratio)), where topCount is the highest engine count in the list; nothing is selected when topCount < floor.

The VirusTotal processor rates an APK MALWARE when at least MALICIOUSCOUNT engines, or at least the MALICIOUSRATIO share of all engines, report it as malicious.

Koodous

The Integration API can look up an APK’s SHA-256 signature on Koodous as one of the asynchronous APK processing sub-processings. It is disabled by default and requires a Koodous API key to be configured.

External APK Package-Lookup Connectors

The Integration API checks whether an APK’s package name is still present in an app store as one of the asynchronous APK package-lookup processings (see Asynchronous APK Package-Lookup Processing). Each store has its own connector and configuration section below.

Google Play

The Integration API can check whether an APK’s package name is currently present on the Google Play Store (public store listing page, unauthenticated) as one of the asynchronous APK package-lookup processings. It is disabled by default and requires no API key. The lookup is a best-effort HTTP-status heuristic — there is no official API for third-party package-existence checks — so an unexpected response from Google (for example an interstitial page) could in principle be misclassified. The listing is served per the region of the server’s IP address, so a package that is unavailable in that region is reported as not found even if it is still in the store elsewhere; “not found” therefore does not necessarily mean “removed from the store”. A redirect to another host (e.g. a consent page) is treated as a communication error and retried.

Huawei AppGallery

The Integration API can check whether an APK’s package name is currently present in Huawei AppGallery (public package-detail endpoint, unauthenticated) as one of the asynchronous APK package-lookup processings. It is disabled by default and requires no API key. The lookup is a best-effort heuristic — there is no official API for third-party package-existence checks — the package is considered found when the response contains the configured AppGallery app URL prefix, so a change of the response format could misclassify packages.

Console API

The Console API provides the backend for the Console Web. It handles authentication, user management, and access to operational data.

TOTP (Two-Factor Authentication)

Console users can secure their accounts with a time-based one-time password (TOTP). The following properties configure code generation and QR code rendering for authenticator app setup.

Password Reset

These properties control the self-service password reset flow, including the security token generated and included in the password reset link sent to the user.

Email

The Console API publishes email events to a Redis Stream for asynchronous delivery by the Integration API.

Redis Publisher Configuration

The following properties control how the Console API writes outgoing email messages to the Redis Stream, including retry behaviour when publishing fails.

Logstash

Logstash polls the PostgreSQL database for new security events and ships them to Elasticsearch. All connection details are provided via environment variables.