Overview
What is its Purpose?
- Standardize end-user authentication by routing API Proxy traffic to external OIDC providers.
- Lighten authentication load of microservices and centralize security with ID token and access token verification.
- Sustain long-term user sessions securely thanks to session, cookie, and cache management.
- Apply fine-grained authorization rules at API layer with role mapping and header injections.
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 OIDC 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 being used or is Apinizer default?
- OIDC Authorization Flow: Request is routed according to selected OIDC/OAuth2 flow type; issuer/discovery metadata is fetched, PKCE and nonce/state values are generated, token is validated.
- Decision Making:
- Match Found: User information is extracted from verified token, header/cookie is updated, optional authorization service is triggered, and request is allowed.
- No Match: Authorization fails, defined error message or redirect rule is applied.
- 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
- Dynamic OIDC Discovery: Reduces manual configuration need by automatically discovering issuer, JWKS, and other metadata information through well-known endpoint.
- Multiple Flow Support: Manages Authorization Code, Implicit, Hybrid, and pure OAuth2 Authorization Code flows in the same policy; increases security with PKCE support.
- Token Verification Controls: Provides ID/Access token verification, signature algorithm control, user information retrieval, and API-based token verification options.
- 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
- Advanced Session Management: Meets corporate security standards with session cookie name, timeout, state/nonce verification, session encryption, and compression settings.
- Role and Authorization Integration: Provides in-depth access management with role mapping, adding role to header, external authorization service, or Credential Role Service.
- Adaptable Token Carrying: Can accept token via header, cookie, or both; can make bearer format mandatory, can use custom header names.
- 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 |
|---|---|---|---|
| Corporate Portal SSO | Single sign-on is desired | Authorization Code + PKCE, global policy | User is authorized in all API Proxies with single login. |
| Mobile App Security | Token leakage risk exists in mobile clients | PKCE enabled, short token cache duration | Mobile app stores token in secure storage, renews when expired. |
| Legacy API Protection | Old services use Basic Authentication | Token validation + header injection | Authentication is done at gateway, service only reads header. |
| External Business Partner Integration | External systems want cookie-based access | Token is written to cookies, SameSite/secure is set | Business partner browsers carry session without additional config. |
| Multiple OIDC Provider Management | Different tenants use different issuers | Custom condition + discovery URL variable | Each tenant request is routed to its own issuer and verified. |
| High-Security API | Token signature and aud verification mandatory | ValidateJwtSignature + ExpectedAudience list | Tokens containing wrong issuer/audience are rejected with 403. |
| Developer Sandbox (optional) | Light verification needed in test environment | Condition with /sandbox/* path selection, debug logging open | Only sandbox calls pass weak verification, live traffic is not affected. |
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 OIDC Authentication Policy
Configuration Steps
| Step | Description / Operation |
|---|---|
| Step 1: Go to Creation Page | - Go to Development → Global Settings → Global Policies → OIDC Authentication 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_OIDCAuth- Enter a unique name, does not start with space. - System automatically checks. Green checkmark: available. Red X: existing name. Description: Example: “OIDC SSO for corporate users” - Max. 1000 characters. - Explain the purpose of the policy. |
| Step 3: OIDC Provider and Endpoint Configuration | - Define Issuer or Discovery URL. - If Discovery is disabled, manually enter Authorization, Token, UserInfo, JWKS, and Introspection endpoint addresses. - Fill Client ID/Secret, Redirect URI, Realm, and scopes fields. - Evaluate and mark PKCE and mandatory scope needs. |
| Step 4: Flow, Token, and Session Parameters | - Determine routing by selecting Flow Type (Authorization Code, Implicit, Hybrid, OAuth2). - Configure token verification, signature algorithm, audience/issuer controls. - Enter token acceptance path (header/cookie), bearer usage status, and cache timeout values. - Open session cookie name, timeout, encryption/compression options. |
| Step 5: Advanced Header and Authorization Settings | - Add required key/value pairs to Custom header and backend header tables. - Activate toggles to write user/role information to header, determine header names. - Make role mappings with Identity Role Group Service, connect additional services through Authorization Configuration component if 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 OIDC provider configuration exists 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 Metadata Discovery | - Automatically fetches issuer, JWKS, endpoint information when Discovery URL is entered. - Performance adjustment is made with metadata cache timeout. - Policy returns error message if discovery fails. |
| Secure Session Encryption | - Enter 32/16 byte values in SessionEncryptionKey/IV fields. - Encryption and compression can be activated separately. - TLS must be made mandatory for security requirements. |
| Role Mapping and Header Injection | - Claim path and target role matching is done. - Roles can be added to header, header names can be customized. - Role selection is done with Identity Role Group Service. |
Best Practices
Things to Do and Best Practices
| Category | Description / Recommendations |
|---|---|
| OIDC Provider Management | Bad: Using single issuer for all environments. Good: Defining different issuers for test and live. Best: Making environment-based issuer selection with Condition. |
| Token Security | Bad: Closing signature verification. Good: Performing JWT signature verification. Best: Caching JWKS keys and refreshing periodically. |
| Session Durations | Bad: Leaving durations at default. Good: Determining timeout according to user profile. Best: Implementing Session absolute timeout + refresh token strategy. |
| Role Management | Bad: Using single claim for roles. Good: Extracting role with claim path. Best: Making centralized role mapping with Identity Role Group Service. |
| Error Management | Bad: Transmitting general error message. Good: Specifying OIDC-specific error message. Best: Providing different content that is user-friendly and log-friendly in Error Message Customization. |
Security Best Practices
| Security Area | Description / Warnings |
|---|---|
| TLS Mandatory | All endpoint addresses must be HTTPS; allowInsecureConnections=true is recommended only for temporary use. |
| PKCE Usage | enablePKCE=true should be configured for mobile and SPAs, code verifier should not be logged. |
| Nonce/State Protection | Nonce and state verification should not be disabled; mandatory against replay attacks. |
| Session Encryption | SessionEncryptionKey/IV values should be fed from environment secret variables, should not be embedded in code. |
| Cookie Security | Secure, HttpOnly, and SameSite policies should be enabled; token cookies should be sent with minimum permissions. |
Things to Avoid
| Category | Description / Warnings |
|---|---|
| Default Key Usage | Why to avoid: Default session key values in code are predictable. Alternative: Generate unique keys through secret management system for each environment. |
| Wide Scope Definitions | Why to avoid: Excessive scope causes privilege escalation. Alternative: Add only necessary scopes with least privilege principle. |
| Long Cache Durations | Why to avoid: If JWKS/token cache is kept long, compliance with key rotation weakens. Alternative: Select cache duration between 15-60 minutes and establish refresh mechanism. |
| Keeping Debug Logs Open in Live | Why to avoid: Sensitive token information may fall into logs. Alternative: Open debug logging only briefly during troubleshooting. |
Performance Tips
| Criterion | Recommendation / Impact |
|---|---|
| Metadata Cache | Recommendation: Keep providerMetadataCacheTimeoutSeconds value between 900-1800 seconds. Impact: Discovery endpoint calls decrease, latency drops. |
| Token Cache Timeout | Recommendation: Adjust tokenCacheTimeoutSeconds according to OIDC access token lifetime. Impact: Unnecessary re-verifications are prevented, back-end load decreases. |
| JWKS Cache | Recommendation: Do not exceed 3600 seconds upper limit for jwkCacheTimeoutSeconds. Impact: Acceptance of incorrect signatures during key rotation is prevented. |
| Ignore Patterns | Recommendation: Add static content paths to ignoreRequestPatterns. Impact: Static files are freed from unnecessary redirection, response time increases. |
| Backend Header Management | Recommendation: Remove unnecessary backendRequestHeaders entries. Impact: Request size and processing time going to backend decreases. |
Frequently Asked Questions (FAQ)
| Category | Question | Answer |
|---|---|---|
| General | What is OIDC authentication? | OpenID Connect (OIDC) is an authentication protocol built on OAuth 2.0. Verifies user identity using ID token and access token. |
| General | Which flow types are supported? | Authorization Code, Implicit, Hybrid, and pure OAuth2 Authorization Code flow types are supported. |
| Technical | How is token verified? | Gateway receives token, verifies JWT signature with public key obtained from JWKS endpoint, performs audience and issuer check. |
| Technical | What is PKCE? | Proof Key for Code Exchange (PKCE) is a security mechanism providing protection against authorization code interception attacks. |
| Usage | How are different OIDC providers used for different tenants? | Tenant-based issuer selection can be done with Condition or discovery URL variable can be used. |
| Usage | How can I change default error message? | You can edit status code, error code, and message fields from Error Message Customization tab. |
| General | Can OIDC policy work together with Basic Authentication policy? | Yes, but Basic Authentication is recommended only as fallback; you can determine which policy will work conditionally. |
| General | Does global copy get affected when I convert policy to local? | No, Localize operation creates a new local policy; global policy remains unchanged. |
| Technical | Which fields should I fill if I don’t use Discovery URL? | You need to manually enter Authorization, Token, UserInfo, JWKS, and Introspection endpoint addresses. |
| Technical | Which log messages should I look for when token verification fails? | You can examine error details of validateAccessTokenWithApi and validateJwtSignature steps by opening Policy debug logs. |
| Usage | How do I share same policy for multiple API Proxies? | You can create policy globally and assign to relevant API Proxies or use Policy Group. |
| Usage | Is PKCE mandatory for mobile applications? | Recommended for strong security; activate enablePKCE=true setting to prevent code interception attacks. |