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 pom.xml file:
<dependency>
<groupId>io.castle</groupId>
<artifactId>castle-java</artifactId>
<version>2.4.2</version>
</dependency>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 CastleConfigurationBuilder. Castle.configurationBuilder()
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(...);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
ALLOW,DENY,CHALLENGEorTHROW. 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.
Settings can be provided as a Java Properties file in the classpath, through
environmental variables or through methods calls on CastleConfigurationBuilder
When two of these options are used, environmental variables take precedence over the Java
Properties file.
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 |
|---|---|---|---|
| API Secret | api_secret |
CASTLE_API_SECRET |
|
| Allowlisted Headers | allow_list |
CASTLE_SDK_ALLOWLIST_HEADERS |
|
| Denylisted Headers | Cookie |
deny_list |
CASTLE_SDK_DENYLIST_HEADERS |
| Timeout | 500 |
timeout |
CASTLE_SDK_TIMEOUT |
| Authenticate Failover Strategy | ALLOW |
failover_strategy |
CASTLE_SDK_AUTHENTICATE_FAILOVER_STRATEGY |
| Backend Provider | OKHTTP |
backend_provider |
CASTLE_SDK_BACKEND_PROVIDER |
| Base URL | https://api.castle.io/ |
base_url |
CASTLE_SDK_BASE_URL |
| Log HTTP | false | log_http |
CASTLE_SDK_LOG_HTTP |
| IP Headers | ip_headers |
CASTLE_SDK_IP_HEADERS |
By default, the SDK will look in the classpath for the Java Properties file named castle_sdk.properties.
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());It is the strategy that will be used when a request to the /v1/authenticate endpoint
of the Castle API fails.
Also, see 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
Verdict; - throw an
io.castle.client.model.CastleRuntimeException.
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