OpenIddict Security & Flow Setup

Token Lifetimes Configuration

Token lifetimes define how long different types of tokens remain valid before expiring. Proper configuration balances security with user experience.

Token Types and Their Purpose:

UserCodesLifetime: Device flow user codes duration

AuthorizationCodesLifetime: Authorization code validity period

AccessTokensLifetime: API access token duration

IdentityTokensLifetime: OpenID Connect ID token duration

DeviceCodesLifetime: Device authorization flow codes

RefreshTokensLifetime: Refresh token validity period

Recommended Timeframes:

• Authorization Codes: 1-5 minutes (short-lived for security)
• Access Tokens: 1-24 hours (balance security vs API calls)
• Identity Tokens: 30 minutes - 1 hour (UI session duration)
• Refresh Tokens: Days to weeks (long-term access renewal)

Token Configuration

Token configuration settings control how tokens are handled, validated, and referenced within the OpenIddict server. These settings affect token behavior and client token management strategies.

Key Token Settings:

UseReferenceRefreshTokens: When enabled, refresh tokens are stored as references in the database rather than being self-contained. Provides better revocation control and security.

UseReferenceAccessTokens: Similar to refresh tokens, access tokens are stored as database references. Allows immediate token revocation but increases database load.

Reference vs Self-Contained Tokens:

Reference Tokens Benefits:

• Immediate revocation capability
• Smaller token size
• Better audit trail
• Enhanced security control

Self-Contained Tokens Benefits:

• No database lookup required
• Better performance
• Stateless validation
• Distributed system friendly

Requirements

Requirements settings enforce additional security measures and compliance standards. These settings help ensure that clients and requests meet specific security criteria before processing.

Security Requirements:

RequireProofKeyForCodeExchange: Enforces PKCE (Proof Key for Code Exchange) for public clients. Critical security measure for mobile and SPA applications to prevent authorization code interception attacks.

RequirePushedAuthorizationRequests: Requires clients to push authorization request parameters to a dedicated endpoint before initiating the authorization flow. Enhances security by keeping sensitive parameters server-side.

Implementation Notes:

• PKCE should be required for all public clients (mobile apps, SPAs)
• Pushed Authorization Requests are part of the latest OAuth security best practices
• These requirements may break compatibility with older client implementations
• Test thoroughly with your client applications before enabling in production

Flow Configuration

OAuth 2.0 and OpenID Connect flows define how clients obtain tokens. Each flow is designed for specific application types and security requirements. This is a critical configuration section that determines which authentication methods your server supports.

Core Flow Types:

Authorization Code Flow

Most secure flow for web applications. Client receives authorization code, exchanges it for tokens. Recommended for server-side web apps.

Hybrid Flow

Combination of authorization code and implicit flows. Provides both front-channel and back-channel tokens. Suitable for applications needing immediate token access.

Client Credentials Flow

Machine-to-machine authentication. No user interaction required. Essential for API-to-API communication.

Device Authorization Flow

For devices with limited input capabilities (smart TVs, IoT devices). User authenticates on a separate device.

Additional Flow Options:

Password Flow: Direct username/password exchange (use with caution)

Refresh Token Flow: Enables token renewal without re-authentication

Implicit Flow: Direct token return (deprecated for security reasons)

Anonymous Clients: Allow clients without authentication

Security Considerations:

• Disable flows not used by your applications
• Implicit flow is deprecated - use Authorization Code with PKCE instead
• Password flow should only be used for trusted first-party applications
• Always require HTTPS in production environments

ASP.NET Core Configuration

ASP.NET Core specific configuration settings that control how OpenIddict integrates with the ASP.NET Core pipeline and handles various framework-specific features.

Core Integration Settings:

EnableAuthorizationEndpointPassthrough: Allows the authorization endpoint to be handled by custom ASP.NET Core middleware or controllers instead of being fully processed by OpenIddict. Useful for custom authorization UI or logic.

EnableUserInfoEndpoint: Enables the UserInfo endpoint that allows clients to retrieve additional user information using an access token. Standard OpenID Connect endpoint.

EnableUserInfoEndpointPassthrough: Similar to authorization endpoint, allows custom handling of UserInfo requests through ASP.NET Core pipeline.

EnableEndUserVerificationEndpointPassthrough: For device authorization flow, allows custom handling of the user verification process through ASP.NET Core controllers.

EnableTokenEndpointPassthrough: Enables custom token endpoint handling for specialized token issuance logic or additional validation.

EnableEndSessionEndpointPassthrough: Allows custom logout/end session handling through ASP.NET Core pipeline for specialized logout flows.

Additional Features:

EnableStatusCodePagesIntegration: Integrates with ASP.NET Core status code pages for better error handling and user experience.

IdentitySuite Library Integration

Important: When using the IdentitySuite library, all passthrough settings should remain enabled as the library provides custom endpoint implementations that enhance OpenIddict's default functionality. These custom endpoints include improved UI, additional validation logic, seamless integration with IdentitySuite's user management features, and full compliance with OpenID Connect certification requirements.

Only disable passthrough settings if you want to revert to OpenIddict's default endpoint behavior, which will bypass IdentitySuite's custom implementations and may result in reduced functionality.

When to Use Passthrough:

• Custom authorization UI that doesn't fit OpenIddict's default handling
• Additional business logic validation before token issuance
• Integration with existing ASP.NET Core authentication systems
• Custom claims transformation or user information enrichment
• Specialized logout procedures or session management

Validation & Security Configuration

Security and validation settings provide additional layers of protection and control over token validation, data protection, and endpoint security. These settings help ensure compliance with OAuth 2.0 and OpenID Connect specifications.

Validation Settings:

EnableAuthorizationEntryValidation: Validates authorization entries against stored data. Helps prevent token replay attacks and ensures authorization integrity.

EnableTokenEntryValidation: Validates token entries in the database. Provides additional security by checking token state and preventing misuse.

Security Features:

EnableUseDataProtection: Encrypts sensitive data using ASP.NET Core Data Protection. Protects tokens and authorization codes at rest.

EnableAccessTokenEncryption: Encrypts access tokens to prevent information disclosure. Recommended for sensitive environments.

Endpoint Security:

EnableAuthorizationEndpointPassthrough: Allows custom authorization handling

EnableUserInfoEndpoint: Provides user information endpoint

EnableTokenEndpointPassthrough: Custom token endpoint processing

EnableUserInfoEndpointPassthrough: Custom UserInfo processing

EnableEndUserVerificationEndpointPassthrough: Device flow verification

EnableEndSessionEndpointPassthrough: Custom logout handling

Best Practices:

• Enable data protection in production environments
• Use token entry validation for enhanced security
• Enable endpoint passthrough only when custom logic is required
• Regularly review and audit enabled security features
• Consider token encryption for highly sensitive applications