# nginxinc/nginx-openid-connect architecture

> Architecture diagram of the GitHub repository nginxinc/nginx-openid-connect, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-04-09). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/nginxinc/nginx-openid-connect
- Repository: https://github.com/nginxinc/nginx-openid-connect

## Overview

##### 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.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% External Client
    Browser["User/Browser"]:::client

    %% NGINX Plus OIDC Handling Subgraph
    subgraph "NGINX Plus OIDC Handling"
        Ngx["NGINX Plus (OIDC)"]:::nginx
        FC["frontend.conf"]:::config
        SC["openid_connect.server_conf"]:::config
        JS["openid_connect.js"]:::script
        Ngx --> FC
        Ngx --> SC
        Ngx --> JS
    end

    %% Identity Provider
    IdP["Identity Provider (IdP)"]:::external

    %% Key-Value Store Subgraph
    subgraph "NGINX Key-Value Store"
        KV["Token Store"]:::store
        KVConf["openid_connect_configuration.conf"]:::config
        KV --> KVConf
    end

    %% Backend Application
    Backend["Backend Application"]:::backend

    %% Configuration and Setup Script
    Setup["Configuration and Setup Script"]:::script

    %% Flow of interactions
    Browser -->|"request"| Ngx
    Ngx -->|"redirect to login"| IdP
    IdP -->|"authcode redirect"| Ngx
    Ngx -->|"token exchange"| IdP
    Ngx -->|"store tokens"| KV
    Ngx -->|"proxy request"| Backend
    Setup -->|"configure"| Ngx

    %% Click Events
    click FC "https://github.com/nginxinc/nginx-openid-connect/blob/main/frontend.conf"
    click SC "https://github.com/nginxinc/nginx-openid-connect/blob/main/openid_connect.server_conf"
    click JS "https://github.com/nginxinc/nginx-openid-connect/blob/main/openid_connect.js"
    click KVConf "https://github.com/nginxinc/nginx-openid-connect/blob/main/openid_connect_configuration.conf"
    click Setup "https://github.com/nginxinc/nginx-openid-connect/blob/main/configure.sh"

    %% Styles
    classDef client fill:#f9e79f,stroke:#b9770e,stroke-width:2px;
    classDef nginx fill:#aed6f1,stroke:#2471a3,stroke-width:2px;
    classDef external fill:#f5b7b1,stroke:#c0392b,stroke-width:2px;
    classDef backend fill:#abebc6,stroke:#27ae60,stroke-width:2px;
    classDef store fill:#f9c5d1,stroke:#c0392b,stroke-width:2px;
    classDef config fill:#d5f5e3,stroke:#1e8449,stroke-width:2px;
    classDef script fill:#fcf3cf,stroke:#f1c40f,stroke-width:2px;
```
