Verify RequestShield tokens with Java

If you are new to RequestShield, start with the Introduction.

RequestShield Backend SDK verifies tokens received from the Browser SDK and returns the decision that the application backend must enforce. The SDK client is configured once and invoked before each protected operation.

Prerequisites

• Java 8 or newer.
• The App Key used by the Browser SDK.
• The backend-only API Secret supplied by IntelliFend.
• Access to the IntelliFend Maven repository.

Value	Where to use it	Description
App Key	Browser and backend	Public application identifier. The same value must be configured in both SDKs.
API Secret	Backend only	Private credential used by the Backend SDK. Store it in a secret manager.

The API Secret must not be exposed in browser code, client-visible responses, source control, or logs.

1. Add the Java dependency

Configure the IntelliFend Maven repository and declare IntelliFend Client 1.3.0.

Maven

pom.xml

<repositories>
  <repository>
    <id>intellifend-maven</id>
    <url>https://sdk.intellifend.com/packages/maven</url>
  </repository>
</repositories>

<dependencies>
  <dependency>
    <groupId>com.intellifend.sdk</groupId>
    <artifactId>intellifend-client</artifactId>
    <version>1.3.0</version>
  </dependency>
</dependencies>

Gradle

build.gradle.kts

repositories {
    maven {
        url = uri("https://sdk.intellifend.com/packages/maven")
    }
}

dependencies {
    implementation("com.intellifend.sdk:intellifend-client:1.3.0")
}

The IntelliFend Client includes the compatible RequestShield Backend SDK. A separate RequestShield dependency is not required.

2. Configure the client

Create one RequestShieldClient for each App Key and reuse it across requests:

import com.intellifend.requestshield.RequestShieldClient;

RequestShieldClient requestShield = RequestShieldClient.builder()
    .appKey(System.getenv("REQUESTSHIELD_APP_KEY"))
    .apiSecret(System.getenv("REQUESTSHIELD_API_SECRET"))
    .build();

Builder method	Required	Description
appKey(String)	Yes	Sets the same public App Key used by the Browser SDK.
apiSecret(String)	Yes	Sets the backend-only API Secret. Pass the supplied value unchanged.
build()	N/A	Validates the configuration and returns a thread-safe client.

3. Verify a protected request

Read the token from the request and pass it directly to verify():

import com.intellifend.requestshield.VerificationResult;

String token = request.getHeader("X-IntelliFend-Token");
VerificationResult result = requestShield.verify(token);

if (!result.isAllowed()) {
    rejectRequest();
    return;
}

continueRequest();

Pass the request header value unchanged to verify(), including an empty string. The method returns the decision that the application backend must enforce.

important

result.isAllowed() must be enforced before running the protected operation. The Browser SDK result is not an access-control decision.

Verification result

verify(String token) returns a VerificationResult:

Method	Returns	Description
isAllowed()	boolean	Returns whether the backend should continue processing the request.
getReason()	VerificationReason	Returns the stable reason for the decision.

getReason() returns one of the following enum values. getCode() returns the corresponding lowercase value for controlled diagnostics and metrics.

VerificationReason	getCode()	isAllowed()	Meaning
OK	ok	true	Token verification and consume succeeded.
MISSING_TOKEN	missing_token	false	The request did not contain a token.
UNKNOWN_CUSTOMER	unknown_customer	false	The token belongs to a different App Key.
TOKEN_TAMPERED	token_tampered	false	The token is malformed, altered, or otherwise invalid.
TOKEN_EXPIRED	token_expired	false	The token is outside its validity period.
TOKEN_REPLAYED	token_replayed	false	The token was already consumed.
CONSUME_UNAUTHORIZED	consume_unauthorized	false	The consume service rejected the configured API Secret.
INVALID_REQUEST	invalid_request	false	The service rejected the SDK request as invalid.
NOT_FOUND	not_found	false	The configured service endpoint was not found.
SERVICE_UNAVAILABLE	service_unavailable	true	Protection was unavailable and the fixed fail-open policy was applied.

SERVICE_UNAVAILABLE is the only non-OK reason associated with an allowed result.

Use result.getReason().getCode() for controlled diagnostics and metrics. The value returned by isAllowed() must not be overridden based on a reason code.

Security requirements

• The API Secret must remain in backend secret storage.
• The same App Key must be configured in the Browser SDK and Backend SDK.
• Obtain and verify a fresh token for every protected request.
• Pass the token value unchanged to verify().
• Enforce isAllowed() before processing the protected operation.
• Raw tokens, decoded claims, and the API Secret must not be logged or persisted.