WS-Security (From Target)

You can verify SOAP responses through WS-Security signature and encryption checks and transmit decrypted content to client

This document explains the detailed usage of a specific policy. If you are using Apinizer policy structure for the first time or want to learn the general working principles of policies, we recommend reading the What is Policy? page first.

Overview

What is its Purpose?

• Guarantees integrity of SOAP responses coming from target system through API Proxy (API Proxy Server) with digital signature verification.
• Ensures correct transmission of sensitive data from backend by decrypting encrypted SOAP bodies with configured keystore information.
• Enforces WS-Security verification requirements in specific endpoint or header combinations through policy conditions.
• Facilitates root cause analysis by operation teams in integration errors with customizable error messages.

Working Principle

1. Request Arrival: For each HTTP/HTTPS request arriving at the API Gateway, the source IP address of the request is identified.
2. Policy Check: If the WS Security From Target policy is active, the system checks in the following order:
   • Is a Condition defined? If so, is the condition met?
   • Is the policy active (active=true)?
   • Is a Variable used or is Apinizer default?
3. WS-Security Verification: Digital signature verification with selected truststore, then SOAP body is decrypted with decryption keystore; operation errors if keystore is not found.
4. Decision Making:
   • Match Found: SOAP response is verified, decrypted if necessary, and transmitted to client.
   • No Match: Verification or decryption fails and defined error message is returned.
5. Error Handling: Customizable HTTP status code and error message are returned for requests that do not comply with the policy rule.

Features and Capabilities

Basic Features

• Decryption Support: Opens encrypted SOAP bodies coming from target system with selected keystore; alias and password information are read through Worker Context.
• Signature Verification Support: Verifies digital signatures with keystore defined as truststore, rejects untrusted certificates.
• Dynamic Policy Conditions: Manages endpoint, header, or IP-based rule combinations with Query Builder integration.
• Active/Passive Status Control: Easily change the active or passive status of the policy (active/passive toggle). In passive state, the policy is not applied but its configuration is preserved.
• Condition-Based Application: Determine when the policy will be applied by creating complex conditions with Query Builder (e.g., only for specific endpoints or header values).

Advanced Features

• Multi-Environment Keystore Access: Automatically selects keystore environment in active project context, works transparently in Production Environment transitions.
• Case Insensitive Signature ID Option: Compares XML Signature ID values case-insensitively when allowCaseInsensitiveId field is enabled.
• Policy Flow Synchronization: Triggers policy updates in real-time with Event Manager, warns users on global policy changes.
• Export/Import Feature: Export policy configuration as a ZIP file. Import to different environments (Development, Test, Production). Version control and backup capability.
• Policy Group and Proxy Group Support: Manage multiple policies within Policy Group. Bulk policy assignment to Proxy Groups. Centralized update and deployment operations.
• Deploy and Versioning: Deploy policy changes to live environment. See which API Proxies use it (Policy Usage). Proxy Group and Policy Group usage reports.

Usage Scenarios

