himari 0.5.0 → 0.7.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 5b8557a7f7d75db91d61c20e931bfa9d05d832541b4fb9fdc05055491568e4ec
-  data.tar.gz: c50b5396fa19b2c03b2b4115d495f3f96a688016a4c8d3fb9b1833ef10de13b7
+  metadata.gz: f986e727b538f1f6f512f6787e7546e1ebdaa942398053966d52db1383135fc8
+  data.tar.gz: a300ee5b77dc2e1f7c5befbae719876cc60f08a742d97c43f71bdd44fb170adc
 SHA512:
-  metadata.gz: eac9157e67de6f6c2538b36f7d6a55e62f1d3a7e3837e72a23d0b6d407a40a2004f7a7fee8c71b036c709daf6be970a75ae45118c116bbd4ab1a085eb23af137
-  data.tar.gz: b40f7ed7a033f312871a191398ba1d74f376c89d634666b4b076a05666a66309d8886d0bd3d441144d1fea781847e6f020fa9ec39a079ac1ef3f48f9f332efba
+  metadata.gz: 1bf93eaa1f6f98c45ec2649278ccb571f26a530f7b5b4d6c35d0b15e250861f9fc7e6efdb7f3c77de9abd177330b86970d9b1de29df2a0cdb4c4d65f33933fb0
+  data.tar.gz: 033b8dfa409cea02e7ddd73a6369c261e0d79402ab7a82cab49cbffafc654b12bb08dabd42b824382d4143b426d2749117014b94e96bd4d1b67de7e2ca8e37ef

data/CHANGELOG.md

