omniauth_oidc 0.2.7 → 1.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 9e78d766cf25ec6bae84d2af8d007cfafd53cdc1c5f67c448b91f04d80cf8bc9
-  data.tar.gz: 572884ae38c7d8a4c89882b8609348a6bcc5aea0c4f7e7f0303e1a4e9a763136
+  metadata.gz: 235b9ddce05f36feb1cff322acfd22e06969de1ae49673b607fbb6779b85d448
+  data.tar.gz: 4cfec340b6c5cc585091829b3e4b6b8bd3db913773687481a05fc52fc3e27ea0
 SHA512:
-  metadata.gz: d48453b68849c0ec1a34a0d58805efb3a1cecbb4966d40e0ba4098d679330cf5d7f27b401e9a6a2d6d4f4bae4dc36224bb5b0788299358e6a8054b1c35666996
-  data.tar.gz: b7dfad42cf0c15f34d36ce0676e79da70e03d7114695578dc170fe9be2338424b0cc20dbeffe9f503820016bee65f8c5de0c6388d56d78320a48e03a2cad7ad7
+  metadata.gz: ebae17e00270c2aeefe3937993de033f7241d1f98cfbc630e9acd2163fbbe5011808da0189cef14fa20d9f94833b5ef014fbfc99652f6e16448048c25ee7e6fe
+  data.tar.gz: 6d908f0af3cd3e341f3ef3fdfa8c2f6c36fb15f4c1d94a17cb72d1ea1c28eb6f92b368696c32daf11dd89a72a78e76f409c28be3668ba42ab262677bacd9c14d

data/.rubocop.yml

@@ -1,5 +1,6 @@
 AllCops:
   TargetRubyVersion: 2.7
+  NewCops: enable
 
 Style/StringLiterals:
   Enabled: true
@@ -21,7 +22,7 @@ Metrics/MethodLength:
 Metrics/AbcSize:
   Max: 35
 
-Metrics/Metrics/CyclomaticComplexity:
+Metrics/CyclomaticComplexity:
   Max: 10
 
 Metrics/PerceivedComplexity:

data/CHANGELOG.md

@@ -1,5 +1,75 @@
 ## [Released]
 
