OIDC Authentication

You can integrate with OIDC provider and verify user sessions and control API access

This document explains the detailed usage of a specific policy. If you are using Apinizer policies for the first time or want to learn the general working principles of policies, we recommend reading the What is Policy? page first.

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

1. Request Arrival: For each HTTP/HTTPS request arriving at the API Gateway, the source IP address of the request is identified.
2. 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?
3. 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.
4. 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.
5. 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. 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

The sections below walk through the OIDC (Keycloak, Okta, Azure AD, …) configuration profile in tab order, with screenshots and field tables for that profile. For how OAuth2 (External OAuth2 Provider) differs, finish these OIDC sections first, then read OIDC vs OAuth2 configuration profile — UI differences right after them (including OAuth2 Parameters and Session & HTML screenshots).

Connection tab

Configuration Profile: OIDC (Keycloak, Okta, Azure AD, …) or OAuth2 (External OAuth2 Provider) — determines flow type, visible tabs, and fields; many fields remain editable after selection.

Section	Field	Notes
Provider Configuration	OIDC Issuer URL (required)	e.g. https://accounts.google.com. Use Auto Discover for metadata.
	Discovery URL	If empty, derived from issuer; or set explicitly (e.g. …/.well-known/openid-configuration). Help text: If empty, automatically derived from Issuer URL.
Endpoint Configuration	Authorization Endpoint (required)	Authorization endpoint URL.
	Token Endpoint (required)	Token endpoint URL.
	UserInfo Endpoint	UserInfo URL. OIDC profile only.
	JWKS Endpoint	JWKS URL for signature verification. OIDC profile only.
	Introspection Endpoint	Token introspection URL. OIDC profile only.
	Token Revocation Endpoint	Revocation URL. OIDC profile only.
	oauth2ResourceEndpoint (required)	OAuth2 profile only; replaces the four endpoints above.
Client Information	Client ID (required)	OAuth/OIDC client identifier.
	Client Secret	Client secret (show/hide).
	Redirect URI (required)	OAuth redirect URI.
	Realm	Provider-specific realm when applicable. Hidden in OAuth2 profile.
Flow Configuration	Flow Type (required)	OIDC: choose from list (e.g. Authorization Code Flow). OAuth2: OAUTH2_AUTHORIZATION_CODE is fixed in the backend; OAuth2 Username Extraction Path appears on this profile.
	Authentication Mode	e.g. External OIDC Provider Only. Some builds may show the same label twice; keep values consistent.
	Enable PKCE	Proof Key for Code Exchange (checkbox).
	Scopes	Comma-separated scopes, e.g. openid, profile, email.
Additional Auth Parameters	+ to add rows	Extra authorization request parameters (acr_values, login_hint, prompt, etc.). OIDC profile only; use OAuth2 Parameters tab for OAuth2.

Token & Validation tab

OIDC configuration profile only. The OAuth2 profile uses the OAuth2 Parameters tab instead of this one.

Defines how incoming tokens are validated, forwarded to backends, and cached (JWT checks, UserInfo, header/cookie behavior).

Token Validation

Field	Description
Bearer JWT Authentication	Authenticate using Bearer JWT.
Validate ID Token	Validate the ID token.
Validate Access Token	Validate the access token.
Validate Token with API	Validate the token via API.
Call UserInfo Endpoint	Calls the UserInfo endpoint; additional user information can be forwarded to the backend as a header (see inline help).
Token Cache Timeout (sec)	Token cache TTL (seconds).
JWK Cache Timeout (sec)	JWKS cache TTL (seconds).

Token Accept Settings

Field	Description
Accept Token As	e.g. Header and Cookie — where the token is accepted from.
Add Token to Cookie	Write token to cookie.
Add as Bearer	Use Bearer format.
Add Access Token to Header	Forward access token in a header; when enabled, a header name field may appear.
Add ID Token to Header	Forward ID token in a header; when enabled, a header name field may appear.
Disable UserInfo Header	Do not add UserInfo payload as a header.
UserInfo Header Name	e.g. UserInfo.

JWT Validation Details

Field	Description
Validate Issuer	Validate iss; when enabled, set Expected Issuer if needed.
Validate Audience	Validate aud.
Validate JWT Locally	Local JWT validation.
Validate JWT Signature	Signature verification.

Cache Settings (duplicate block in UI)

Field	Description
Token Cache Timeout (sec)	Token cache duration.
JWK Cache Timeout (sec)	JWK cache duration.

Session & Logout tab

OIDC configuration profile only (full session and logout). The OAuth2 profile uses Session & HTML instead (simplified session + HTML templates).

Session cookie, token cookies, and logout behavior.

Session Settings