@@ -0,0 +1,64 @@
+## [0.7.0] - 2026-06-06
+
+### Enhancements
+
+- Authorization Server Issuer Identification (RFC 9207): the authorization endpoint now returns the `iss` parameter in all authorization responses (success and redirected errors), and discovery metadata advertises `authorization_response_iss_parameter_supported`
+
+## [0.6.0] - 2026-06-03
+
+### Enhancements
+
+- Refresh token (`refresh_token` grant) support [#14](https://github.com/sorah/himari/pull/14)
+- Dynamic client registration (RFC 7591), Client ID Metadata Documents, an RFC 8414 `oauth-authorization-server` metadata endpoint, and Himari-owned `redirect_uri` matching with loopback-port relaxation and `Regexp` entries [#15](https://github.com/sorah/himari/pull/15)
+- Interactive consent page gated by the client `skip_consent` attribute [#16](https://github.com/sorah/himari/pull/16)
+- Per-client `scopes` allow-list [#17](https://github.com/sorah/himari/pull/17)
+- Persist granted scopes on the grant and expose them to authorization rules as `context.scopes` [#19](https://github.com/sorah/himari/pull/19)
+- Opt-in RFC 9068 (`at+jwt`) JWT access tokens [#20](https://github.com/sorah/himari/pull/20)
+- Configurable `scopes_supported`/`claims_supported` and advertise `refresh_token`/`offline_access` in discovery metadata [#21](https://github.com/sorah/himari/pull/21)
+
+## [0.5.0] - 2024-05-11
+
+### Enhancements
+
+- Userinfo endpoint now returns the `aud` claim.
+- Client gains the `require_pkce` attribute.
+
+## [0.4.0] - 2023-03-26
+
+### Enhancements
+
+- Support `prompt=login` for reauthentication; the userinfo endpoint now also answers POST [#8](https://github.com/sorah/himari/pull/8)
+- Store `SessionData` in a storage backend [#7](https://github.com/sorah/himari/pull/7)
+- Introduce the `omniauth-himari` strategy gem [#6](https://github.com/sorah/himari/pull/6)
+- Access token gains its own lifetime.
+
+### Changes
+
+- Rename `AccessToken#handler` to `handle` and stop treating the token handle as a sensitive value [#5](https://github.com/sorah/himari/pull/5)
+- Disable `Rack::Protection::JsonCsrf` for ALB OIDC compatibility [#1](https://github.com/sorah/himari/pull/1)
+
+### Bug fixes
+
+- Fix error when logging an expired session token.
+
+## [0.3.0] - 2023-03-22
+
+### Enhancements
+
+- Customizable session and token lifetimes.
+- `suggest=reauthenticate` to prompt login, with a decision `user_facing_message`.
+
+### Bug fixes
+
+- Callback returns 400 when the auth hash is missing.
+
+## [0.2.0] - 2023-03-22
+
+### Enhancements
+
+- Better login page template with cachebuster.
+- Prebuilt container image.
+
+## [0.1.0] - 2023-02-25
+
+- Initial release

data/lib/himari/access_token.rb

@@ -1,7 +1,11 @@
+# frozen_string_literal: true
+
 require 'rack/oauth2'
 require 'openid_connect'
+require 'json/jwt'
 
 require 'himari/token_string'
+require 'himari/access_token_jwt'
 
 module Himari
   class AccessToken
@@ -23,26 +27,67 @@ module Himari
       3600
     end
 
+    # Parse a presented access token into its opaque Format (handle + secret) for verification
+    # against storage. Two on-the-wire shapes are accepted:
+    #
+    # - the opaque token "hmat.<handle>.<secret>" (TokenString format), or
+    # - an RFC 9068 JWT (Himari::AccessTokenJwt) carrying the opaque token in its +hmat+ claim.
+    #
+    # For a JWT, the signature is verified first (requires signing_key_provider to resolve the
+    # kid), then the embedded opaque token is returned so the caller validates the secret against
+    # storage exactly as for an opaque token. Any malformed/unverifiable JWT becomes
+    # TokenString::InvalidFormat so callers handle one failure type.
+    #
+    # @param signing_key_provider [Himari::ProviderChain<Himari::SigningKey>, nil]
+    def self.parse(str, signing_key_provider: nil)
+      return TokenString::Format.parse(magic_header, str) if str.to_s.start_with?("#{magic_header}.")
+
+      parse_jwt(str, signing_key_provider)
+    end
+
+    def self.parse_jwt(str, signing_key_provider)
+      raise TokenString::InvalidFormat, 'signing keys are required to verify a JWT access token' unless signing_key_provider
+
+      jwt = JSON::JWT.decode(str, :skip_verification)
+      key = jwt.kid && signing_key_provider.find(id: jwt.kid)
+      raise TokenString::InvalidFormat, 'unknown or missing signing key (kid)' unless key
+
+      jwt.verify!(key.pkey)
+
+      hmat = jwt[magic_header]
+      raise TokenString::InvalidFormat, 'missing hmat claim' unless hmat.is_a?(String) && hmat.start_with?("#{magic_header}.")
+
+      TokenString::Format.parse(magic_header, hmat)
+    rescue JSON::JWT::Exception, JSON::ParserError => e
+      raise TokenString::InvalidFormat, "invalid JWT access token: #{e.class}"
+    end
+
     # @param authz [Himari::AuthorizationCode]
     def self.from_authz(authz)
       make(
         client_id: authz.client_id,
         claims: authz.claims,
+        scopes: authz.scopes,
+        session_handle: authz.session_handle,
         lifetime: authz.lifetime.access_token,
       )
     end
 
-    def initialize(handle:, client_id:, claims:, expiry:, secret: nil, secret_hash: nil)
+    def initialize(handle:, client_id:, claims:, expiry:, scopes: [], session_handle: nil, secret: nil, secret_hash: nil)
       @handle = handle
       @client_id = client_id
       @claims = claims
+      @scopes = scopes
+      @session_handle = session_handle
       @expiry = expiry
 
       @secret = secret
       @secret_hash = secret_hash
+      @secret_hash_prev = nil
+      @verification = nil
     end
 
-    attr_reader :handle, :client_id, :claims, :expiry
+    attr_reader :handle, :client_id, :claims, :scopes, :session_handle, :expiry
 
     def userinfo
       claims.merge(
@@ -50,18 +95,39 @@ module Himari
       )
     end
 
-    def to_bearer
+    # @param token_string [String] the on-the-wire access token to deliver. Defaults to the
+    #   opaque format; the token endpoint passes the RFC 9068 JWT when one was minted.
+    def to_bearer(token_string: format.to_s)
       Bearer.new(
-        access_token: format.to_s,
+        access_token: token_string,
         expires_in: (expiry - Time.now.to_i).to_i,
       )
     end
 
+    # Render this token as an RFC 9068 JWT (Himari::AccessTokenJwt). The opaque secret travels in
+    # the JWT's hmat claim, so the token validates against storage the same way either form does.
+    # exp is tied to this token's own expiry rather than recomputed, keeping both forms in sync.
+    # @param signing_key [Himari::SigningKey]
+    # @param issuer [String]
+    def to_jwt(signing_key:, issuer:, now: Time.now)
+      AccessTokenJwt.new(
+        access: self,
+        claims: claims,
+        client_id: client_id,
+        signing_key: signing_key,
+        issuer: issuer,
+        time: now,
+        lifetime: expiry - now.to_i,
+      ).to_jwt
+    end
+
     def as_log
       {
         handle: handle,
         client_id: client_id,
         claims: claims,
+        scopes: scopes,
+        session_handle: session_handle,
         expiry: expiry,
       }
     end
@@ -72,6 +138,8 @@ module Himari
         secret_hash: secret_hash,
         client_id: client_id,
         claims: claims,
+        scopes: scopes,
+        session_handle: session_handle,
         expiry: expiry.to_i,
       }
     end

data/lib/himari/access_token_jwt.rb

@@ -0,0 +1,46 @@
+# frozen_string_literal: true
+
+require 'himari/jwt_token'
+require 'himari/access_token'
+
+module Himari
+  # RFC 9068 (JWT Profile for OAuth 2.0 Access Tokens) representation of an access token. The
+  # signed JWT carries the same IdP claims as the ID Token for relying parties to consume
+  # directly, plus the registered claims RFC 9068 requires. Himari still authenticates the token
+  # by the opaque secret embedded in the +hmat+ claim (see Himari::AccessToken.parse), so the
+  # JWT signature is an additional, self-contained guarantee for relying parties.
+  class AccessTokenJwt < JwtToken
+    # sub is the one RFC 9068 §2.2 required claim sourced from variable IdP claims rather than set
+    # by us; fail closed at mint time if a misconfigured allowed_claims stripped it.
+    class MissingSubject < StandardError; end
+
+    # @param access [Himari::AccessToken] the minted, persisted opaque access token this JWT wraps
+    def initialize(access:, **kwargs)
+      super(**kwargs)
+      @access = access
+    end
+
+    # https://www.rfc-editor.org/rfc/rfc9068.html#section-2.1
+    def jwt_header
+      {typ: 'at+jwt'}
+    end
+
+    # https://www.rfc-editor.org/rfc/rfc9068.html#section-2.2
+    def final_claims
+      raise MissingSubject, 'RFC 9068 access token requires a sub claim' unless claims[:sub]
+
+      standard_claims.merge(
+        client_id: @client_id,
+        jti: @access.handle,
+        # The opaque access token Himari validates against storage; relying parties ignore it.
+        AccessToken.magic_header.to_sym => @access.format.to_s,
+      ).merge(scope_claim)
+    end
+
+    # https://www.rfc-editor.org/rfc/rfc9068.html#section-2.2.1 — space-delimited granted scopes.
+    private def scope_claim
+      scopes = @access.scopes
+      scopes && !scopes.empty? ? {scope: scopes.join(' ')} : {}
+    end
+  end
+end

data/lib/himari/app.rb

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 require 'sinatra/base'
 require 'addressable'
 require 'base64'
@@ -15,10 +17,13 @@ require 'himari/session_data'
 require 'himari/middlewares/client'
 require 'himari/middlewares/config'
 require 'himari/middlewares/signing_key'
+require 'himari/middlewares/dynamic_clients'
+require 'himari/middlewares/metadata_clients'
 
 require 'himari/services/downstream_authorization'
 require 'himari/services/upstream_authentication'
 
+require 'himari/services/client_registration_endpoint'
 require 'himari/services/jwks_endpoint'
 require 'himari/services/oidc_authorization_endpoint'
 require 'himari/services/oidc_provider_metadata_endpoint'
@@ -32,6 +37,7 @@ module Himari
     # remote_token: disabled in favor of authenticity_token (more stricter)
     # json_csrf: can be prevented using x-content-type-options:nosniff
     set :protection, use: %i(authenticity_token), except: %i(remote_token json_csrf)
+    set :host_authorization, {}
 
     set :logging, nil
 
@@ -42,13 +48,15 @@ module Himari
     helpers do
       def current_user
         return @current_user if defined? @current_user
+
         given_token = session[:himari_session]
-        return nil unless given_token
+        return unless given_token
 
         given_parsed_token = Himari::SessionData.parse(given_token)
 
         token = config.storage.find_session(given_parsed_token.handle)
         raise InvalidSessionToken, "no session found in storage (possibly expired)" unless token
+
         token.verify!(secret: given_parsed_token.secret)
 
         @current_user = token
@@ -70,12 +78,28 @@ module Himari
         Himari::ProviderChain.new(request.env[Himari::Middlewares::Client::RACK_KEY] || [])
       end
 
+      def dynamic_clients_enabled?
+        request.env.key?(Himari::Middlewares::DynamicClients::RACK_KEY)
+      end
+
+      def metadata_clients_enabled?
+        request.env.key?(Himari::Middlewares::MetadataClients::RACK_KEY)
+      end
+
       def known_providers
         back_to = if request.query_string.empty?
           request.path
         else
           Addressable::URI.parse(request.fullpath).tap do |u|
-            u.query_values = u.query_values.reject { |k,_v| k == 'prompt' }
+            # Drop only the prompt values that would re-trigger the login screen once the user
+            # comes back authenticated (otherwise we'd loop); keep the rest (e.g. consent) so they
+            # still apply at the authorize endpoint after login.
+            u.query_values = u.query_values.filter_map do |k, v|
+              next [k, v] unless k == 'prompt'
+
+              remaining = v.to_s.split(/\s+/) - %w(login select_account)
+              [k, remaining.join(' ')] unless remaining.empty?
+            end.to_h
           end.to_s
         end
         query = Addressable::URI.form_encode(back_to: back_to)
@@ -103,12 +127,10 @@ module Himari
       end
 
       def release_code
-        env['himari.release'] ||= begin
-          [
-            Himari::VERSION,
-            config.release_fragment,
-          ].compact.join(':')
-        end
+        env['himari.release'] ||= [
+          Himari::VERSION,
+          config.release_fragment,
+        ].compact.join(':')
       end
 
       def request_id
@@ -134,7 +156,7 @@ module Himari
     end
 
     before do
-      request_as_log()
+      request_as_log
     end
 
     get '/' do
@@ -142,16 +164,22 @@ module Himari
       "Himari #{release_code}\n"
     end
 
-    get '/oidc/authorize' do
+    # Served on GET (initial request and consent display) and POST (consent submission). The
+    # consent form posts the original authorization params back here as hidden fields plus a
+    # _consent decision; everything else flows through OidcAuthorizationEndpoint identically.
+    authorize_ep = proc do
       client = client_provider.find(id: params[:client_id])
       unless client
         logger&.warn(Himari::LogLine.new('authorize: no client registration found', req: request_as_log, client_id: params[:client_id]))
-        next halt 401, 'unknown client' 
+        next halt 401, 'unknown client'
       end
 
       if current_user
-        # do downstream authz and process oidc request
-        decision = Himari::Services::DownstreamAuthorization.from_request(session: current_user, client: client, request: request).perform
+        # do downstream authz and process oidc request. The OIDC request's scope is parsed the
+        # same way rack-oauth2 parses it downstream (OidcAuthorizationEndpoint), so the scopes the
+        # authz rules see match those the grant is filtered to.
+        requested_scopes = request.params['scope'].to_s.split(' ')
+        decision = Himari::Services::DownstreamAuthorization.from_request(session: current_user, client: client, request: request, requested_scopes: requested_scopes).perform
         logger&.info(Himari::LogLine.new('authorize: downstream authorized', req: request_as_log, session: current_user.as_log, allowed: decision.authz_result.allowed, result: decision.as_log))
         raise unless decision.authz_result.allowed # sanity check
 
@@ -159,23 +187,35 @@ module Himari
           client_id: decision.client.id,
           claims: decision.claims,
           lifetime: decision.lifetime,
+          mint_jwt_access_token: decision.mint_jwt_access_token,
+          session_handle: current_user.handle,
         )
 
+        consent = case params[:_consent]
+        when 'approve' then :approve
+        when 'deny' then :deny
+        end
+
         Himari::Services::OidcAuthorizationEndpoint.new(
           authz: authz,
           client: client,
           storage: config.storage,
+          issuer: config.issuer,
+          consent: consent,
           logger: logger,
         ).call(env)
       else
         logger&.info(Himari::LogLine.new('authorize: prompt login', req: request_as_log, client_id: params[:client_id]))
         erb(config.custom_templates[:login] || :login)
       end
-
     rescue Himari::Services::OidcAuthorizationEndpoint::ReauthenticationRequired
-      logger&.warn(Himari::LogLine.new('authorize: prompt login to reauthenticate (demanded by oidc request)',  req: request_as_log, session: current_user&.as_log, allowed: decision&.authz_result&.allowed, result: decision&.as_log))
+      logger&.warn(Himari::LogLine.new('authorize: prompt login to reauthenticate (demanded by oidc request)', req: request_as_log, session: current_user&.as_log, allowed: decision&.authz_result&.allowed, result: decision&.as_log))
       next erb(config.custom_templates[:login] || :login)
-
+    rescue Himari::Services::OidcAuthorizationEndpoint::ConsentRequired => e
+      logger&.info(Himari::LogLine.new('authorize: prompt consent', req: request_as_log, session: current_user&.as_log, client: e.client.as_log, scopes: e.scopes))
+      @consent_client = e.client
+      @consent_scopes = e.scopes
+      next erb(config.custom_templates[:consent] || :consent)
     rescue Himari::Services::DownstreamAuthorization::ForbiddenError => e
       logger&.warn(Himari::LogLine.new('authorize: downstream forbidden', req: request_as_log, session: current_user&.as_log, allowed: e.result.authz_result.allowed, err: e.class.inspect, result: e.as_log))
 
@@ -193,6 +233,8 @@ module Himari
 
       halt(403, "Forbidden#{message_human ? "; #{message_human}" : nil}")
     end
+    get '/oidc/authorize', &authorize_ep
+    post '/oidc/authorize', &authorize_ep
 
     token_ep = proc do
       Himari::Services::OidcTokenEndpoint.new(
@@ -209,6 +251,7 @@ module Himari
     userinfo_ep = proc do
       Himari::Services::OidcUserinfoEndpoint.new(
         storage: config.storage,
+        signing_key_provider: signing_key_provider,
         logger: logger,
       ).call(env)
     end
@@ -225,12 +268,43 @@ module Himari
     get '/jwks', &jwks_ep
     get '/public/jwks', &jwks_ep
 
-    get '/.well-known/openid-configuration' do
+    # RFC 7591 Dynamic Client Registration. Enabled by presence of the DynamicClients
+    # middleware; the route always exists but 404s when the feature is off.
+    register_ep = proc do
+      next halt 404, 'not found' unless dynamic_clients_enabled?
+
+      Himari::Services::ClientRegistrationEndpoint.new(
+        storage: config.storage,
+        registration_lifetime: request.env[Himari::Middlewares::DynamicClients::RACK_KEY].registration_lifetime,
+        ignore_localhost_redirect_uri_port: request.env[Himari::Middlewares::DynamicClients::RACK_KEY].ignore_localhost_redirect_uri_port,
+        logger: logger,
+      ).call(env)
+    end
+    post '/oidc/register', &register_ep
+    post '/public/oidc/register', &register_ep
+    # Wire the non-POST verbs too so they reach the endpoint, which answers 405 (RFC 7591 only
+    # defines POST). Without these Sinatra would 404 a GET, masking the method error.
+    %w(/oidc/register /public/oidc/register).each do |path|
+      get(path, &register_ep)
+      put(path, &register_ep)
+      patch(path, &register_ep)
+      delete(path, &register_ep)
+    end
+
+    metadata_ep = proc do
       Himari::Services::OidcProviderMetadataEndpoint.new(
         signing_key_provider: signing_key_provider,
         issuer: config.issuer,
+        registration_endpoint: dynamic_clients_enabled? ? "#{config.issuer}/public/oidc/register" : nil,
+        client_id_metadata_document_supported: metadata_clients_enabled?,
+        scopes_supported: config.scopes_supported,
+        claims_supported: config.claims_supported,
       ).call(env)
     end
+    # OpenID Connect Discovery 1.0
+    get '/.well-known/openid-configuration', &metadata_ep
+    # RFC 8414 OAuth 2.0 Authorization Server Metadata
+    get '/.well-known/oauth-authorization-server', &metadata_ep
 
     omniauth_callback = proc do
       authhash = request.env['omniauth.auth']
@@ -243,17 +317,17 @@ module Himari
 
       given_back_to = request.env['omniauth.params']&.fetch('back_to', nil)
       back_to = if given_back_to
-        uri = begin
-          Addressable::URI.parse(given_back_to)
-        rescue Addressable::URI::InvalidURIError
-          nil
-        end
-        if uri && uri.host.nil? && uri.scheme.nil? && uri.path.start_with?('/')
-          given_back_to
-        else
-          logger&.warn(Himari::LogLine.new('invalid back_to', req: request_as_log, given_back_to: given_back_to))
-          nil
-        end
+                  uri = begin
+                    Addressable::URI.parse(given_back_to)
+                  rescue Addressable::URI::InvalidURIError
+                    nil
+                  end
+                  if uri && uri.host.nil? && uri.scheme.nil? && uri.path.start_with?('/')
+                    given_back_to
+                  else
+                    logger&.warn(Himari::LogLine.new('invalid back_to', req: request_as_log, given_back_to: given_back_to))
+                    nil
+                  end
       end || '/'
 
       session.destroy

data/lib/himari/authorization_code.rb

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 require 'digest/sha2'
 require 'himari/lifetime_value'
 
@@ -6,7 +8,11 @@ module Himari
     code
     client_id
     claims
+    scopes
+    mint_jwt_access_token
     openid
+    offline_access
+    session_handle
     redirect_uri
     nonce
     code_challenge
@@ -24,23 +30,23 @@ module Himari
       )
     end
 
-    alias _lifetime_raw lifetime
+    alias_method :_lifetime_raw, :lifetime
     private :_lifetime_raw
     def lifetime
       case _lifetime_raw
       when Hash
         self.lifetime = LifetimeValue.new(**_lifetime_raw)
-      when Integer #compat
+      when Integer # compat
         self.lifetime = LifetimeValue.from_integer(_lifetime_raw)
       else
         _lifetime_raw
       end
     end
 
-    alias _expiry_raw expiry
+    alias_method :_expiry_raw, :expiry
     private :_expiry_raw
     def expiry
-      self._expiry_raw || (self.expiry = created_at + (lifetime&.code || 900))
+      _expiry_raw || (self.expiry = created_at + (lifetime&.code || 900))
     end
 
     def valid_redirect_uri?(given_uri)
@@ -80,7 +86,11 @@ module Himari
         client_id: client_id,
         claims: claims,
         nonce: nonce,
+        scopes: scopes,
+        mint_jwt_access_token: mint_jwt_access_token,
         openid: openid,
+        offline_access: offline_access,
+        session_handle: session_handle,
         created_at: created_at.to_i,
         lifetime: lifetime.as_log,
         expiry: expiry.to_i,
@@ -95,7 +105,11 @@ module Himari
         code: code,
         client_id: client_id,
         claims: claims,
+        scopes: scopes,
+        mint_jwt_access_token: mint_jwt_access_token,
         openid: openid,
+        offline_access: offline_access,
+        session_handle: session_handle,
         redirect_uri: redirect_uri,
         nonce: nonce,
         code_challenge: code_challenge,