How nginxinc/nginx-openid-connect works
Main Components
• Client/Browser: Represents the end user – initiating requests for resources.
• NGINX Plus: Acts as the central component that handles the OpenID Connect flows. It is configured via several files (frontend.conf, openid_connect.server_conf) and executes JavaScript logic (openid_connect.js) for token handling.
• Identity Provider (IdP): The external authorization server that handles authentication and issues tokens. (It is external to the repository but central to the flow.)
• Backend Application: The protected upstream service that the NGINX Plus instance proxies requests to once authentication is complete.
• Token Key-Value Store: Although not a separate process, the configuration details in openid_connect_configuration.conf reflect a key/value store (using keyval_zone) that NGINX Plus uses to persist and verify tokens (ID tokens, access tokens, refresh tokens).
Understand the Relationships and Interactions
• The client’s request for a protected resource is first intercepted by NGINX Plus.
• After successful authentication at the IdP, the browser is redirected back to NGINX Plus with an authorization code.
• NGINX Plus then exchanges this code with the IdP to obtain an ID token (and possibly access/refresh tokens) – with validation performed through the included JavaScript module.
• Tokens are stored in the NGINX Plus key-value store.
• Finally, NGINX Plus proxies the authenticated request to the backend app, attaching the necessary bearer tokens if needed.
Architectural Design Principles
• Separation of Concerns: NGINX Plus is configured in a modular way (with separate configuration files for frontend reverse proxy, server handling the token exchange, and a dedicated JavaScript module).
• Stateful Session Management: Although using tokens, a local persistent key-value store is used for maintaining session state.
• Extensibility: The configuration supports multiple IdPs, PKCE for public clients, varied client authentication methods, and even deployment adjustments (e.g., running in containers or behind a load balancer).
• Security Focus: The emphasis on JWT validation, session cookies, and secure token storage is a core design element.
Technologies/Frameworks Involved
• NGINX Plus (with advanced modules like auth_jwt, keyval_zone, and the API module for monitoring)
• njs (NGINX JavaScript module)
• Shell scripting (configure.sh)
• OpenID Connect protocol and JSON Web Tokens (JWT)
Final Advice to the Principal Software Engineer
• The client initiating a resource request.
• NGINX Plus (with its associated configuration modules and JavaScript for token handling) being responsible for initiating and managing the OpenID Connect flow.
• Interaction with the external Identity Provider for authentication.
• Storage and validation of tokens via a key-value store.
• Proxying authenticated requests to the backend application.