Overview
What is its Purpose?
- Simplifies consumer integrations by repackaging API Proxy response or request as JWT in JOSE standards-compliant format.
- Secures claim data carried between application services with signature and encryption layers.
- Ensures centralized and auditable key management by working integrated with JWK vault.
- Dynamically triggered in specific endpoint, header, or environment combinations with condition engine support.
- Manages organization-specific token enrichments without code changes through additional claim map and data manipulation targets.
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 Application 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?
- Token Generation and Security Layer: After target field is determined, claim set is collected, additional claim map is added, signing and optional encryption is applied according to JWK selection.
- Decision Making:
- Match Found: Generated JWT is written to specified target (body, Authorization header, or variable) and traffic continues.
- No Match: Policy remains disabled, request is transmitted with original content.
- 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 generation output can be stored in body, Authorization header, or selected variable; facilitates response manipulations.
- Ready Claim Keys: Core claim fields like Issuer, Subject, Audience, Expiration are managed with key/lock combinations.
- Additional Claim Map: Text, list, or numeric claims can be added and edited from interface with type-controlled MapValue support.
- 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 Management Integration: JWK search, selection, update, and new key generation through Secret Manager is done with single click.
- Dual-Layer Security: Token integrity and confidentiality are simultaneously ensured by applying signature and encryption combination in the same request.
- Data Manipulation Synchronization: Data sharing between chain policies is done with encoded claim target and variable assignment after decode.
- 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 |
|---|---|---|---|
| Converting Microservice Response to JWT | Service returns plain text JSON, consumer expects JWT | joseTarget=BODY, ready claims active, signature open | Response returns in JWT format, consumer does not do additional work |
| Carrying JWT via Header | Mobile client wants signed token in Authorization header | joseTarget=AUTHORIZATION_HEADER, addTypeToHeader=true | Token is added as Authorization: JWT <token> |
| Multiple Audience Management | Same API transmits token to different target systems | addAudience=true, multiple values added to audience list | Token contains multiple values in aud claim |
| Signing with Internal System Key | Token signed by issuer side is preferred | sign=true, signByIssuer=true is selected | Gateway does not require signature key, issuer signature is preserved |
| Dual-Layer Security | External integration requires signature+encryption combination | sign=true, encrypt=true, appropriate JWKs selected | Token is first signed then encrypted with selected method |
| Data Manipulation Chain | Next policy needs decoded claims | encodedClaimsTargetForDataManipulation=BODY, decoded variable assigned | Decoded claims are stored in defined variable |
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 Application Policy
Configuration Steps
| Step | Description / Operation |
|---|---|
| Step 1: Go to Creation Page | - Go to Development → Global Settings → Global Policies → JOSE Application 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_JOSE- Enter a unique name, does not start with space. - System automatically checks. Green checkmark: available. Red X: existing name. Description: Example: “Converts output body to signed JWT” - Max. 1000 characters. - Explain the purpose of the policy. |
| Step 3: JOSE Target and Claim Settings | - Select body, Authorization header, or variable from JOSE Target field.- If you will use variable, assign a project variable from Variable selector. - In Claim panel, open addIssuer, addSubject, addAudience, addExpirationTime options as needed and fill required fields.- Enrich payload by adding type-based claims from Additional Claim Map table. |
| Step 4: Signature Configuration (If Any) | - Open token signature by activating Sign key.- Use Sign by Issuer option if signature will be provided by issuer.- If Gateway will sign, select jwkIdForValidationAndSign field from Secret Manager list or create new key. |
| Step 5: Encryption and Data Manipulation (If Any) | - Activate Encrypt key and select Encryption Method if confidentiality is needed.- Open Encrypt by Issuer option if encryption will be done by issuer side, otherwise select JWK.- Determine target where token will be stored from Encoded Claims Target for Data Manipulation field, select relevant variable if variable is needed. |
| 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 defined JOSE target and necessary JWK selections exist 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 Claim Mapping | - Press + button from Additional Claim Map table.- Select claim key and appropriate valueType information.- Fill value field and save; change is immediately reflected in list. |
| Dual Role JWK Management | - Open relevant JWK selector from signature or encryption panel. - Select existing key or navigate to Secret Manager with New option. - Policy form is automatically updated when current JWK is saved. |
| Token Chain Manipulation | - Select target where token will be written from Encoded Claims Target field.- Define target variable if you will transfer decoded data to another policy. - Complete data flow by using same variable as source in relevant second policy. |
Best Practices
Things to Do and Best Practices
| Category | Description / Recommendations |
|---|---|
| Claim Design | Bad: Adding all unnecessary fields as claims. Good: Defining only functional claims. Best: Maintaining minimal but sufficient set with regular claim audits. |
| JWK Management | Bad: Continuing to use expired keys. Good: Performing JWK rotation manually at intervals. Best: Setting up automatic rotation schedule through Secret Manager. |
| Signature and Encryption Combination | Bad: Unnecessarily adding both signature and encryption to same token. Good: Being satisfied with only one according to security requirements. Best: Ensuring full security by applying signature first then encryption on sensitive data. |
| Data Manipulation | Bad: Writing decoded data to variables with empty names. Good: Using meaningful variable names. Best: Documenting data flow between policies and determining standard names. |
| Error Message Strategy | Bad: Leaving default error message in all environments. Good: Preparing environment-based custom messages. Best: Including reference codes in error messages for traceability. |
Security Best Practices
| Security Area | Description / Warnings |
|---|---|
| Key Storage | Keep JWKs only within Secret Manager, perform exports through encrypted channels. |
| Token Lifetime | Keep Expiration values short, establish Sliding or Refresh token mechanisms. |
| Issuer and Audience Accuracy | Determine issuer and audienceList values according to corporate naming standard and update in revisions. |
| Additional Claim Hygiene | Make encryption mandatory if personal data exists in additional claims and apply data minimization. |
| Signature Key Authorities | Limit JWK editing authority to ROLE_API_SECURITY, track audit logs. |
Things to Avoid
| Category | Description / Warnings |
|---|---|
| Inconsistent Claim Structure | Why to avoid: Claims outside schema cause parse errors on consumer side. Alternative: Deploy claim changes in version-controlled manner. |
| Wrong JWK Mapping | Why to avoid: Selecting missing or different algorithm JWK breaks token verification. Alternative: Use filtered JWK list for relevant algorithm. |
| Infinite Token Duration | Why to avoid: Token revocation is not possible in case of security breach. Alternative: Design short-term tokens and revocation list. |
| Target Field Incompatibility | Why to avoid: Token written to header instead of response body may not be consumed. Alternative: Clarify target field according to integration documentation. |
Performance Tips
| Criterion | Recommendation / Impact |
|---|---|
| Token Size | Recommendation: Remove unnecessary claims and keep JSON in minimal format. Impact: Transmission time and bandwidth decrease. |
| Encryption Method | Recommendation: Prefer algorithms with hardware support (e.g., A256GCM). Impact: CPU usage decreases, latency drops. |
| Additional Claim Count | Recommendation: Define only necessary claims in MapValue table. Impact: Token size decreases, verification time shortens. |
| Condition Engine | Recommendation: Avoid unnecessary nested conditions in Query Builder. Impact: Policy evaluation process speeds up. |
| JWK Lookup | Recommendation: Activate Secret Manager options that cache frequently used JWKs. Impact: I/O delays decrease during signing/encryption. |
Frequently Asked Questions (FAQ)
| Category | Question | Answer |
|---|---|---|
| General | When is JOSE Application Policy used? | Used in integrations requiring token generation, claim management, and secure transmission; especially effective in scenarios where consumer expects JWT. |
| General | Is it mandatory to open both signature and encryption simultaneously? | No, only signature or only encryption can be used according to requirements; both together are recommended for sensitive data. |
| Technical | How is JWK selection done? | Secret Manager JWK list is opened; key matching appropriate algorithm and purpose is selected or new key is created. |
| Technical | What happens when variable is selected as target? | Policy writes token to specified project variable; other policies or backend can read this variable. |
| Usage | How are values added to audience list? | Add Audience is activated, value is written to input box and confirmed; each value is listed as chip. |
| Usage | Do I have to customize error message? | Not mandatory; however, customization can be done in Error Message tab if directive information is needed for consumer side. |