Field	Description
Session Cookie Name	Session cookie name (e.g. OIDC_SESSION).
Session Timeout (min)	Session idle timeout (minutes).
Absolute Timeout (sec)	Absolute session lifetime (seconds).
Secure Cookie	Send cookie only over HTTPS.
Enable State Validation	Validate OAuth state.
Enable Nonce Validation	Validate OpenID nonce.

Token Cookie Settings

Field	Description
Renew Access Token on Expiry	Refresh access token when it expires.
Access Token Cookie Name	Cookie name for access token.
Enable ID Token Cookie	Store ID token in cookie.
Enable Refresh Token Cookie	Store refresh token in cookie.

Logout Settings

Field	Description
Logout Path	Logout URL path (e.g. /logout).
Post Logout Redirect URI	Redirect after logout at provider.
Redirect After Logout URI	Redirect after logout in Apinizer.
ID Token Hint in Logout	Send id_token_hint on logout.
Revoke Tokens on Logout	Revoke tokens when logging out.
Token Revocation Endpoint	Revocation endpoint URL.

User Mapping tab

OIDC configuration profile only. There is no User Mapping tab on the OAuth2 profile; use OAuth2 Username Extraction Path on Connection and the OAuth2 Parameters tab.

Maps OIDC claims to user fields, roles, and backend headers.

Claim Paths

Field	Description
Username Claim Path	Claim for username (e.g. sub).
Email Claim Path	Claim for email (e.g. email).
Display Name Claim Path	Claim for display name (e.g. name).

Role Mappings (table)

Column	Description
Claim Path	Claim to match.
Claim Value	Expected value.
Target Role	Role to assign.

Custom Claim Mappings (table: Header Name / Header Value)

Backend Header Settings

Field	Description
Disable UserInfo Header	Do not forward UserInfo as a backend header.
UserInfo Header Name	Header name for UserInfo (e.g. UserInfo).

Custom HTTP Headers (table: Header Name / Header Value) — additional headers sent to the backend.

Security & Other tab

TLS/mTLS to the provider, timeouts, request filtering, error redirects, and debug options.

Secure Connection Settings

Field	Description
Customize SSL/TLS Settings	When off, system defaults (e.g. JVM cacerts) are used; when on, you configure custom certificates, TrustStore, or mTLS.
Skip SSL Verification	Skip server certificate verification (use only for testing).
Server Certificate Verification	Server certificate verification details (collapsible panel, opens with +).
KeyStore (Client Certificate)	Client certificate / mTLS (collapsible panel).
Protocol & Verification Settings	Protocol and verification (collapsible panel).

UI warning: mTLS settings affect all connections to the OIDC provider; incorrect configuration can cause connection errors.

IP and Security Control

Field	Description
Check Client IP	Validate client IP. OIDC configuration profile only.

Timeout Settings

Field	Description
Connection Timeout (sec)	Connect timeout.
Read Timeout (sec)	Read timeout.
Max Clock Skew (sec)	Clock skew tolerance for JWT iat/exp, etc.

Request Filtering

Field	Description
Ignored Methods	HTTP methods skipped by the policy (e.g. OPTIONS). OIDC configuration profile only.
Ignored Patterns	Comma-separated path/file patterns (e.g. static/js, *.css, *.png). OIDC configuration profile only.

Error Handling

Field	Description
Error Redirect URL	Redirect URL on error.
Include Error Details	Include error details in the response.
Error Message Template	Custom error message template.

Debug and Logging

Field	Description
Debug Logging	Verbose logging.
User Agent	User-Agent for OIDC requests (e.g. Apinizer-OIDC-Client/1.0).

Other

Field	Description
Clear Authorization	Remove existing authentication information from the message.
Add User to Header	On success, add username or clientId to a header.
User Header Name (required)	Header name; help text may reference default e.g. X-Authenticated-UserId (UI may show e.g. User).

OIDC vs OAuth2 configuration profile — UI differences

The tables above document the OIDC profile tabs in order. When Configuration Profile is set to OAuth2 (External OAuth2 Provider), Manager shows or hides different tabs and conditional fields on the same policy screen; this section summarizes that behavior.

In Apinizer Manager, the Configuration Profile radio buttons (OIDC / OAuth2) control this.

Summary table

	OIDC (Keycloak, Okta, Azure AD, …)	OAuth2 (External OAuth2 Provider)
flowType in the background	Selected from dropdown: Authorization Code, Implicit, Hybrid (pure OAuth2 Authorization Code is not listed)	Fixed: OAUTH2_AUTHORIZATION_CODE — set in code when the profile changes
Connection — endpoints	UserInfo, JWKS, Introspection, Revocation fields are shown	Those four are hidden; instead the required oauth2ResourceEndpoint field is shown
Realm	Shown	Hidden
Extra authorization parameters	Additional Auth Params panel (OIDC)	No panel here; instead OAuth2 Auth / Token / Resource parameter tables on a separate tab
Flow panel	No Username Extraction Path (OAuth2-specific)	OAuth2 Username Extraction Path is shown
Tab order	Connection → Token & Validation → Session & Logout (full) → User Mapping → Security & Other	Connection → OAuth2 Parameters → Session & HTML → Security & Other