Scenario	Situation	Solution (Policy Application)	Expected Behavior / Result
Target Signature Verification	SOAP response arrives signed	Open Signature Verification toggle, select trusted truststore.	Response is verified, fake signatures return 403.
Service Requiring Decryption	Target service encrypts body with AES	Open Decryption toggle, match relevant keystore.	Body is decrypted, client receives plain text.
Critical Endpoint Protection	Control needed only for /billing/* request	Define Path equals /billing/* with Condition.	WS-Security check is performed only at critical endpoint.
Invalid Certificate Block	Response arrives with fake certificate	Select truststore containing trusted root.	Response is rejected, customized error message is returned.
Multi-Environment Management	Test and Production Environment use different keystores	Use global policy with environment-specific keystore IDs.	Environment-based keystore is automatically loaded after deploy.
Error Message Customization	Integration team wants detailed message	Define custom JSON in Error Message tab.	403 response contains custom error code and explanation.

Configuring Policy Parameters

At this step, users can create a new policy or configure existing policy parameters to define access rules. The defined parameters directly affect how the policy works (e.g., which IPs will be allowed, geographical restrictions, conditional activations, etc.). This way, the policy can be customized according to organization-specific requirements and managed centrally.

Creating a New WS Security From Target Policy

Configuration Steps

Step	Description / Operation
Step 1: Going to Creation Page	- Go to Development → Global Settings → Global Policies → WS Security From Target section from the left menu. - Click the [+ Create] button at the top right.
Step 2: Entering Basic Information	Policy Status: Shows Active/Passive status. New policies are active by default. Name (Required): Example: Production_WS_FromTarget - Enter a unique name, it cannot start with a space. - System automatically checks. Green checkmark: available. Red cross: existing name. Description: Example: “WS-Security verification and decryption” - Max. 1000 characters. - Explain the purpose of the policy.
Step 3: Variable Usage	- In the action button area at the top of the page, you can use the [<> Variable] button to select dynamic values. - Using context/global variable expressions, you can manage policy parameters with variable-based values instead of fixed values. - This reduces manual update effort when values change and provides operational convenience. - For detailed information, review Dynamic Variables.
Step 4: Configuring Decryption Parameters	- Indicate that encrypted SOAP bodies will be decrypted by enabling Decryption (decExists) toggle. - Select appropriate keystore ID from Decryption Keystore list. - Create new record with Add KeyStore dialog if keystore does not exist yet. - Policy becomes invalid and saving is blocked when keystore is not selected.
Step 5: Signature Verification Parameters	- Make digital signature control mandatory by opening Signature Verification (verExists) toggle. - Select trusted certificate store in Signature Verification Keystore field. - Truststore should only contain root/intermediate certificates, should not contain private key. - Toggle can be left closed for services without response signature.
Step 6: Keystore Management and Synchronization	- Records created with Add KeyStore dialog are automatically added to list. - No need to refresh page to keep list current when new keystore arrives. - Alias and password information are read through Worker Context; wrong alias selection makes signature verification fail. - Close KeyStore dialog when needed to verify that selection is processed in form field.
Step 7: Defining Condition (Optional)	- Go to the Condition tab. - Conditions determine when the policy will be active. Examples: - Environment-based: Header = X-Environment, Operator = Equals, Value = production - API Key-based: Header = X-API-Key, Starts With = PROD- - Endpoint-based: Path = /api/admin/* If no condition is defined, the policy is always active For details, you can refer to: Conditions
Step 8: Customizing Error Message (Optional)	- Go to the Error Message Customization tab. - Customize the message to be returned when access is denied. Default: { "statusCode": 403, "message": "[Default error message]" } Custom: { "statusCode": 403, "errorCode": "[CUSTOM_ERROR_CODE]", "message": "[Custom message]" }
Step 9: Saving	- Click the [Save] button at the top right. Checklist: Unique name. Required fields filled. At least one WS-Security check active. Result: - Policy is added to the list. - Can be linked to APIs. - If it’s a global policy, it is automatically applied.

For the description of Conditions and Error Message Customization panels, you can review the Conditions and Error Message Customization sections on the What is Policy? page.

For a complete guide on all layers, priority order and scenario examples of the error message configuration system, see the Error Message Configuration Guide page.

Deleting the Policy

For the deletion steps of this policy and the operations to be applied when it is in use, you can refer to the Removing Policy from Flow section on the Policy Management page.

Exporting/Importing the Policy

For the export and import steps of this policy, you can refer to the Export/Import page.

Linking the Policy to API

For the process of how this policy will be linked to APIs, you can refer to the Linking Policy to API section on the Policy Management page.

Advanced Features

Feature	Description and Steps
Decryption and Verification Order	- Verification starts with WSSecurityEngine. - Decryption comes into play after successful signature. - Policy produces error if both steps fail.
Case Insensitive ID Option	- When allowCaseInsensitiveId is enabled, signature ID comparisons are made case-insensitively. - Supports alternative ID usage in XML Signature element. - Wrong configuration can invalidate signature verification.
Dynamic Keystore Update	- Worker Context resolves keystore according to active environment. - Policy retrieves current data without additional processing when new keystore is deployed. - Password updates are reflected instantly.

Best Practices

Things to Do and Best Practices

Category	Description / Recommendations
Keystore Management	Bad: Sharing same keystore with all environments. Good: Creating environment-based keystore. Best: Automatically retrieving keystores from secret management system.
Policy Conditions	Bad: Running unconditionally on all endpoints. Good: Filtering critical endpoints. Best: Reducing attack surface by combining with Rate Limiting.
Error Message Management	Bad: Not changing default 403 message. Good: Indicating which step the error occurred in. Best: Adding operation reference code and tracking ID.
Multi-Environment Deployment	Bad: Using Production Environment keystore in test. Good: Performing export/import in environment transitions. Best: Running automatic import and verification in deploy pipeline.
Test Strategy	Bad: Only performing manual test. Good: Verifying signature with SOAP UI scripts. Best: Running automatic WS-Security regression tests in CI/CD pipeline.

Security Best Practices

Security Area	Description / Warnings
Truststore Hygiene	Do not add untrusted certificates to list; renew certificate chain at regular intervals.
Keystore Passwords	Store passwords in secret vault, never keep in source code.
Case Insensitive ID Usage	Enable this feature only if target service creates ID inconsistency; otherwise unnecessary flexibility may increase attack surface.
Logging	Log signature subject and keystore alias information masked in error cases.
Authorization	Give policy editing permission only to users with WS-Security expertise.

Things to Avoid

Category	Description / Warnings
Default Keystore Usage	Why avoid: If all environments share same key, security breach risk increases. Alternative: Apply environment-based keystore and password management.
Closing All Checks	Why avoid: Policy cannot be saved without at least one security step; bypass attempts create security vulnerability. Alternative: Keep at least one check active, run both steps in parallel if needed.
Missing Error Message	Why avoid: If error message is left empty, integration teams cannot find root cause. Alternative: Add correlation ID to error message.
Certificate Expiration Tracking	Why avoid: Expired certificate rejects all requests. Alternative: Set up warning mechanism for certificate expiration dates.

Performance Tips

Criterion	Recommendation / Impact
SOAP Message Size	Recommendation: Reduce unnecessary namespace and whitespace. Impact: WS-Security processing time decreases.
Keystore Size	Recommendation: Limit truststore to only necessary certificates. Impact: Loading and verification time decreases.
Thread Pool	Recommendation: Adjust Gateway worker thread count according to WS-Security processing load. Impact: Parallel SOAP verification performance increases.
Cache Usage	Recommendation: Enable Gateway cache mechanism in certificate chain verification. Impact: Repeated signature verifications speed up.
Monitoring	Recommendation: Monitor WS-Security error rates as metric. Impact: Performance or certificate issues are detected early.

Frequently Asked Questions (FAQ)

Category	Question	Answer
General	Should I use the policy only in SOAP services?	Yes, WS Security From Target targets SOAP WS-Security standards; ineffective in REST services.
General	Why must I keep at least one check active?	Signature verification or decryption must be performed for policy to achieve its purpose; otherwise policy is unnecessary and saving is blocked.
Technical	Why might signature verification fail?	May be due to wrong truststore, expired certificate, or different canonicalization algorithm; check PolicyWSSecurityFromException details in logs.
Technical	Which keystore formats are supported for decryption?	JKS and P12 types are supported through Worker Context; alias and password must be correct.
Usage	Can I convert global policy to local policy?	Global policy is copied and made API-specific with Localize button on detail page.
Usage	How do I check before deploy?	You can test by importing exported ZIP to Development environment, run signature/encryption tests with SOAP UI.