{"id":19745171,"url":"https://github.com/castle/castle-java","last_synced_at":"2025-04-30T07:33:56.394Z","repository":{"id":15091023,"uuid":"76383371","full_name":"castle/castle-java","owner":"castle","description":"Java bindings for Castle","archived":false,"fork":false,"pushed_at":"2024-03-25T13:15:42.000Z","size":643,"stargazers_count":8,"open_issues_count":0,"forks_count":11,"subscribers_count":17,"default_branch":"master","last_synced_at":"2024-03-26T15:00:44.485Z","etag":null,"topics":["castle","fraud-detection","fraud-prevention","java","sdk"],"latest_commit_sha":null,"homepage":"https://castle.io","language":"Java","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/castle.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null}},"created_at":"2016-12-13T17:41:17.000Z","updated_at":"2024-02-23T07:28:49.000Z","dependencies_parsed_at":"2023-12-22T11:44:32.473Z","dependency_job_id":"7530a728-b818-4fa1-a988-dd19dcdfcf7e","html_url":"https://github.com/castle/castle-java","commit_stats":null,"previous_names":[],"tags_count":24,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/castle%2Fcastle-java","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/castle%2Fcastle-java/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/castle%2Fcastle-java/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/castle%2Fcastle-java/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/castle","download_url":"https://codeload.github.com/castle/castle-java/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":224202878,"owners_count":17272807,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["castle","fraud-detection","fraud-prevention","java","sdk"],"created_at":"2024-11-12T02:04:32.819Z","updated_at":"2025-04-30T07:33:56.387Z","avatar_url":"https://github.com/castle.png","language":"Java","funding_links":[],"categories":["java"],"sub_categories":[],"readme":"# Java SDK for Castle\n\n[![CircleCI](https://circleci.com/gh/castle/castle-java.svg?style=svg)](https://circleci.com/gh/castle/castle-java) [![Maintainability](https://api.codeclimate.com/v1/badges/ef9e24a1fb8ebf7b4218/maintainability)](https://codeclimate.com/github/castle/castle-java/maintainability) [![Test Coverage](https://api.codeclimate.com/v1/badges/ef9e24a1fb8ebf7b4218/test_coverage)](https://codeclimate.com/github/castle/castle-java/test_coverage)\n\n**[Castle](https://castle.io) analyzes user behavior in web and mobile apps to stop fraud before it happens.**\n\n# Usage\nSee the [documentation](https://docs.castle.io) for how to use this SDK with the Castle APIs\n\n# Quickstart\n\nWhen using Maven, add the following dependency to your `pom.xml` file:\n```xml\n        \u003cdependency\u003e\n            \u003cgroupId\u003eio.castle\u003c/groupId\u003e\n            \u003cartifactId\u003ecastle-java\u003c/artifactId\u003e\n            \u003cversion\u003e2.6.0\u003c/version\u003e\n        \u003c/dependency\u003e\n```\n\n## Initialize the SDK\n\nGo to the settings page of your Castle account and find your **API Secret**\n\n**Alt 1. Initialize using ENV variables**\n\nOn 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.\n\n```java\nCastle castle = Castle.initialize();\n```\n\n**Alt 2. Initialize using API secret only**\n\n```java\nCastle castle = Castle.initialize(\"abcd\");\n```\n\n\n**Alt 3. Initialize using configuration builder**\n\nIf you don't use ENV variables, you can set the secret programatically together\nwith other options by using `CastleConfigurationBuilder`. `Castle.configurationBuilder()`\nreturns a configuration builder initialized with default settings.\n\n```java\nCastle castle = Castle.initialize(\n  Castle.configurationBuilder()\n    .apiSecret(\"abcd\")\n    .enableHttpLogging(true) // Log all outgoing requests sent to Castle\n    .build()\n);\n```\nAll other settings will be set to their default values.\n\nWe can also maintain a global instance wich can be set the following way\n\n```java\nCastle.setSingletonInstance(castle);\n\n// Use the singleton\nCastle.instance().client().filter(...);\n```\n\n# Configuring the SDK\n\n## Settings\n\nBefore running an application that uses the Castle Java SDK,\nthere is one that must be configured:\n\n * **API Secret**: a secret that will be used for authentication purposes.\n\nIf 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.\n\nBesides the aforementioned settings, the following are other application-level setting\nthat can be optionally configured:\n\n * **Denylisted Headers**: a comma-separated list of strings representing HTTP headers that will\n never get passed to the context object. See [The Context Object](#the-context-object).\n * **Allowlisted Headers**: this is a comma-separated list of strings representing HTTP headers\n that will get passed to the context object with each call to the Castle API,\n unless they are denylisted. If not set or empty all headers will be sent. See [The Context Object](#the-context-object).\n * **Authenticate Failover Strategy**: it can be set to `ALLOW`, `DENY`, `CHALLENGE` or `THROW`.\n See also [Authenticate](#authenticate)\n * **Timeout**: an integer that represents the time in milliseconds after which a request fails.\n * **Backend Provider**: The HTTP layer that will be used to make requests to the Castle API.\n Currently there is only one available and it uses [OkHttp](https://square.github.io/okhttp/).\n * **Base URL**: The base endpoint of the Castle API without any relative path.\n * **IP Headers**: The headers checked (in order) to use for the context IP.\n\nAllowlist and Denylist are case-insensitive.\n\nIf the value of any of these keys is left unspecified, the client will be configured with their default values.\nSee *[Where to Configure Settings](#where-to-configure-settings)* for a list of the default values.\n\n## Where to Configure Settings\n\nSettings can be provided as a Java Properties file in the classpath, through\nenvironmental variables or through methods calls on `CastleConfigurationBuilder`\nWhen two of these options are used, environmental variables take precedence over the Java\nProperties file.\n\nThe following table shows the default value for each setting.\nIt also shows the key that can be used to set its value in a Properties file.\nFinally, it also contains the environmental variable that can be used instead of the key in the Java Properties file:\n\nSetting | Default values, when they exist | Properties file key | Environment variable |\n--- | --- |---------------------| --- |\nAPI Secret |   | `api_secret`        | `CASTLE_API_SECRET` |\nAllowlisted Headers |   | `allow_list`        | `CASTLE_SDK_ALLOWLIST_HEADERS` |\nDenylisted Headers | `Cookie` | `deny_list`         | `CASTLE_SDK_DENYLIST_HEADERS` |\nTimeout | `500` | `timeout`           | `CASTLE_SDK_TIMEOUT` |\nAuthenticate Failover Strategy | `ALLOW` | `failover_strategy` | `CASTLE_SDK_AUTHENTICATE_FAILOVER_STRATEGY` |\nBackend Provider | `OKHTTP` | `backend_provider`  | `CASTLE_SDK_BACKEND_PROVIDER` |\nBase URL | `https://api.castle.io/` | `base_url`          | `CASTLE_SDK_BASE_URL` |\nLog HTTP | false | `log_http`          | `CASTLE_SDK_LOG_HTTP` |\nIP Headers |  | `ip_headers`        | `CASTLE_SDK_IP_HEADERS` |\n\nBy default, the SDK will look in the classpath for the Java Properties file named `castle_sdk.properties`.\nAn alternative file can be chosen by setting the `CASTLE_PROPERTIES_FILE` environment variable to a different value.\n\nThe following is a sample Java Properties file containing all of the settings that can be\nmodified:\n\n```properties\napi_secret=\nallow_list=User-Agent,Accept-Language,Accept-Encoding,Accept-Charset,Accept,Accept-Datetime,X-Forwarded-For,Forwarded,X-Forwarded,X-Real-IP,REMOTE_ADDR\ndeny_list=Cookie\ntimeout=500\nbackend_provider=OKHTTP\nfailover_strategy=ALLOW\nbase_url=https://api.castle.io/\nlog_http=false\nip_headers=\n```\n\nTo configure using the `CastleConfigurationBuilder` use the corresponding method to set the values\n\n```builder\nCastle castle = Castle.initialize(Castle.configurationBuilder()\n    .apiSecret(\"abcd\")\n    .withAllowListHeaders(\"User-Agent\", \"Accept-Language\", \"Accept-Encoding\")\n    .withDenyListHeaders(\"Cookie\")\n    .withTimeout(500)\n    .withBackendProvider(CastleBackendProvider.OKHTTP)\n    .withAuthenticateFailoverStrategy(new AuthenticateFailoverStrategy(AuthenticateAction.ALLOW))\n    .withApiBaseUrl(\"https://api.castle.io/\")\n    .withLogHttpRequests(true)\n    .ipHeaders(Arrays.asList(\"X-Forwarded-For\", \"CF-Connecting-IP\"))\n    .build());\n```\n\n### The Authenticate Failover Strategy\n\nIt is the strategy that will be used when a request to the `/v1/authenticate` endpoint\nof the Castle API fails.\nAlso, see [`doNotTrack` boolean](the-donottrack-boolean) for another use case of a failover strategy.\n\nIt can be one of the following options:\n* return a specific *authenticate action* inside an instance of `Verdict`;\n* throw an `io.castle.client.model.CastleRuntimeException`.\n\nSee [configuration](#configuring-the-sdk) to find out how to enable a failover strategy and to\nlearn about its default value.\n\n\n# Development branch\n\nBranch for development process. The castle-java-example application have a parallel dev branch for test proposes.\n\nTo use on example application dev branch, first install locally:\n\n    mvn clean install\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcastle%2Fcastle-java","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fcastle%2Fcastle-java","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcastle%2Fcastle-java/lists"}