Java SDK for Castle
Castle analyzes user behavior in web and mobile apps to stop fraud before it happens.
See the documentation for how to use this SDK with the Castle APIs
When using Maven, add the following dependency to your
<dependency> <groupId>io.castle</groupId> <artifactId>castle-java</artifactId> <version>2.3.0</version> </dependency>
Initialize the SDK
Go to the settings page of your Castle account and find your API Secret
Alt 1. Initialize using ENV variables
On initialization the Castle SDK will look for the secret in the
CASTLE_API_SECRET environment variable. If it is set, no options needs to be passed to the initializer.
Castle castle = Castle.initialize();
Alt 2. Initialize using API secret only
Castle castle = Castle.initialize("abcd");
Alt 3. Initialize using configuration builder
If you don't use ENV variables, you can set the secret programatically together
with other options by using
returns a configuration builder initialized with default settings.
Castle castle = Castle.initialize( Castle.configurationBuilder() .apiSecret("abcd") .enableHttpLogging(true) // Log all outgoing requests sent to Castle .build() );
All other settings will be set to their default values.
We can also maintain a global instance wich can be set the following way
Castle.setSingletonInstance(castle); // Use the singleton Castle.instance().client().filter(...);
Java 7 configuration
To use the library on a java 7 environment, switch the guava library to the following version:
<dependency> <groupId>io.castle</groupId> <artifactId>castle-java</artifactId> <version>1.0.3</version> <exclusions> <exclusion> <groupId>com.google.guava</groupId> <artifactId>guava</artifactId> </exclusion> </exclusions> </dependency> <dependency> <groupId>com.google.guava</groupId> <artifactId>guava</artifactId> <version>23.0-android</version> </dependency>
Configuring the SDK
Before running an application that uses the Castle Java SDK, there is one that must be configured:
- API Secret: a secret that will be used for authentication purposes.
If the API Secret is not provided, the client's initialization process will fail. It can be found in the settings page of the Castle dashboard.
Besides the aforementioned settings, the following are other application-level setting that can be optionally configured:
- Denylisted Headers: a comma-separated list of strings representing HTTP headers that will never get passed to the context object. See The Context Object.
- Allowlisted Headers: this is a comma-separated list of strings representing HTTP headers that will get passed to the context object with each call to the Castle API, unless they are denylisted. If not set or empty all headers will be sent. See The Context Object.
- Authenticate Failover Strategy: it can be set to
THROW. See also Authenticate
- Timeout: an integer that represents the time in milliseconds after which a request fails.
- Backend Provider: The HTTP layer that will be used to make requests to the Castle API. Currently there is only one available and it uses OkHttp.
- Base URL: The base endpoint of the Castle API without any relative path.
- IP Headers: The headers checked (in order) to use for the context IP.
Allowlist and Denylist are case-insensitive.
If the value of any of these keys is left unspecified, the client will be configured with their default values. See Where to Configure Settings for a list of the default values.
Where to Configure Settings
Settings can be provided as a Java Properties file in the classpath, through
environmental variables or through methods calls on
When two of these options are used, environmental variables take precedence over the Java
The following table shows the default value for each setting. It also shows the key that can be used to set its value in a Properties file. Finally, it also contains the environmental variable that can be used instead of the key in the Java Properties file:
|Setting||Default values, when they exist||Properties file key||Environment variable|
|Authenticate Failover Strategy||
By default, the SDK will look in the classpath for the Java Properties file named
An alternative file can be chosen by setting the
CASTLE_PROPERTIES_FILE environment variable to a different value.
The following is a sample Java Properties file containing all of the settings that can be modified:
api_secret= allow_list=User-Agent,Accept-Language,Accept-Encoding,Accept-Charset,Accept,Accept-Datetime,X-Forwarded-For,Forwarded,X-Forwarded,X-Real-IP,REMOTE_ADDR deny_list=Cookie timeout=500 backend_provider=OKHTTP failover_strategy=ALLOW base_url=https://api.castle.io/ log_http=false ip_headers=
To configure using the
CastleConfigurationBuilder use the corresponding method to set the values
Castle castle = Castle.initialize(Castle.configurationBuilder() .apiSecret("abcd") .withAllowListHeaders("User-Agent", "Accept-Language", "Accept-Encoding") .withDenyListHeaders("Cookie") .withTimeout(500) .withBackendProvider(CastleBackendProvider.OKHTTP) .withAuthenticateFailoverStrategy(new AuthenticateFailoverStrategy(AuthenticateAction.ALLOW)) .withApiBaseUrl("https://api.castle.io/") .withLogHttpRequests(true) .ipHeaders(Arrays.asList("X-Forwarded-For", "CF-Connecting-IP")) .build());
The Authenticate Failover Strategy
It is the strategy that will be used when a request to the
of the Castle API fails.
doNotTrack boolean for another use case of a failover strategy.
It can be one of the following options:
- return a specific authenticate action inside an instance of
- throw an
See configuration to find out how to enable a failover strategy and to learn about its default value.
Branch for development process. The castle-java-example application have a parallel dev branch for test proposes.
To use on example application dev branch, first install locally:
mvn clean install