Both profiles typically also include: Conditions, Error Message Customization, API Proxies Using Policy, API Proxy Groups Using Policy (logic is largely independent of profile).

Hidden or different when OAuth2 profile is selected (vs OIDC)

• Token & Validation tab: Bearer JWT, ID/access token checks, UserInfo, JWT issuer/audience/signature, token accept settings, etc.
• Full Session & Logout tab (OIDC): state/nonce, absolute timeout, token cookie names, logout path, revoke, post-logout, etc.
• User Mapping tab: claim paths, role mappings, custom claim mappings.
• On Security & Other, Check Client IP and Ignored Methods / Patterns — OIDC profile only.

Additional / different on OAuth2 profile

The following tabs and screenshots appear only when OAuth2 (External OAuth2 Provider) is selected. Tables use Header Name / Header Value pairs or template editors as appropriate.

OAuth2 Parameters tab

Section	Description
Authorization Parameters	Extra HTTP headers for the authorization request (oauth2AuthParams). Table: Header Name / Header Value; use + to add rows.
Token Parameters	Extra headers for the token exchange request (oauth2TokenParams).
Resource Parameters	Extra headers when calling the resource / user-info request (oauth2ResourceParams).
Backend Request Headers	Extra headers sent to the backend after successful authentication (collapsible section; + to add rows).

Session & HTML tab

Replaces the full OIDC Session & Logout and User Mapping tabs for this profile: simplified session fields and optional HTML Response Pages for login, error, and success.

Session Settings

Field	Description
Session Cookie Name	Session cookie name (e.g. OIDC_SESSION).
Session Timeout (min)	Session lifetime in minutes.
Secure Cookie	Send cookie only over HTTPS.
Renew Access Token on Expiry	Attempt to refresh the access token when it expires.

HTML Response Pages (when enabled)

Field	Description
HTML Response Pages	Enables custom HTML pages (similar to enableHtmlResponsePages).
Application Title	Title shown on pages (may be referenced in templates, e.g. {{APP_TITLE}}).
Success Page Call	Redirect after successful authentication.
Success Page URL	Target URL after success.
Login / Error / Success Page Template	Three sub-tabs for HTML templates for login, error, and success flows.

Common to both profiles

• Connection is largely shared: Issuer, Discovery URL, Authorization Endpoint, Token Endpoint, Client ID, Client Secret, Redirect URI, PKCE, Scopes, Authentication Mode (endpoint and flow fields differ per summary table above).
• Security & Other: mTLS/SSL, connection/read timeout, max clock skew, error redirect, debug, user headers; Conditions and Error Message Customization remain profile-independent in behavior.

If documentation states a single tab order for both profiles, that does not fully match the Manager UI: with OAuth2 selected, OAuth2 Parameters and Session & HTML replace Token & Validation, full Session & Logout, and User Mapping.

Note: UI behavior depends on profile flags such as isOIDCProfile / isOAuth2Profile; fields may change between Apinizer versions.

Configuration Steps

OIDC profile recommended order: Connection → Token & Validation → Session & Logout → User Mapping → Security & Other → optional Conditions, Error Message Customization, API usage tabs.

OAuth2 profile order differs: Connection → OAuth2 Parameters → Session & HTML → Security & Other → same optional tabs. This page first documents OIDC tabs in tables; OAuth2 differences are in the OIDC vs OAuth2 configuration profile — UI differences section immediately above.

