Overview
What is its Purpose?
- Standardize centralized JWT generation: Gathers reliable JWT creation flow for different client types on Apinizer.
- Manage authentication sources: Makes Secret Manager, LDAP, Database, or API-based authentication services selectable.
- Facilitate authorization integration: Coordinates role and method-based authorization on the same policy as JWT generation.
- Provide operational control: Provides audit and traceability by centrally controlling token durations, refresh rights, and header transfers.
Working Principle
- Request Arrival: For each HTTP/HTTPS request arriving at the API Gateway, the source IP address of the request is detected.
- Policy Check: If the JWT Authentication 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?
- JWT Generation and Validation Process: Authentication source is triggered according to selected grant type, signing algorithm is applied, token lifetime and refresh rights are calculated.
- Decision Making:
- Match Found: Token is created or validated, redirected to target service with user/role headers added if necessary.
- No Match: Request is rejected with default or customized error message; refresh token generation/cancellation is not performed.
- Error Handling: Returns customizable HTTP status code and error message for requests that do not comply with the policy rule.
Features and Capabilities
Basic Features
- Grant Type Management: Quick switching between Client Credentials and Password grant types, automatic checking of required authentication components for each type.
- Identity Source Selection: Integrates Secret Manager, LDAP, Database, or external API sources into JWT generation process.
- Token Lifecycle Control: Detailed configuration and default value assignments for token lifetime, refresh right count, and durations.
- 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.
- Conditional 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
- JWT Signature Algorithms: Provides signing suitable for target system requirements with RS256, RS384, RS512 options.
- Header Injection: Carries user identity and role information to target with desired header names; works integrated with role-based authorization.
- Refresh Token Policies: Establishes security/comfort balance through refresh token generation, usage limit, and durations.
- 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 | Situation | Solution (Policy Application) | Expected Behavior / Result |
|---|---|---|---|
| Mobile Client JWT Distribution | Mobile apps will connect with separate client identities | Grant Type: CLIENT_CREDENTIALS, Secret Manager selected, token duration 30 min | JWT is automatically generated for each mobile client, backend validation works smoothly |
| Authorized User Session | Login with username/password | Grant Type: PASSWORD, LDAP source, token 15 min + refresh 2 times | JWT is generated after LDAP validation, session extends to 45 min with refresh |
| Inter-Microservice Communication | Services calling each other in background | Grant Type: CLIENT_CREDENTIALS, allowUrlParameters closed, header transfer active | Services carry token only through header, URL leakage is prevented |
| Geographically Restricted Access | Requests from specific locations will be accepted | Condition: Geolocation header check, checkClientIpAddress open | Allowed IPs/locations get JWT, others return 403 |
| JWT Refresh Limit | Refresh token count must be limited | RefreshTokenAllowed true, Count=2, duration 24 hours | User must re-login after 2 refreshes |
| Authorization Header Injection | Roles will be carried to target service | Authorization tab active, addRolesToHeader true, custom header name set | Roles are added to specified header, target service applies RBAC |
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 way, the policy can be customized according to organization-specific requirements and managed centrally.Creating New JWT Authentication Policy
Configuration Steps
| Step | Description / Operation |
|---|---|
| Step 1: Going to Creation Page | - Go to Development → Global Settings → Global Policies → JWT Authentication Policy 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_JWTAuth- Enter a unique name, does not start with space. - System automatically checks. Green check: available. Red X: existing name. Description: Example: “Generates JWT through LDAP with Password grant.” - Max. 1000 characters. - Describe the purpose of the policy. |
| Step 3: JWT Authentication Parameters | - Managed From This Policy: Will the policy control credentials management? true is selected in integrations other than Secret Manager.- Grant Type: Select CLIENT_CREDENTIALS or PASSWORD; selection determines available identity sources. - Identity Source: For PASSWORD, make selection from Identity Role Group modal: LDAP/Database/API or Secret Manager. - Check Client IP Address: Validates the IP from which the request came in Secret Manager-based structures. |
| Step 4: Token and Refresh Configuration | - Token Never Expires: Open if unlimited token will be generated, otherwise enter duration and unit. - Refresh Token Allowed: Open if refresh permission will be given, define right count and validity duration. - JWT Signature Algorithm: Select from RS256/RS384/RS512 according to target system requirements. |
| Step 5: Header and Authorization Settings | - Allow URL Parameters: Enables sending token with query parameter; only recommended in trusted scenarios. - Clear Auth: Clears incoming Authorization header; used for resetting old JWT. - Add User/Roles to Header: Sends user and role information to target service with custom header names. - Authorization Configuration: Open advanced options such as role-based embedding, method access, and JWT refresh service. |
| Step 6: Defining 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: Error Message Customization (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: Saving | - Click the [Save] button at the top right. Checklist: Unique name. Required fields filled. At least one identity source selection completed. Result: - Policy is added to the list. - Can be connected to APIs. - If global policy, automatically applied. |
Deleting Policy
For the deletion steps of this policy and operations to be applied while in use, you can refer to the Removing Policy from Flow section on the Policy Management page.Exporting/Importing Policy
For the export and import steps of this policy, you can refer to the Export/Import page.Binding Policy to API
For the process of how this policy will be bound to APIs, you can refer to the Binding Policy to API section on the Policy Management page.Advanced Features
| Feature | Description and Steps |
|---|---|
| Role-Based Header Injection | - Open addRolesToHeader option from Authorization tab.- Determine header name (e.g., X-Authenticated-UserRoles).- Roles are carried from JWT claims to target service. |
| JWT Regenerator Service Integration | - When API is selected as identity source, open second service modal. - Select and save JWT regenerator service. - Works integrated with refresh token usage in Password grant flow. |
| Method-Based Authorization | - Activate Method Access feature in Authorization tab. - Select API method lists and make role matching. - Requests can be rejected with 403 on method basis. |
Best Practices
Things to Do and Best Practices
| Category | Description / Recommendations |
|---|---|
| Token Lifetime Management | Bad: Using default durations in every environment. Good: Setting 15 min for Production, 60 min for Development. Best: Regularly reviewing token duration according to usage metrics. |
| Refresh Token Strategy | Bad: Defining unlimited refresh rights. Good: Using 3 refresh rights and 24-hour duration. Best: Closing refresh in MFA-mandatory sessions. |
| Header Usage | Bad: Leaving default header names unchanged. Good: Defining header names expected by target service. Best: Using custom header names that have passed security scan. |
| Grant Type Selection | Bad: Using PASSWORD grant in all clients. Good: Preferring CLIENT_CREDENTIALS in machine-to-machine communication. Best: Basing grant selection on per-client analysis with minimum privilege principle. |
| Identity Source Management | Bad: Defining multiple identity sources at the same time. Good: Selecting single source in each grant type. Best: Establishing centralized identity management compatible with Secret Manager versions. |
Security Best Practices
| Security Area | Description / Warnings |
|---|---|
| Token Storage | Store tokens in Secure Cookie instead of browser localStorage; make HttpOnly and Secure flags mandatory. |
| Signature Algorithm | When moving beyond RS256, ensure IM certificate management is ready; plan key rotation. |
| Refresh Token Protection | Limit refresh endpoints with IP and device verification; log failed attempts. |
| Header Hijacking Prevention | Activate ClearAuth feature in legacy token transitions; do not create mixed authentication chains. |
| Audit and Monitoring | Transfer policy logs to SIEM; monitor failed logins by grant type in separate dashboards. |
Things to Avoid
| Category | Description / Warnings |
|---|---|
| Unlimited Token Lifetime | Why to avoid: Provides permanent authority in security breaches. Alternative: Shorten token durations by environment. |
| Carrying Token with URL Parameter | Why to avoid: Leads to token leakage in logs. Alternative: Use header or Authorization Bearer. |
| Shared Identity Source | Why to avoid: Production and test identities may mix. Alternative: Use separate Secret Manager domain for each environment. |
| Unauthorized Refresh Service | Why to avoid: Refresh endpoint can be compromised. Alternative: Make JWT Regenerator service accessible only from secure network segments. |
Performance Tips
| Criterion | Recommendation / Impact |
|---|---|
| Token Calculation Time | Recommendation: Prefer RS256 and do not unnecessarily enlarge key size. Impact: JWT generation stays at milliseconds level. |
| Refresh Calls | Recommendation: Limit refresh count, reduce unnecessary round-trip. Impact: Gateway throughput increases. |
| Identity Source Response Time | Recommendation: Support LDAP/API sources with Cache. Impact: High TPS is managed without triggering throttling. |
| Header Size | Recommendation: Keep role lists minimal, do not transfer unnecessary claims. Impact: Header load going to upstream services decreases. |
| Condition Evaluation | Recommendation: Optimize Query Builder rules; do not use unnecessary regex. Impact: Policy evaluation time decreases. |
Frequently Asked Questions (FAQ)
| Category | Question | Answer |
|---|---|---|
| General | Can I save a policy using Password grant without identity source? | No. When PASSWORD is selected, an Identity Role Group or Secret Manager connection is mandatory; otherwise policy gives Validation error. |
| General | When is Token Never Expires option used? | Only recommended in machine-to-machine communication and situations where security is provided by other layers; risky in user-based access. |
| Technical | Is JWT Regenerator Service API mandatory? | Only required when API is selected as identity source and in refresh token scenario; automatically stays passive in other sources. |
| Technical | How is the role list added to header determined? | Automatically written when addRolesToHeader is active, according to role/claim matches selected in Authorization Configuration field. |
| Usage | What should I do to convert global policy to local copy? | Use [Localize] button from detail page; policy is copied to a new local version and becomes editable. |
| Usage | How do I proceed if policy name conflicts? | System warns with name-exist check; change the name or give unique name by localizing global policy. |