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
- Request Arrival: For each HTTP/HTTPS request arriving at the API Gateway, the source IP address of the request is identified.
- 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?
- WS-Security Verification: Digital signature verification with selected truststore, then SOAP body is decrypted with decryption keystore; operation errors if keystore is not found.
- 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.
- 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: 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 4: 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 5: 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 6: 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 7: 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 8: 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. |
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. |