+## [1.0.0] - 2026-03-02
+
+### BREAKING CHANGES
+- **Dependency Replacement**: Removed `openid_connect`, `openid_config_parser`, `json-jwt`, and `httparty` runtime dependencies. Replaced with custom `Net::HTTP`-based implementation and the standard `jwt` gem. Any code that relied on these gems being transitively available will need to add them directly.
+- **Internal Object Types Changed**: Response objects are now custom classes instead of OpenIDConnect library types:
+  - `OpenIDConnect::Client` replaced by `OmniauthOidc::Client`
+  - `OpenIDConnect::ResponseObject::IdToken` replaced by `OmniauthOidc::ResponseObjects::IdToken`
+  - `OpenIDConnect::ResponseObject::UserInfo` replaced by `OmniauthOidc::ResponseObjects::UserInfo`
+  - `Rack::OAuth2::AccessToken` replaced by `OmniauthOidc::ResponseObjects::AccessToken`
+- **Session Keys Namespaced**: Session keys now include the provider name (e.g. `omniauth.my_provider.state` instead of `omniauth.state`). This enables multiple OIDC providers but breaks code that manually accesses session keys with the old format. Users mid-authentication during upgrade will see state mismatch errors.
+- **Scope Return Type**: `scope` now returns a space-delimited String (e.g. `"openid profile email"`) instead of an Array. Code that called `.each`, `.include?`, or other Array methods on the return value will break.
+- **AuthHash Construction**: Now uses OmniAuth DSL blocks (`info`, `credentials`, `extra`) consistently instead of manually building `env["omniauth.auth"]`. The `info` hash now includes all standard OIDC UserInfo fields (given_name, family_name, gender, picture, phone, website).
+- **Error Classes Restructured**: Error handling uses new specific error classes under `OmniauthOidc::` namespace. `Rack::OAuth2::Client::Error` is no longer caught. `validate_client_algorithm!` now raises `OmniauthOidc::InvalidAlgorithmError` instead of `CallbackError`.
+- **CallbackError Parameter Names**: `CallbackError` now accepts `error_reason:` and `error_uri:` keyword arguments (previously `reason:` and `uri:`). The old keys are still accepted for backward compatibility.
+
+### Added
+- **Custom HTTP Client** (`OmniauthOidc::HttpClient`): Net::HTTP-based client for all HTTP requests, removing external HTTP client dependencies entirely
+  - GET requests follow up to 5 redirects (301, 302, 307, 308), including relative redirects
+  - POST requests reject redirects to prevent credential leakage
+- **Custom OIDC Client** (`OmniauthOidc::Client`): Handles authorization URI construction, token exchange, and userinfo fetching
+- **Response Objects** (`OmniauthOidc::ResponseObjects`): `IdToken`, `UserInfo`, and `AccessToken` classes with method-style access to standard OIDC claims
+- **Configuration Fetcher** (`OmniauthOidc::ConfigFetcher`): Fetches and parses `.well-known/openid-configuration` with retry support
+- **JWK Handler** (`OmniauthOidc::JwkHandler`): JWKS parsing with proper `kid`-based key selection for providers that publish multiple signing keys (e.g. Google, Microsoft Entra ID, Auth0)
+- **JWKS Caching** (`OmniauthOidc::JwksCache`): Thread-safe JWKS cache with configurable TTL (default 1 hour)
+  - Automatic cache invalidation and retry on signature verification failure
+  - Manual cache control via `OmniauthOidc::JwksCache.clear!` and `.invalidate(uri)`
+  - Configurable via `jwks_cache_ttl` option
+- **Logging & Instrumentation** (`OmniauthOidc::Logging`): Logging via Ruby Logger with optional ActiveSupport::Notifications integration
+  - Configurable log levels (default: WARN)
+  - Automatic sanitization of sensitive data (tokens, secrets, code verifiers)
+  - Event instrumentation for config fetch, token exchange, userinfo fetch, JWKS fetch, request phase, and callback phase
+- **Error Hierarchy**: Specific error classes for all failure modes
+  - `TokenVerificationError`, `TokenExpiredError`, `InvalidAlgorithmError`, `InvalidSignatureError`
+  - `InvalidIssuerError`, `InvalidAudienceError`, `InvalidNonceError`
+  - `JwksFetchError`, `KeyNotFoundError`
+  - `ConfigurationError`, `MissingConfigurationError`
+- **Configuration Validation**: Required options (`identifier`, `secret`, `config_endpoint`) are validated on first request with a clear error message listing all missing fields
+- **RBS Type Signatures** (`sig/omniauth_oidc.rbs`): Full type declarations for all public API classes
+- **Comprehensive Test Suite**: Unit tests for HTTP client, JWK handler, JWKS cache, logging, errors, and strategy configuration
+
+### Fixed
+- **JWK kid Selection**: `keyset_for_algorithm` now selects the correct signing key by `kid` from JWKS. Previously, with multiple keys in the JWKS, verification could fail or use the wrong key.
+- **Dead Code Removed**: Removed `decode` method in Verify module that referenced undefined `UrlSafeBase64` constant
+- **Typo**: Fixed `client_singing_alg` to `client_signing_alg` in error messages
+- **Scope Default**: Fixed default scope fallback from `[:open_id]` (typo) to `[:openid]`
+- **AuthHash Consistency**: Consolidated duplicate user info fetching and AuthHash construction into OmniAuth DSL blocks
+- **Removed `resolve_endpoint_from_host`**: Endpoints are now used as full URLs from the discovery document instead of being stripped to relative paths
+
+### Changed
+- **Module Loading**: Replaced `Dir.glob` with explicit `require_relative` for clarity and predictable load order
+- **Dependency Constraints**: Runtime dependencies reduced to `omniauth ~> 2.1` and `jwt ~> 2.7`
+- **CI Updates**: Added Ruby 4.0.1 to test matrix, updated `actions/checkout` to v6, RuboCop runs on Ruby 3.3
+- **RuboCop Config**: Fixed invalid cop name `Metrics/Metrics/CyclomaticComplexity`, added `NewCops: enable`
+
+### Migration Guide from 0.x to 1.0.0
+
+1. **Dependencies**: Remove gems that were only used by this gem, then run `bundle install`:
+   - `httparty`
+   - `openid_connect`
+   - `openid_config_parser`
+   - `json-jwt`
+2. **Session Keys**: If you manually access session keys, update to the new namespaced format: `omniauth.{provider_name}.state`, `omniauth.{provider_name}.nonce`.
+3. **Scope Handling**: If your code treats `scope` as an Array, update it. `scope` now returns a space-delimited String.
+4. **Error Handling**: Update rescue clauses to catch the new error classes if needed. For example:
+   - `Rack::OAuth2::Client::Error` -> `OmniauthOidc::TokenError`
+   - Algorithm mismatches now raise `OmniauthOidc::InvalidAlgorithmError` instead of `CallbackError`
+5. **Response Objects**: If you access `access_token` or `user_info` objects directly, note they are now `OmniauthOidc::ResponseObjects::AccessToken` and `OmniauthOidc::ResponseObjects::UserInfo` respectively.
+6. **Logging** (optional): Configure logging level: `OmniauthOidc::Logging.log_level = Logger::INFO`
+7. **Ruby 4.0+**: Add `gem "ostruct"` to your Gemfile (removed from default gems in Ruby 4.0).
+
 ## [0.2.7] - 2024-10-11
 - Dependencies update
 