The steps below follow the OIDC flow first; if you use OAuth2, fill Connection using the summary table in that section, then use OAuth2 Parameters and Session & HTML instead of Steps 5–6 as written for OIDC.

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: Variable Usage	- In the action button area at the top of the page, you can use the [<> Variable] button to select dynamic values. - Using context/global variable expressions, you can manage policy parameters with variable-based values instead of fixed values. - This reduces manual update effort when values change and provides operational convenience. - For detailed information, review Dynamic Variables.
Step 4: Connection — provider, endpoints, client, flow	- Choose Configuration Profile (OIDC or OAuth2). - Enter OIDC Issuer URL; use Auto Discover or Discovery URL as needed. - OIDC: After discovery or manual entry, verify Authorization, Token, UserInfo, JWKS, Introspection, and Token Revocation; use Realm and Additional Auth Parameters on this profile. - OAuth2: UserInfo / JWKS / Introspection / Revocation are not shown; fill required oauth2ResourceEndpoint; Realm and the Connection Additional Auth Parameters panel are absent (use OAuth2 Parameters tab). Flow is fixed to OAUTH2_AUTHORIZATION_CODE in the backend; set OAuth2 Username Extraction Path when needed. - Client ID, Client Secret, Redirect URI are shared. Redirect URI must exactly match the provider-registered URL. - Set Enable PKCE, Scopes, Authentication Mode, etc.
Step 5: Token & session tabs or OAuth2 tabs → Security & Other	OIDC profile: In order: (1) Token & Validation, (2) Session & Logout, (3) Security & Other — matches tables above. Token validation, UserInfo, cache; session/logout; no skip-SSL in production; on OIDC, Check Client IP, Ignored Methods / Ignored Patterns live here. Do not confuse Error Redirect URL with Step 8 JSON body; enable Debug Logging only briefly. OAuth2 profile: No Token & Validation or full Session & Logout. Use OAuth2 Parameters (oauth2AuthParams, oauth2TokenParams, oauth2ResourceParams, Backend Request Headers) and Session & HTML (simplified session + HTML login/error/success); then Security & Other (shared TLS, timeouts, error redirect, debug, user headers — Check Client IP and ignore fields are not shown on OAuth2).
Step 6: User Mapping (OIDC) or backend headers	OIDC profile: Claim Paths, Role Mappings, Custom Claim Mappings, Backend Header Settings, Custom HTTP Headers — keep consistent with Token & Validation UserInfo/header behavior. OAuth2 profile: Use Backend Request Headers under OAuth2 Parameters and username extraction on Connection instead; there is no classic User Mapping tab.
Step 7: 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 8: Customize Error Message (Optional)	- Go to Error Message Customization tab. - Customize the JSON API response body when access is denied. This differs from Error Redirect URL on Security & Other (browser redirect); if you use both, test the combined behavior. Default: { "statusCode": 403, "message": "[Default error message]" } Custom: { "statusCode": 403, "errorCode": "[CUSTOM_ERROR_CODE]", "message": "[Custom message]" }
Step 9: Save	- Click the [Save] button at the top right. Checklist (summary): - Unique Name and required Connection fields: OIDC Issuer URL; Authorization / Token; Client ID; Redirect URI; OIDC Flow Type, OAuth2 oauth2ResourceEndpoint. - Redirect URI matches the provider registration. - OIDC: Token & Validation / Session & Logout / User Mapping complete as needed; OAuth2: OAuth2 Parameters and Session & HTML complete. - Optional Conditions / Error Message Customization tested. Result: Policy is added to the list; can be connected to APIs; if global, applied automatically.

For descriptions of Conditions and Error Message Customization panels, you can review the Conditions and Error Message Customization sections on the What is Policy? page.

For a complete guide on all layers, priority order and scenario examples of the error message configuration system, see the Error Message Configuration Guide page.

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.
Session Management	- Session data is stored in distributed cache (mandatory). - Session encryption key and IV are automatically generated from policy ID. - Configure with session cookie name, timeout, absolute timeout, and cookie delimiter.
mTLS Configuration	- mTLS can be used when connecting to OIDC provider. - KeyStore/TrustStore-based SSL connection and skip SSL verification option are provided.
Token Cookie Configuration	- Access token cookie name can be customized; ID and refresh token storage in cookies is controlled with checkboxes. - Use Renew Access Token on Expiry to control refresh-on-expiry behavior.
Token Acceptance Path	- Where token is read from (header, cookie, or both) can be determined.
Logout and Token Revocation	- Tokens are revoked via revocation endpoint on logout. - Redirect URL after logout can be defined.
Authentication Mode	- EXTERNAL_ONLY (external OIDC), INTERNAL_ONLY (Bearer only), HYBRID (both). - Both authentications can be enforced in Hybrid mode.
OAuth 2.0 HTML Pages	- Custom login, error, and success pages are shown in OAuth 2.0 flow. - Page templates can be customized. - Post-authentication redirect can be configured.
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 Security	Session data is stored in cache; encryption key is automatically generated from policy ID. TLS must be mandatory.
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: Manual session key values may be predictable. Alternative: Session encryption is automatically generated from policy ID; ensure policy ID is unique.
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 ignore patterns field. Impact: Static files are freed from unnecessary redirection, response time increases.
Backend Header Management	Recommendation: Remove unnecessary backend header 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.
Technical	What does authentication mode (EXTERNAL_ONLY, INTERNAL_ONLY, HYBRID) mean?	EXTERNAL_ONLY: OIDC redirect only. INTERNAL_ONLY: Bearer token only (header/cookie). HYBRID: Both; both can be enforced in Hybrid mode.
Technical	How is token revocation done on logout?	Enable token revocation on logout option and define revocation endpoint. If not set, it is derived from introspection endpoint (/introspect → /revoke).