Overview
What is its Purpose?
- Designed to ensure reliability of identity information by verifying JOSE/JWT tokens entering the API Proxy flow.
- Prevents unauthorized access and protects sensitive endpoints by enforcing specified issuer, audience, and claim rules.
- Provides clean data transfer to downstream services by securely decrypting encrypted JWE contents.
- Works integrated with centralized authorization policies in downstream services by broadcasting identity and role information at header level.
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 JOSE Verification 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 being used or is Apinizer default?
- JOSE Content Resolution: Token is read from specified source (body, Authorization header, or variable); if needed, decryption is performed with selected JWK and claim set is prepared for verification.
- Decision Making:
- Match Found: If signature/encryption is valid, claim and audience rules are met, and issuer ACL is approved, request continues in flow, user information is added to header if needed.
- No Match: If token cannot be resolved, signature cannot be verified, claim rules are violated, or ACL rejection occurs, request is terminated by policy.
- 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
- Flexible JOSE Target: Token can be read from body, Authorization header, or selected variable; dynamic selection can be made with Query Builder in variable scenarios.
- Granular Claim Verification: Multi-layer verification is configured by defining exact match rules with accepted audience, required and prohibited claim lists.
- Identity and Role Broadcasting: User identity and role information extracted from request can be carried to subsequent services via header, supporting centralized authorization control.
- Active/Passive Status Control: Easily change the active or passive status of the policy (active/passive toggle). In passive mode, 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
- JWK Lifecycle Management: Signature and encryption keys are managed with Secret Manager or manual JWK selections; necessary roles can define new keys.
- Issuer ACL and IP Control: Issuer-based permission list and client IP verification of request maker creates additional security layer.
- Claim Decode and Rewrite: Encrypted or base64 claims can be resolved and directed to body, header, or variable; partial decode is supported.
- 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 deploy 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 | Status | Solution (Policy Application) | Expected Behavior / Result |
|---|---|---|---|
| Mobile JWT Verification | Mobile app carries JWT in Authorization header | joseTarget=AUTHORIZATION_HEADER, validateSign=true, use issuer JWKS | Valid token is accepted, invalid signatures return 401 |
| IoT JWE Resolution | IoT devices send encrypted payload | decrypt=true, decryptByIssuer=false, select encryption JWK | Payload is decrypted, content is transferred to downstream services |
| Issuer Whitelisting | Access is not desired except for specific issuer values | clientSourcePart=CLAIMS, clientFieldname=iss, list with exact match map | Requests with incompatible issuer are blocked with 403 |
| Audience Segmentation | Microservices expect different audience | Fill acceptedAudienceList environment-based | Requests containing wrong audience receive customized error |
| User Header Injection | Downstream services require identity header | addUserToHeader=true, userHeaderName=X-Authenticated-UserId | Identity information is securely transmitted in header |
| Authorization Integration | Role-based access control is required | enableAuthorization=true, configure method access | Request is stopped by policy if role match is not provided |
| Policy Group Synchronization (optional) | Same rules will be used in multiple API Proxies | Create global policy, add to Policy Group | Policy is updated in all API Proxies with single change |
Configuring Policy Parameters
In 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 allows the policy to be customized according to organization-specific requirements while being centrally manageable.Creating a New JOSE Verification Policy
Configuration Steps
| Step | Description / Operation |
|---|---|
| Step 1: Go to Creation Page | - Go to Development → Global Settings → Global Policies → JOSE Verification Policy from the left menu. - Click the [+ Create] button at the top right. |
| Step 2: Enter Basic Information | Policy Status: Shows Active/Passive status. New policies are active by default. Name (Required): Example: Production_JOSEValidation- Enter a unique name, does not start with space. - System automatically checks. Green checkmark: available. Red X: existing name. Description: Example: “Performs JWT signature and encryption verification.” - Max. 1000 characters. - Explain the purpose of the policy. |
| Step 3: JOSE Source and User Information Configuration | - Select token source from JOSE Target field (body, Authorization header, or variable). - If using variable, select or create relevant variable. - Determine field where issuer information will be read with Client Source Part, assign clientFieldname or variable if needed. |
| Step 4: Define Claim and Audience Rules | - Fill Accepted Audience, Required Claim, Prohibited Claim lists. - Enter key-type-value matches for Exact Match Claim. - Activate Validate Expiration Time, Validate ACL for Issuer, and checkClientIpAddress settings as needed. |
| Step 5: Cryptographic Key and Decode Settings | - If signature verification is needed, open Validate Sign option and select or create necessary JWK. - Configure Decrypt setting and relevant JWK for encrypted contents. - Define claims to be decoded and target field with Strip and Decode. |
| Step 6: Define Condition (Optional) | - Go to 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, policy is always active |
| Step 7: Customize Error Message (Optional) | - Go to 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: Save | - Click the [Save] button at the top right. Checklist: Unique name. Required fields filled. At least one cryptographic check (signature or encryption) active. Result: - Policy is added to the list. - Can be connected to APIs. - If global policy, automatically applied. |
Deleting the Policy
For deletion steps of this policy and operations to be applied when in use, you can refer to the Remove Policy from Flow section on the Policy Management page.Exporting/Importing the Policy
For export (Export) and import (Import) steps of this policy, you can refer to the Export/Import page.Connecting the Policy to API
For the process of how this policy will be connected to APIs, you can refer to the Connect Policy to API section on the Policy Management page.Advanced Features
| Feature | Description and Steps |
|---|---|
| Dynamic JWK Integration | - Select signature or encryption JWK from Secret Manager or list. - Users with appropriate role can generate new JWK from the same screen. - Saved JWK changes are automatically matched with policy. |
| Issuer ACL and IP Verification | - Activate validateACLforIssuer option.- Update issuer-based ACL rules through security service. - Open checkClientIpAddress setting if needed to verify incoming request’s IP. |
| Claim Decode & Rewrite | - Determine stripAndDecode value as ALL or PARTIAL.- Enter list of claims to be decoded ( jwtClaimsToDecode).- Direct output to body, header, or variable and use in other policies. |
Best Practices
Things to Do and Best Practices
| Category | Description / Recommendations |
|---|---|
| Audience Management | Bad: Leaving Accepted audience empty. Good: Defining separate audience value for each microservice. Best: Managing environment-based audience lists (Development/Test/Production) with separate policies. |
| Signature Verification | Bad: Running with validateSign closed.Good: Using issuer JWKS endpoint with validateByIssuer.Best: Enforcing centralized JWK vault in scenarios without issuer. |
| Encryption Management | Bad: Leaving decrypt closed in encrypted tokens.Good: Enabling issuer-based resolution. Best: Defining separate encryption key for each issuer and performing periodic key rotation. |
| Claim Policies | Bad: Leaving claim lists undefined. Good: Determining required and prohibited claim lists. Best: Performing value-type verification with exact match map. |
| Header Integration | Bad: Not transmitting user identity to downstream services. Good: Adding identity header with addUserToHeader.Best: Matching role headers with security logs and auditing. |
Security Best Practices
| Security Area | Description / Warnings |
|---|---|
| Key Management | Store JWK files in Secret Manager; manage access with role-based access. |
| Issuer Trust | Regularly update issuer whitelist; immediately remove suspicious issuers. |
| Token Lifetime | validateExpirationTime should always be open; restrict long-term tokens. |
| Header Hardening | Transmit added identity/role headers only over HTTPS; ensure masking in logs. |
| Error Messages | Do not share internal details in error messages; use generic message + error code combination. |
Things to Avoid
| Category | Description / Warnings |
|---|---|
| Static Embedded JWK | Why to avoid: Keys embedded in code are vulnerable to leakage. Alternative: Select JWK through Secret Manager. |
| Ambiguous Claim Rules | Why to avoid: Accepting all claims creates security vulnerability. Alternative: Define required and prohibited lists. |
| Undecoded Encrypted Data | Why to avoid: Encrypted data passes without verification. Alternative: Keep decrypt setting mandatory and bind appropriate JWK. |
| Unmonitored Header Additions | Why to avoid: Unaudited headers can be abused. Alternative: Log header usage and apply access control. |
Performance Tips
| Criterion | Recommendation / Impact |
|---|---|
| JWK Cache | Recommendation: Share frequently used JWKs with Secret Manager cache. Impact: Signature verification time decreases. |
| Claim Rule Count | Recommendation: Clean unnecessary claim checks. Impact: Policy execution time shortens. |
| Decode Options | Recommendation: Decode only needed claims. Impact: Memory and CPU consumption decreases. |
| Global vs Local Usage | Recommendation: Prefer global policy in APIs sharing same rules. Impact: Management and deploy times shorten. |
| Condition Simplification | Recommendation: Remove unnecessary conditions in Query Builder. Impact: Condition evaluation time per request decreases. |
Frequently Asked Questions (FAQ)
| Category | Question | Answer |
|---|---|---|
| General | What token types does the policy verify? | Supports JOSE standards (JWS/JWE); performs verification according to JSON Web Signature/Encryption rules. |
| General | Can the policy be shared for multiple API Proxies? | Yes, if defined globally, it is shared with multiple API Proxies through Policy Group. |
| Technical | How is it configured if issuer provides its own JWKS endpoint? | Enable validateByIssuer option to allow gateway to get keys from issuer JWKS. |
| Technical | How is encrypted JWE content resolved? | Open decrypt option, select appropriate encryption JWK if not trusted; decrypted payload is written to specified target. |
| Usage | Is it safe to add user identity to header? | Transmit over HTTPS, mask header name, and allow only authorized services to read it. |
| Usage | How can I separate claim rules by environment? | Create separate policy copy for each environment or define condition according to environment header in Condition tab. |