data/LICENSE.txt

@@ -1,6 +1,6 @@
 The MIT License (MIT)
 
-Copyright (c) 2024 Suleyman Musayev
+Copyright (c) 2024-present Suleyman Musayev
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

data/README.md

@@ -1,6 +1,8 @@
 # OmniAuth::Oidc
 
-This gem provides an OmniAuth strategy for integrating OpenID Connect (OIDC) authentication into your Ruby on Rails application. It allows seamless login using various OIDC providers.
+OmniAuth strategy for OpenID Connect (OIDC) authentication. Supports multiple OIDC providers, PKCE, JWKS key rotation, and both `code` and `id_token` response types.
+
+Minimal dependencies: only `omniauth` and `jwt` gems required. All HTTP requests use Ruby's built-in `Net::HTTP` — no Faraday, HTTParty, or other external HTTP clients.
 
 Developed with reference to [omniauth-openid-connect](https://github.com/jjbohn/omniauth-openid-connect) and [omniauth_openid_connect](https://github.dev/omniauth/omniauth_openid_connect).
 
@@ -16,14 +18,15 @@ If bundler is not being used to manage dependencies, install the gem by executin
 
     $ gem install omniauth_oidc
 
+**Ruby 4.0+**: Add `gem "ostruct"` to your Gemfile (`ostruct` was removed from default gems in Ruby 4.0).
 
 ## Usage
 
 To use the OmniAuth OIDC strategy, you need to configure your Rails application and set up the necessary environment variables for OIDC client credentials.
 
 ### Configuration
-You have to provide Client ID, Client Secret and url for the OIDC configuration endpoint as a bare minimum for the `omniauth_oidc` to work properly.
-Create an initializer file at `config/initializers/omniauth.rb`
+
+You must provide Client ID, Client Secret, and the URL for the OIDC configuration endpoint as a minimum for `omniauth_oidc` to work. Create an initializer file at `config/initializers/omniauth.rb`:
 
 ```ruby
 # config/initializers/omniauth.rb
@@ -39,13 +42,13 @@ Rails.application.config.middleware.use OmniAuth::Builder do
 end
 ```
 
-With Devise
+With Devise:
 
 ```ruby
 Devise.setup do |config|
   config.omniauth :oidc, {
     name: :simple_provider,
-    scope: [:openid, :email, :profile, :address],
+    scope: %w[openid email profile address],
     response_type: :code,
     uid_field: "preferred_username",
     client_options: {
@@ -57,7 +60,7 @@ Devise.setup do |config|
 end
 ```
 
-The gem also supports a wide range of optional parameters for higher degree of configurability.
+The gem also supports a wide range of optional parameters for a higher degree of configurability:
 
 ```ruby
 # config/initializers/omniauth.rb
@@ -65,7 +68,7 @@ Rails.application.config.middleware.use OmniAuth::Builder do
   provider :oidc, {
     name: :complex_provider, # used for dynamic routing
     issuer: 'https://complexprovider.com/cdn-cgi/access/sso/oidc/23575f4602bebbd9a17dbc38d85bd1a77',
-    scope: [:openid],
+    scope: %w[openid],
     response_type: 'id_token',
     require_state: true,
     response_mode: :query,
@@ -73,24 +76,25 @@ Rails.application.config.middleware.use OmniAuth::Builder do
     send_nonce: false,
     uid_field: "sub",
     pkce: false,
+    jwks_cache_ttl: 3600, # JWKS cache TTL in seconds (default: 3600)
     client_options: {
       identifier: '23575f4602bebbd9a17dbc38d85bd1a77',
       secret: ENV['COMPLEX_PROVIDER_CLIENT_SECRET'],
       config_endpoint: 'https://complexprovider.com/cdn-cgi/access/sso/oidc/23575f4602bebbd9a17dbc38d85bd1a77/.well-known/openid-configuration',
-      host: 'complexprovider.com'
+      host: 'complexprovider.com',
       scheme: "https",
       port: 443,
       authorization_endpoint: 'https://complexprovider.com/cdn-cgi/access/sso/oidc/23575f4602bebbd9a17dbc38d85bd1a77/authorization',
       token_endpoint: 'https://complexprovider.com/cdn-cgi/access/sso/oidc/23575f4602bebbd9a17dbc38d85bd1a77/token',
       userinfo_endpoint: 'https://complexprovider.com/cdn-cgi/access/sso/oidc/23575f4602bebbd9a17dbc38d85bd1a77/userinfo',
       jwks_uri: 'https://complexprovider.com/cdn-cgi/access/sso/oidc/23575f4602bebbd9a17dbc38d85bd1a77/jwks',
-      end_session_endpoint: '/signout'
+      end_session_endpoint: 'https://complexprovider.com/signout'
     }
   }
 end
 ```
 
-Ensure to replace identifier, secret, configuration endpoint url and others with credentials received from your OIDC provider.
+Ensure to replace identifier, secret, configuration endpoint URL and others with credentials received from your OIDC provider.
 Please note that the gem does not accept `redirect_uri` as a configurable option. For details please see section Routes.
 
 ### Redirecting for Authentication
@@ -103,7 +107,7 @@ Buttons and links to initialize the authentication request can be placed on rele
 
 ### Handling Callbacks
 
-The gem uses dyanmic routes to handle different phases, and while you can use same routes in your Rails application, for
+The gem uses dynamic routes to handle different phases, and while you can use same routes in your Rails application, for
 better experience you should have a controller to process the authenticated user. Create a CallbacksController:
 
 ```ruby
@@ -113,9 +117,9 @@ class CallbacksController < ApplicationController
     # user info received from OIDC provider will be available in `request.env['omniauth.auth']`
     auth = request.env['omniauth.auth']
 
-    user = User.find_or_create_by(uid: auth['uid']) do |user|
-      user.name = auth['info']['name']
-      user.email = auth['info']['email']
+    user = User.find_or_create_by(uid: auth['uid']) do |u|
+      u.name = auth['info']['name']
+      u.email = auth['info']['email']
     end
 
     session[:user_id] = user.id
@@ -124,17 +128,48 @@ class CallbacksController < ApplicationController
 end
 ```
 
+The `omniauth.auth` hash includes:
+
+```ruby
+{
+  provider: :simple_provider,
+  uid: "user123",
+  info: {
+    name: "Test User",
+    email: "test@example.com",
+    email_verified: true,
+    nickname: "testuser",         # preferred_username
+    first_name: "Test",           # given_name
+    last_name: "User",            # family_name
+    gender: "male",
+    image: "https://example.com/avatar.jpg",  # picture
+    phone: "+1234567890",         # phone_number
+    urls: { website: "https://testuser.com" }
+  },
+  credentials: {
+    id_token: "eyJ...",
+    token: "access_token_value",
+    refresh_token: "refresh_token_value",
+    expires_in: 3600,
+    scope: "openid profile email"
+  },
+  extra: {
+    raw_info: { ... }  # full userinfo response attributes
+  }
+}
+```
+
 ### Routes
 
 The gem uses dynamic routes when making requests to the OIDC provider endpoints, so called `redirect_uri` which is a
-non-configurable value that follows the naming pattern of `https://your_app.com/auth/<simple_provider>/callback`, 
+non-configurable value that follows the naming pattern of `https://your_app.com/auth/<simple_provider>/callback`,
 where `<simple_provider>` is the provider name defined within the configuration of the `omniauth.rb` initializer.
 This represents the `redirect_uri` that will be passed with the authorization request to your OIDC provider and that
 has to be registered with your OIDC provider as permitted `redirect_uri`.
 
 Dynamic routes are used to process responses and perform intermediary steps by the middleware, e.g. request phase,
-token verification. While you can define and use same routes within your Rails app, it is highly recommended to modify 
-your `routes.rb` to perform a dynamic redirect to a another controller method so this does not cause any conflicts with
+token verification. While you can define and use same routes within your Rails app, it is highly recommended to modify
+your `routes.rb` to perform a dynamic redirect to another controller method so this does not cause any conflicts with
 the middleware or the authorization flow.
 
 In an example below, `auth/:provider/callback` is generalized `redirect_uri` value that is passed in the authorization
@@ -163,11 +198,11 @@ end
 ```
 
 **Please note that you should register `https://your_app.com/auth/<simple_provider>/callback` with your OIDC provider
-as a callback redirect url.**
+as a callback redirect URL.**
 
 ### Using Access Token Without User Info
 
-In case your app requries only an access token and not the user information, then you can specify an optional
+In case your app requires only an access token and not the user information, then you can specify an optional
 configuration in the omniauth initializer:
 
 ```ruby
@@ -185,38 +220,17 @@ Rails.application.config.middleware.use OmniAuth::Builder do
 end
 ```
 
-Then the callback returned once your user authenticates with the OIDC provider will contain only access token parameters:
-
-```ruby
-# app/controllers/callbacks_controller.rb
-class CallbacksController < ApplicationController
-  def omniauth
-    # access token parameters received from OIDC provider will be available in `request.env['omniauth.auth']`
-    omniauth_params = request.env['omniauth.auth']
-
-    # omniauth_params will contain similar data as shown below
-    # {"provider"=>:simple_provider_access_token_only,
-    #  "credentials"=>
-    #   {"id_token"=> "id token value",
-    #    "token"=> "token value",
-    #    "refresh_token"=>"refresh token value",
-    #    "expires_in"=>300,
-    #    "scope"=>nil
-    #   }
-    # }
-  end
-end
-```
+When `fetch_user_info` is `false`, user info is extracted from the ID token claims instead of calling the userinfo endpoint. If the userinfo endpoint call fails, the gem also falls back to ID token claims automatically.
 
 ### Ending Session
 
 The gem provides two configuration options to allow ending a session simultaneously with your client application and the
 OIDC provider.
 
-To use this feature, you need to provide a `logout_path` in the options and an `end_session_endpoint` in the client 
-options. Here’s a sample setup:
+To use this feature, you need to provide a `logout_path` in the options and an `end_session_endpoint` in the client
+options. Here's a sample setup:
 
-``` ruby
+```ruby
   provider :oidc, {
     name: :simple_provider,
     client_options: {
@@ -236,32 +250,76 @@ options. Here’s a sample setup:
 Using these two configurations, you can ensure that when a user logs out from your application, they are also logged out
 from the OIDC provider, providing a seamless logout across multiple services.
 
-This works by calling `other_phase` on every controller request in your application. The method checks if the requested 
-URL matches the defined `logout_path`. If it does (i.e. current user has requested to log out from your application) 
-`other_phase` performs a redirect to the `end_session_endpoint` to terminate the user's session with the OIDC provider 
+This works by calling `other_phase` on every controller request in your application. The method checks if the requested
+URL matches the defined `logout_path`. If it does (i.e. current user has requested to log out from your application)
+`other_phase` performs a redirect to the `end_session_endpoint` to terminate the user's session with the OIDC provider
 and then it returns back to your application and concludes the request to end the current user's session.
 
 For additional details please refer to the [OIDC specification](https://openid.net/specs/openid-connect-session-1_0-17.html#:~:text=%C2%A0TOC-,5.%C2%A0%20RP%2DInitiated%20Logout,-An%20RP%20can).
 
+### Logging
+
+The gem includes built-in logging with automatic sensitive data sanitization. By default, log level is set to WARN.
+
+```ruby
+# Set log level
+OmniauthOidc::Logging.log_level = Logger::INFO
+
+# Use a custom logger
+OmniauthOidc::Logging.logger = Rails.logger
+```
+
+If ActiveSupport::Notifications is available (e.g. in Rails), the gem publishes instrumentation events:
+
+- `config.fetch.omniauth_oidc` — OIDC discovery document fetch
+- `token.exchange.omniauth_oidc` — authorization code to token exchange
+- `userinfo.fetch.omniauth_oidc` — userinfo endpoint call
+- `jwks.fetch.omniauth_oidc` — JWKS fetch
+- `request_phase.start.omniauth_oidc` — authorization redirect
+- `callback_phase.start.omniauth_oidc` — callback processing
+- `id_token.verify.omniauth_oidc` — ID token verification
+
+### Error Handling
+
+The gem raises specific error classes that you can rescue in your callback handling:
+
+| Error Class | When Raised |
+|---|---|
+| `OmniauthOidc::MissingConfigurationError` | Required options (`identifier`, `secret`, `config_endpoint`) are missing |
+| `OmniauthOidc::ConfigurationError` | OIDC discovery endpoint fetch fails |
+| `OmniauthOidc::TokenError` | Token exchange fails |
+| `OmniauthOidc::TokenVerificationError` | JWT format is invalid |
+| `OmniauthOidc::TokenExpiredError` | ID token `exp` claim is in the past |
+| `OmniauthOidc::InvalidAlgorithmError` | JWT algorithm does not match `client_signing_alg` |
+| `OmniauthOidc::InvalidSignatureError` | JWT signature verification fails |
+| `OmniauthOidc::InvalidIssuerError` | ID token `iss` does not match expected issuer |
+| `OmniauthOidc::InvalidAudienceError` | ID token `aud` does not match client identifier |
+| `OmniauthOidc::InvalidNonceError` | ID token `nonce` does not match stored nonce |
+| `OmniauthOidc::JwksFetchError` | JWKS endpoint fetch fails |
+
+All error classes inherit from `OmniauthOidc::Error < RuntimeError`.
+
 ### Advanced Configuration
+
 You can customize the OIDC strategy further by adding additional configuration options:
 
 | Field                        | Description                                                                                                                                                           | Required                | Default Value                       | Example/Notes                                         |
 |------------------------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------|-------------------------|-------------------------------------|-------------------------------------------------------|
 | name                         | Arbitrary string to identify OIDC provider and segregate it from other OIDC providers                                                                                 | no                      | `"oidc"`                            | `:simple_provider`                                    |
-| issuer                       | Root url for the OIDC authorization server                                                                                                                            | no                      | retrived from config_endpoint       | `"https://simpleprovider.com"`                        |
-| fetch_user_info              | Fetches user information from user_info_endpoint using the access token. If set to false the omniauth params will include only access token                           | no                      | `true`                              | `fetch_user_info: false`                              |
-| client_auth_method           | Authentication method to be used with the OIDC authorization server                                                                                                   | no                      | `:basic`                            | `"basic"`, `"jwks"`                                   |
-| scope                        | OIDC scopes to be included in the server's response                                                                                                                   | `[:openid]` is required | all scopes offered by OIDC provider | `[:openid, :profile, :email]`                         |
+| issuer                       | Root url for the OIDC authorization server                                                                                                                            | no                      | retrieved from config_endpoint      | `"https://simpleprovider.com"`                        |
+| fetch_user_info              | Fetches user information from userinfo endpoint using the access token. If false, user info is extracted from ID token claims                                          | no                      | `true`                              | `fetch_user_info: false`                              |
+| client_signing_alg           | Expected JWT signing algorithm. If set, tokens signed with a different algorithm are rejected                                                                          | no                      | `nil` (any algorithm accepted)      | `"RS256"`, `"HS256"`                                  |
+| scope                        | OIDC scopes to request. Accepts Array or String; always sent as a space-delimited string                                                                              | `openid` is required    | all scopes offered by OIDC provider | `%w[openid profile email]`                            |
 | response_type                | OAuth2 response type expected from OIDC provider during authorization                                                                                                 | no                      | `"code"`                            | `"code"` or `"id_token"`                              |
 | state                        | Value to be used for the OAuth2 state parameter on the authorization request. Can be a proc that generates a string                                                   | no                      | Random 16 character string          | `Proc.new { SecureRandom.hex(32) }`                   |
 | require_state                | Boolean to indicate if state param should be verified. This is a recommendation by OIDC spec                                                                          | no                      | `true`                              | `true` or `false`                                     |
 | response_mode                | The response mode per [OIDC spec](https://openid.net/specs/oauth-v2-form-post-response-mode-1_0.html)                                                                 | no                      | `nil`                               | `:query`, `:fragment`, `:form_post` or `:web_message` |
 | display                      | Specifies how OIDC authorization server should display the authentication and consent UI pages to the end user                                                        | no                      | `nil`                               | `:page`, `:popup`, `:touch` or `:wap`                 |
 | prompt                       | Specifies whether the OIDC authorization server prompts the end user for reauthentication and consent                                                                 | no                      | `nil`                               | `:none`, `:login`, `:consent` or `:select_account`    |
+| send_nonce                   | Include a nonce in the authorization request and verify it in the ID token                                                                                            | no                      | `true`                              | `true` or `false`                                     |
 | send_scope_to_token_endpoint | Should the scope parameter be sent to the authorization token endpoint                                                                                                | no                      | `true`                              | `true` or `false`                                     |
 | post_logout_redirect_uri     | Logout redirect uri to use per the [session management draft](https://openid.net/specs/openid-connect-session-1_0.html)                                               | no                      | `nil`                               | `"https://your_app.com/logout/callback"`              |
-| uid_field                    | Field of the user info response to be used as a unique ID                                                                                                             | no                      | `'sub'`                             | `"sub"` or `"preferred_username"`                     |
+| uid_field                    | Field of the user info response to be used as a unique ID                                                                                                             | no                      | `"sub"`                             | `"sub"` or `"preferred_username"`                     |
 | extra_authorize_params       | Hash of extra fixed parameters that will be merged to the authorization request                                                                                       | no                      | `{}`                                | `{"tenant" => "common"}`                              |
 | allow_authorize_params       | List of allowed dynamic parameters that will be merged to the authorization request                                                                                   | no                      | `[]`                                | `[:screen_name]`                                      |
 | pkce                         | Enable [PKCE flow](https://oauth.net/2/pkce/)                                                                                                                         | no                      | `false`                             | `true` or `false`                                     |
@@ -269,9 +327,13 @@ You can customize the OIDC strategy further by adding additional configuration o
 | pkce_options                 | Specify custom implementation of the PKCE code challenge/method                                                                                                       | no                      | SHA256(code_challenge) in hex       | Proc to customise the code challenge generation       |
 | client_options               | Hash of client options detailed below in a separate table                                                                                                             | yes                     | see below                           | see below                                             |
 | jwt_secret_base64            | Specify the base64-encoded secret used to sign the JWT token for HMAC with SHA2 (e.g. HS256) signing algorithms                                                       | no                      | `client_options.secret`             | `"bXlzZWNyZXQ=\n"`                                    |
-| logout_path                  | Log out is only triggered when the request path ends on this path                                                                                                     | no                      | `'/logout'`                         | '/sign_out'                                           |
-| acr_values                   | Authentication Class Reference (ACR) values to be passed to the authorize_uri to enforce a specific level, see [RFC9470](https://www.rfc-editor.org/rfc/rfc9470.html) | no                      | `nil`                               | `"c1 c2"`                                             å|
-
+| client_jwk_signing_key       | JWK or JWKS (as JSON string or Hash) for local signature verification without fetching from `jwks_uri`                                                                | no                      | `nil`                               | `'{"kty":"RSA","n":"...","e":"AQAB"}'`                |
+| client_x509_signing_key      | X.509 certificate (PEM format) for local signature verification                                                                                                       | no                      | `nil`                               | PEM string                                            |
+| logout_path                  | Log out is only triggered when the request path ends on this path                                                                                                     | no                      | `"/logout"`                         | `"/sign_out"`                                         |
+| jwks_cache_ttl               | JWKS cache time-to-live in seconds                                                                                                                                    | no                      | `3600` (1 hour)                     | `7200`                                                |
+| hd                           | Google-specific: hosted domain parameter                                                                                                                              | no                      | `nil`                               | `"example.com"`                                       |
+| max_age                      | Maximum authentication age in seconds                                                                                                                                 | no                      | `nil`                               | `3600`                                                |
+| acr_values                   | Authentication Class Reference (ACR) values per [RFC9470](https://www.rfc-editor.org/rfc/rfc9470.html)                                                                | no                      | `nil`                               | `"c1 c2"`                                             |
 
 Below are options for the `client_options` hash of the configuration:
 
@@ -280,14 +342,14 @@ Below are options for the `client_options` hash of the configuration:
 | identifier             | OAuth2 client_id                                            |    yes   | `nil`                         |
 | secret                 | OAuth2 client secret                                        |    yes   | `nil`                         |
 | config_endpoint        | OIDC configuration endpoint                                 |    yes   | `nil`                         |
-| scheme                 | http scheme to use                                          |     no   | https                         |
-| host                   | host of the authorization server                            |     no   | nil                           |
-| port                   | port for the authorization server                           |     no   | 443                           |
-| authorization_endpoint | authorize endpoint on the authorization server              |     no   | retrived from config_endpoint |
-| token_endpoint         | token endpoint on the authorization server                  |     no   | retrived from config_endpoint |
-| userinfo_endpoint      | user info endpoint on the authorization server              |     no   | retrived from config_endpoint |
-| jwks_uri               | jwks_uri on the authorization server                        |     no   | retrived from config_endpoint |
-| end_session_endpoint   | url to call to log the user out at the authorization server |     no   | `nil`                         |
+| scheme                 | HTTP scheme to use                                          |     no   | `"https"`                     |
+| host                   | Host of the authorization server                            |     no   | `nil`                         |
+| port                   | Port for the authorization server                           |     no   | `443`                         |
+| authorization_endpoint | Authorize endpoint on the authorization server              |     no   | retrieved from config_endpoint |
+| token_endpoint         | Token endpoint on the authorization server                  |     no   | retrieved from config_endpoint |
+| userinfo_endpoint      | User info endpoint on the authorization server              |     no   | retrieved from config_endpoint |
+| jwks_uri               | JWKS URI on the authorization server                        |     no   | retrieved from config_endpoint |
+| end_session_endpoint   | URL to call to log the user out at the authorization server |     no   | `nil`                         |
 
 ## Contributing
 

data/lib/omniauth/oidc/client.rb

@@ -0,0 +1,86 @@
+# frozen_string_literal: true
+
+require "base64"
+
+module OmniauthOidc
+  # Custom OIDC client using Net::HTTP
+  class Client
+    attr_accessor :identifier, :secret, :authorization_endpoint, :token_endpoint, :userinfo_endpoint,
+                  :host, :redirect_uri
+
+    def initialize(options = {})
+      @identifier = options[:identifier] || options["identifier"]
+      @secret = options[:secret] || options["secret"]
+      @authorization_endpoint = options[:authorization_endpoint] || options["authorization_endpoint"]
+      @token_endpoint = options[:token_endpoint] || options["token_endpoint"]
+      @userinfo_endpoint = options[:userinfo_endpoint] || options["userinfo_endpoint"]
+      @redirect_uri = options[:redirect_uri] || options["redirect_uri"]
+    end
+
+    def authorization_uri(params = {})
+      uri = URI.parse(authorization_endpoint)
+      query_params = {
+        client_id: identifier,
+        response_type: params[:response_type] || "code",
+        scope: params[:scope] || "openid profile email",
+        redirect_uri: params[:redirect_uri] || @redirect_uri,
+        state: params[:state],
+        nonce: params[:nonce]
+      }.compact
+
+      # Add PKCE parameters if provided
+      query_params[:code_challenge] = params[:code_challenge] if params[:code_challenge]
+      query_params[:code_challenge_method] = params[:code_challenge_method] if params[:code_challenge_method]
+
+      # Add any additional params
+      query_params.merge!(params[:extra_params]) if params[:extra_params]
+
+      uri.query = URI.encode_www_form(query_params)
+      uri.to_s
+    end
+
+    def access_token!(params = {}) # rubocop:disable Metrics/MethodLength
+      body_params = {
+        grant_type: "authorization_code",
+        code: params[:code],
+        redirect_uri: params[:redirect_uri] || @redirect_uri,
+        client_id: identifier,
+        client_secret: secret
+      }
+
+      # Add PKCE verifier if provided
+      body_params[:code_verifier] = params[:code_verifier] if params[:code_verifier]
+
+      OmniauthOidc::Logging.instrument("token.exchange", code: "[FILTERED]") do
+        response = HttpClient.post(
+          token_endpoint,
+          body: URI.encode_www_form(body_params),
+          headers: {
+            "Content-Type" => "application/x-www-form-urlencoded",
+            "Accept" => "application/json"
+          }
+        )
+
+        ResponseObjects::AccessToken.new(response)
+      end
+    rescue HttpClient::HttpError => e
+      raise OmniauthOidc::TokenError, "Token exchange failed: #{e.message}"
+    end
+
+    def userinfo!(access_token)
+      OmniauthOidc::Logging.instrument("userinfo.fetch", endpoint: userinfo_endpoint) do
+        response = HttpClient.get(
+          userinfo_endpoint,
+          headers: {
+            "Authorization" => "Bearer #{access_token}",
+            "Accept" => "application/json"
+          }
+        )
+
+        ResponseObjects::UserInfo.new(response)
+      end
+    rescue HttpClient::HttpError => e
+      raise OmniauthOidc::TokenError, "Failed to fetch user info: #{e.message}"
+    end
+  end
+end

data/lib/omniauth/oidc/config_fetcher.rb

@@ -0,0 +1,76 @@
+# frozen_string_literal: true
+
+module OmniauthOidc
+  # Fetches and parses OpenID Connect configuration from .well-known endpoint
+  class ConfigFetcher
+    # Config object with dynamic attribute access for OIDC discovery fields
+    class Config
+      def initialize(attributes = {})
+        @attributes = attributes
+      end
+
+      def [](key)
+        @attributes[key.to_sym] || @attributes[key.to_s]
+      end
+
+      def []=(key, value)
+        @attributes[key.to_sym] = value
+        @attributes[key.to_s] = value
+      end
+
+      def respond_to_missing?(method_name, include_private = false)
+        setter = method_name.to_s.end_with?("=")
+        key = setter ? method_name.to_s.chomp("=") : method_name.to_s
+        setter || @attributes.key?(key.to_sym) || @attributes.key?(key) || super
+      end
+
+      private
+
+      def method_missing(method_name, *args)
+        name = method_name.to_s
+
+        if name.end_with?("=")
+          key = name.chomp("=")
+          @attributes[key.to_sym] = args.first
+          @attributes[key] = args.first
+        elsif @attributes.key?(name.to_sym)
+          @attributes[name.to_sym]
+        elsif @attributes.key?(name)
+          @attributes[name]
+        else
+          super
+        end
+      end
+    end
+
+    class << self
+      def fetch(endpoint_url, max_retries: 3)
+        retries = 0
+        begin
+          response = OmniauthOidc::HttpClient.get(endpoint_url)
+          symbolized_config = deep_symbolize_keys(response)
+          Config.new(symbolized_config)
+        rescue OmniauthOidc::HttpClient::HttpError => e
+          retries += 1
+          retry if retries < max_retries
+          raise OmniauthOidc::ConfigurationError, "Failed to fetch OIDC configuration: #{e.message}"
+        rescue StandardError => e
+          raise OmniauthOidc::ConfigurationError, "Failed to fetch OIDC configuration: #{e.message}"
+        end
+      end
+
+      private
+
+      # Recursively converts keys of a hash to symbols while retaining the original string keys
+      def deep_symbolize_keys(hash)
+        result = {}
+        hash.each do |key, value|
+          sym_key = key.to_sym
+          result[sym_key] = value.is_a?(Hash) ? deep_symbolize_keys(value) : value
+          result[key] = result[sym_key] # Add the string key as well
+        end
+        result
+      end
+    end
+  end
+end