omniauth-authify 0.1.1

data/lib/omniauth/authify/jwt_validator.rb

@@ -0,0 +1,237 @@
+# frozen_string_literal: true
+
+require "base64"
+require "json"
+require "net/http"
+require "uri"
+require "jwt"
+require "omniauth/authify/errors"
+
+module OmniAuth
+  module Authify
+    # Validates OpenID Connect ID tokens issued by Authify.
+    #
+    # Verifies the RS256 signature against the signing keys published at the
+    # organization's JWKS endpoint, and the standard ID token claims:
+    # iss, sub, aud, exp, iat, auth_time (when max_age applies), and nonce.
+    class JwtValidator
+      # ID token signature algorithms this validator accepts
+      SUPPORTED_ALGORITHMS = %w[RS256].freeze
+      # Claims that must be present in every ID token
+      REQUIRED_CLAIMS = %w[iss sub aud exp iat].freeze
+      # Network failures that map to a {TokenValidationError} during JWKS fetches
+      NETWORK_ERRORS = [SocketError, Errno::ECONNREFUSED, Timeout::Error, Net::OpenTimeout,
+                        OpenSSL::SSL::SSLError].freeze
+
+      # Creates a validator
+      #
+      # @param client_id [String] the OAuth2 client ID (expected `aud` value)
+      # @param issuer [String] the expected value of the ID token `iss` claim
+      # @param jwks_uri [String] the organization's JWKS endpoint URL
+      def initialize(client_id:, issuer:, jwks_uri:)
+        @client_id = client_id
+        @issuer = issuer
+        @jwks_uri = URI(jwks_uri)
+        @jwks = nil
+      end
+
+      # Decodes an ID token and verifies its signature and claims.
+      #
+      # @param jwt [String] the ID token
+      # @param authorize_params [Hash] per-login parameters stored at the
+      #   start of the flow; may contain +nonce+, +leeway+, +max_age+ and
+      #   +issuer+ (string or symbol keys)
+      # @return [Hash] the verified claims
+      # @raise [TokenValidationError] when the token cannot be verified
+      def verify(jwt, authorize_params = {})
+        raise TokenValidationError, "ID token is required but missing" if jwt.to_s.empty?
+
+        params = authorize_params || {}
+        claims, = decode(jwt)
+        verify_iss(claims, params)
+        verify_sub(claims)
+        verify_aud(claims)
+        verify_expiration(claims, params)
+        verify_iat(claims, params)
+        verify_auth_time(claims, params)
+        verify_nonce(claims, params)
+        claims
+      end
+
+      # Decodes an ID token, verifying its signature but skipping claim checks.
+      #
+      # @param jwt [String] the ID token
+      # @return [Array(Hash, Hash)] the claims and the JOSE header
+      # @raise [TokenValidationError] when the signature cannot be verified
+      def decode(jwt)
+        header = token_head(jwt)
+        algorithm = header["alg"]
+        unless SUPPORTED_ALGORITHMS.include?(algorithm)
+          raise TokenValidationError,
+                "Signature algorithm of #{algorithm.inspect} is not supported. " \
+                "Expected the ID token to be signed with RS256"
+        end
+
+        claims, = JWT.decode(
+          jwt,
+          nil,
+          true,
+          jwks: jwks_loader,
+          algorithms: [algorithm],
+          required_claims: REQUIRED_CLAIMS,
+          verify_iss: false,
+          verify_aud: false,
+          verify_expiration: false,
+          verify_iat: false
+        )
+        [claims, header]
+      rescue JWT::DecodeError, JWT::ExpiredSignature, JWT::JWKError => e
+        raise TokenValidationError, "ID token could not be verified: #{e.message}"
+      end
+
+      private
+
+      def verify_iss(claims, params)
+        expected = params[:issuer] || params["issuer"] || @issuer
+        return if claims["iss"] == expected
+
+        raise TokenValidationError,
+              "Issuer (iss) claim mismatch in the ID token, expected (#{expected}), " \
+              "found (#{claims["iss"].inspect})"
+      end
+
+      def verify_sub(claims)
+        subject = claims["sub"]
+        return if subject.is_a?(String) && !subject.empty?
+
+        raise TokenValidationError,
+              "Subject (sub) claim must be a string present in the ID token"
+      end
+
+      def verify_aud(claims)
+        audience = claims["aud"]
+        audiences = Array(audience)
+        if audience.to_s.empty?
+          raise TokenValidationError,
+                "Audience (aud) claim must be a string or array of strings present in the ID token"
+        end
+        return if audiences.include?(@client_id)
+
+        raise TokenValidationError,
+              "Audience (aud) claim mismatch in the ID token; expected (#{@client_id}), " \
+              "found (#{audiences.join(", ")})"
+      end
+
+      def verify_expiration(claims, params)
+        expiration = claims["exp"]
+        if !expiration.is_a?(Integer)
+          raise TokenValidationError,
+                "Expiration time (exp) claim must be a number present in the ID token"
+        elsif expiration <= Time.now.to_i - leeway(params)
+          raise TokenValidationError,
+                "Expiration time (exp) claim error in the ID token; " \
+                "current time (#{Time.now}) is after expiration time " \
+                "(#{Time.at(expiration + leeway(params))})"
+        end
+      end
+
+      def verify_iat(claims, params)
+        issued_at = claims["iat"]
+        if !issued_at.is_a?(Integer)
+          raise TokenValidationError,
+                "Issued At (iat) claim must be a number present in the ID token"
+        elsif issued_at > Time.now.to_i + leeway(params)
+          raise TokenValidationError,
+                "Issued At (iat) claim error in the ID token; issued in the future " \
+                "at #{Time.at(issued_at)} (current time #{Time.now})"
+        end
+      end
+
+      def verify_auth_time(claims, params)
+        max_age = params[:max_age] || params["max_age"]
+        return unless max_age
+
+        auth_time = claims["auth_time"]
+        if !auth_time.is_a?(Integer)
+          raise TokenValidationError,
+                "Authentication Time (auth_time) claim must be a number present in " \
+                "the ID token when Max Age (max_age) is specified"
+        elsif Time.now.to_i > auth_time + max_age.to_i + leeway(params)
+          raise TokenValidationError,
+                "Authentication Time (auth_time) claim in the ID token indicates that " \
+                "too much time has passed since the last end-user authentication"
+        end
+      end
+
+      def verify_nonce(claims, params)
+        nonce = params[:nonce] || params["nonce"]
+        return unless nonce
+
+        received = claims["nonce"]
+        if !received.is_a?(String) || received.empty?
+          raise TokenValidationError,
+                "Nonce (nonce) claim must be a string present in the ID token"
+        elsif received != nonce
+          raise TokenValidationError,
+                "Nonce (nonce) claim value mismatch in the ID token; " \
+                "expected (#{nonce}), found (#{received})"
+        end
+      end
+
+      def leeway(params)
+        (params[:leeway] || params["leeway"] || 60).to_i
+      end
+
+      def token_head(jwt)
+        parts = jwt.to_s.split(".")
+        raise TokenValidationError, "ID token could not be decoded" if parts.length != 3
+
+        JSON.parse(Base64.urlsafe_decode64(parts[0]))
+      rescue ArgumentError, JSON::ParserError => e
+        raise TokenValidationError, "ID token could not be decoded: #{e.message}"
+      end
+
+      # Returns a proc usable as JWT's +jwks+ option. Fetches the JWKS from the
+      # organization's endpoint (once) and refetches when the verification
+      # machinery reports a `kid` missing from the cached key set (rotated
+      # signing keys).
+      def jwks_loader
+        lambda do |options|
+          options ||= {}
+          refetch = options[:invalidate] || options[:kid_not_found]
+          { keys: fetch_keys(force: refetch) }
+        end
+      end
+
+      def fetch_keys(force: false)
+        @jwks = parse_jwks(fetch_jwks_response) if force || !@jwks
+        @jwks
+      end
+
+      def fetch_jwks_response
+        Net::HTTP.start(@jwks_uri.host, @jwks_uri.port,
+                        use_ssl: @jwks_uri.scheme == "https") do |http|
+          request = Net::HTTP::Get.new(@jwks_uri.request_uri)
+          request["accept"] = "application/json"
+          http.request(request)
+        end
+      rescue *NETWORK_ERRORS => e
+        raise TokenValidationError,
+              "Could not fetch the Authify JWKS from #{@jwks_uri}: #{e.message}"
+      end
+
+      def parse_jwks(response)
+        unless response.is_a?(Net::HTTPSuccess)
+          raise TokenValidationError,
+                "Could not fetch the Authify JWKS from #{@jwks_uri}: HTTP #{response.code}"
+        end
+
+        parsed = JSON.parse(response.body, symbolize_names: true)
+        parsed[:keys] || []
+      rescue JSON::ParserError => e
+        raise TokenValidationError,
+              "Could not parse the Authify JWKS from #{@jwks_uri}: #{e.message}"
+      end
+    end
+  end
+end

data/lib/omniauth/authify/version.rb

@@ -0,0 +1,7 @@
+# frozen_string_literal: true
+
+module OmniAuth
+  module Authify
+    VERSION = "0.1.1"
+  end
+end

data/lib/omniauth/authify.rb

@@ -0,0 +1,18 @@
+# frozen_string_literal: true
+
+# Root namespace for the OmniAuth framework. Third-party strategies such as
+# this gem attach under {OmniAuth::Strategies} and may carry helper classes
+# in their own namespace (here: {OmniAuth::Authify}).
+module OmniAuth
+  # OmniAuth strategy support for [Authify](https://github.com/authify/authify),
+  # a self-hosted, multi-tenant identity provider implementing OpenID Connect.
+  #
+  # See {OmniAuth::Strategies::Authify} for the strategy itself.
+  module Authify
+    autoload :ConfigurationError, "omniauth/authify/errors"
+    autoload :TokenValidationError, "omniauth/authify/errors"
+    autoload :JwtValidator, "omniauth/authify/jwt_validator"
+  end
+end
+
+require "omniauth/strategies/authify"

data/lib/omniauth/strategies/authify.rb

@@ -0,0 +1,287 @@
+# frozen_string_literal: true
+
+require "securerandom"
+require "omniauth-oauth2"
+require "omniauth/authify/errors"
+require "omniauth/authify/jwt_validator"
+
+module OmniAuth
+  # Namespace for all OmniAuth strategies (core and third-party)
+  module Strategies
+    # OmniAuth strategy for Authify, a self-hosted, multi-tenant identity
+    # provider implementing OpenID Connect on top of OAuth 2.0.
+    #
+    # Since Authify is multi-tenant, both the server base URL and the
+    # organization slug are required; all endpoints (authorize, token,
+    # userinfo and JWKS) are scoped to the organization.
+    #
+    # @example Rails/Devise usage
+    #   provider :authify,
+    #            ENV["AUTHIFY_CLIENT_ID"],
+    #            ENV["AUTHIFY_CLIENT_SECRET"],
+    #            site: "https://authify.example.com",
+    #            organization: "my-org"
+    #
+    # @example Sinatra usage
+    #   use OmniAuth::Builder do
+    #     provider :authify, ENV["AUTHIFY_CLIENT_ID"], ENV["AUTHIFY_CLIENT_SECRET"],
+    #              site: "https://authify.example.com", organization: "my-org"
+    #   end
+    class Authify < OmniAuth::Strategies::OAuth2
+      # Scopes requested when the user does not configure any
+      DEFAULT_SCOPE = "openid profile email"
+
+      option :name, "authify"
+
+      args %i[client_id client_secret site organization]
+
+      option :client_id, nil
+      option :client_secret, nil
+      option :site, nil
+      option :organization, nil
+
+      # Set to +false+ to skip ID token signature/claim verification and rely
+      # solely on the userinfo endpoint (not recommended).
+      option :verify_id_token, true
+
+      # Leeway (in seconds) allowed when validating time-based claims.
+      option :leeway, 60
+
+      # Set to +false+ to disable PKCE (S256). PKCE is enabled by default.
+      option :pkce, true
+
+      # Scopes to request from Authify; "openid" is required for an ID token.
+      option :scope, DEFAULT_SCOPE
+
+      option :client_options, {
+        site: nil,
+        authorize_url: nil,
+        token_url: nil
+      }
+
+      # Configure the underlying OAuth2 client URLs for the organization.
+      def client
+        validate_configuration!
+
+        base = org_base
+        options.client_options.site = base
+        options.client_options.authorize_url = "#{base}/oauth/authorize"
+        options.client_options.token_url = "#{base}/oauth/token"
+
+        super
+      end
+
+      uid { raw_info["sub"] }
+
+      info do
+        {
+          name: raw_info["name"],
+          email: raw_info["email"],
+          image: raw_info["picture"],
+          nickname: raw_info["preferred_username"],
+          first_name: raw_info["given_name"],
+          last_name: raw_info["family_name"],
+          location: raw_info["zoneinfo"],
+          phone: raw_info["phone_number"],
+          urls: raw_info["website"] ? { website: raw_info["website"] } : {}
+        }
+      end
+
+      credentials do
+        creds = {
+          "token" => access_token.token,
+          "expires" => access_token.expires?
+        }
+        creds["expires_at"] = access_token.expires_at if access_token.expires?
+        creds["refresh_token"] = access_token.refresh_token if access_token.refresh_token
+        creds["id_token"] = id_token if id_token
+
+        # Full ID token verification: signature (via JWKS), issuer, audience,
+        # times, and the per-login nonce. Raises TokenValidationError on
+        # failure, surfacing as an OmniAuth failure via callback_phase.
+        if options.verify_id_token
+          if id_token.nil?
+            raise ::OmniAuth::Authify::TokenValidationError,
+                  "ID token is required but missing"
+          end
+
+          @verified_claims = jwt_validator.verify(id_token, stored_authorize_params)
+        end
+
+        creds
+      end
+
+      extra do
+        extras = { raw_info: raw_info }
+        extras[:id_info] = @verified_claims if @verified_claims
+        extras
+      end
+
+      # Builds authorize parameters; generates and stores a nonce for this
+      # login so the returned ID token can be bound to the request.
+      #
+      # An OIDC +prompt+ parameter on the request phase (e.g. "consent",
+      # "login", "none") is forwarded to Authify.
+      def authorize_params
+        params = super
+        params[:nonce] = SecureRandom.hex(16)
+        params[:leeway] = options.leeway if options.leeway
+        params[:prompt] = request.params["prompt"] if request.params.key?("prompt")
+
+        store_authorize_params(params)
+
+        params
+      end
+
+      # Initiates the authorization redirect after validating configuration.
+      #
+      # @return [Array] a Rack redirect response to Authify's authorize
+      #   endpoint, or an OmniAuth failure when misconfigured
+      def request_phase
+        if missing_configuration?
+          fail!(:missing_configuration, CallbackError.new(
+                                          :missing_configuration,
+                                          "The :site and :organization options are required"
+                                        ))
+        else
+          super
+        end
+      end
+
+      # Completes the login: exchanges the code for tokens (via the
+      # OmniAuth::Strategies::OAuth2 machinery), verifies the ID token while
+      # building the credentials hash, and translates any validation failure
+      # into an OmniAuth `invalid_credentials` failure.
+      #
+      # The OAuth2 state check is performed here first because the parent
+      # class's `secure_compare` raises NoMethodError (on nil) rather than
+      # failing cleanly when the callback carries a state param but no state
+      # exists in the session (stale or replayed callbacks). The parent's own
+      # check is skipped for this invocation because ours is equivalent (the
+      # same constant-time comparison) minus the crash.
+      def callback_phase
+        return state_failure unless callback_state_matches?
+
+        begin
+          base_ignores_state = options.provider_ignores_state
+          options.provider_ignores_state = true
+          super
+        ensure
+          options.provider_ignores_state = base_ignores_state
+        end
+      rescue ::OmniAuth::Authify::TokenValidationError, ::OAuth2::Error, CallbackError => e
+        fail!(:invalid_credentials, e)
+      rescue Timeout::Error, Errno::ETIMEDOUT, ::OAuth2::TimeoutError,
+             ::OAuth2::ConnectionError => e
+        fail!(:timeout, e)
+      rescue SocketError => e
+        fail!(:failed_to_connect, e)
+      end
+
+      private
+
+      # Constant-time comparison of the callback's state parameter against
+      # the state stored in the session at the start of the flow. Returns
+      # +true+ for blank values when +provider_ignores_state+ is set.
+      def callback_state_matches?
+        return true if options.provider_ignores_state
+
+        callback_state = request.params["state"].to_s
+        session_state = session.delete("omniauth.state").to_s
+        return false if callback_state.empty? || session_state.empty?
+
+        constant_time_equal?(callback_state, session_state)
+      end
+
+      # Constant-time comparison of two strings; returns false for blank or
+      # differently-sized inputs.
+      def constant_time_equal?(string_a, string_b)
+        return false unless string_a.bytesize == string_b.bytesize
+
+        l = string_a.unpack("C#{string_a.bytesize}")
+
+        res = 0
+        string_b.each_byte { |byte| res |= byte ^ l.shift }
+        res.zero?
+      end
+
+      def state_failure
+        fail!(:csrf_detected, CallbackError.new(:csrf_detected, "CSRF detected"))
+      end
+
+      # Persists per-login parameters (nonce, leeway) in the session so they
+      # can be checked against the ID token at the callback.
+      def store_authorize_params(params)
+        stored = { nonce: params[:nonce] }
+        stored[:leeway] = params[:leeway] if params[:leeway]
+        stored[:max_age] = params[:max_age] if params[:max_age]
+        session["omniauth.authify.authorize_params"] = stored
+      end
+
+      def stored_authorize_params
+        @stored_authorize_params ||=
+          (session.delete("omniauth.authify.authorize_params") || {}).transform_keys(&:to_sym)
+      end
+
+      def missing_configuration?
+        [options.site, options.organization].any? { |value| value.nil? || value.to_s.strip.empty? }
+      end
+
+      def id_token
+        return @id_token if defined?(@id_token)
+
+        @id_token = normalized_id_token
+      end
+
+      def jwt_validator
+        @jwt_validator ||= ::OmniAuth::Authify::JwtValidator.new(
+          client_id: options.client_id,
+          issuer: normalized_base,
+          jwks_uri: "#{normalized_base}/.well-known/jwks"
+        )
+      end
+
+      def org_base
+        "#{options.site.to_s.strip.sub(%r{/+\z}, "")}/#{options.organization.to_s.strip}"
+      end
+
+      def validate_configuration!
+        return unless missing_configuration?
+
+        raise ::OmniAuth::Authify::ConfigurationError,
+              "Authify strategy requires both :site and :organization options"
+      end
+
+      def normalized_base
+        org_base
+      end
+
+      def normalized_id_token
+        value = access_token&.params&.[]("id_token") ||
+                access_token&.[]("id_token") ||
+                access_token&.[](:id_token)
+        value.to_s.empty? ? nil : value
+      end
+
+      # Identity claims for the auth hash. Prefers (signature-verified) ID
+      # token claims and falls back to the userinfo endpoint.
+      def raw_info
+        return @raw_info if @raw_info
+
+        @raw_info = if options.verify_id_token && id_token
+                      jwt_validator.decode(id_token).first
+                    else
+                      access_token.get(userinfo_url, headers: {
+                                         "accept" => "application/json"
+                                       }).parsed || {}
+                    end
+      end
+
+      def userinfo_url
+        "#{normalized_base}/oauth/userinfo"
+      end
+    end
+  end
+end
+
+OmniAuth.config.add_camelization "authify", "Authify"

data/lib/omniauth-authify.rb

@@ -0,0 +1,3 @@
+# frozen_string_literal: true
+
+require "omniauth/authify"

data/release-please-config.json

@@ -0,0 +1,15 @@
+{
+  "packages": {
+    ".": {
+      "package-name": "omniauth-authify",
+      "changelog-path": "CHANGELOG.md",
+      "release-type": "ruby",
+      "bump-minor-pre-major": true,
+      "bump-patch-for-minor-pre-major": true,
+      "draft": false,
+      "prerelease": false,
+      "version-file": "lib/omniauth/authify/version.rb"
+    }
+  },
+  "$schema": "https://raw.githubusercontent.com/googleapis/release-please/main/schemas/config.json"
+}

data/sig/omniauth/authify.rbs

@@ -0,0 +1,86 @@
+module OmniAuth
+  module Authify
+    # The gem's current version
+    VERSION: String
+
+    # Raised for configuration errors within the strategy itself
+    class ConfigurationError < StandardError
+      def initialize: (String message) -> void
+
+      def message: () -> String
+    end
+
+    # Raised when an Authify-issued ID token (or the signing keys used to
+    # verify it) cannot be validated
+    class TokenValidationError < StandardError
+      def initialize: (String message) -> void
+
+      def message: () -> String
+    end
+
+    # Validates OpenID Connect ID tokens issued by Authify
+    class JwtValidator
+      # ID token signature algorithms this validator accepts
+      SUPPORTED_ALGORITHMS: Array[String]
+      # Claims that must be present in every ID token
+      REQUIRED_CLAIMS: Array[String]
+      # Network failures that map to a TokenValidationError during JWKS fetches
+      NETWORK_ERRORS: Array[singleton(StandardError)]
+
+      # Creates a validator
+      #
+      # - client_id: the OAuth2 client ID (expected `aud` value)
+      # - issuer: the expected value of the ID token `iss` claim
+      # - jwks_uri: the organization's JWKS endpoint URL
+      def initialize: (client_id: String, issuer: String, jwks_uri: String) -> void
+
+      # Decodes an ID token and verifies its signature and claims
+      #
+      # - jwt: the ID token
+      # - authorize_params: per-login parameters stored at the start of the
+      #   flow; may contain +nonce+, +leeway+, +max_age+ and +issuer+
+      #   (string or symbol keys)
+      #
+      # Returns the verified claims
+      # Raises TokenValidationError when the token cannot be verified
+      def verify: (?Hash[Symbol | String, untyped] authorize_params) -> Hash[String, untyped]
+
+      # Decodes an ID token, verifying its signature but skipping claim
+      # checks
+      #
+      # - jwt: the ID token
+      #
+      # Returns a tuple of the claims and the JOSE header
+      # Raises TokenValidationError when the signature cannot be verified
+      def decode: () -> [Hash[String, untyped], Hash[String, untyped]]
+
+      private
+
+      def verify_iss: (Hash[String, untyped] claims, Hash[Symbol | String, untyped] params) -> void
+
+      def verify_sub: (Hash[String, untyped] claims) -> void
+
+      def verify_aud: (Hash[String, untyped] claims) -> void
+
+      def verify_expiration: (Hash[String, untyped] claims, Hash[Symbol | String, untyped] params) -> void
+
+      def verify_iat: (Hash[String, untyped] claims, Hash[Symbol | String, untyped] params) -> void
+
+      def verify_auth_time: (Hash[String, untyped] claims, Hash[Symbol | String, untyped] params) -> void
+
+      def verify_nonce: (Hash[String, untyped] claims, Hash[Symbol | String, untyped] params) -> void
+
+      def leeway: (Hash[Symbol | String, untyped] params) -> Integer
+
+      def token_head: (String? jwt) -> Hash[String, untyped]
+
+      def jwks_loader: () -> ^(?Hash[Symbol, untyped]) -> Hash[Symbol, Array[Hash[Symbol, untyped]]]
+
+      def fetch_keys: (?force: bool) -> Array[Hash[Symbol, untyped]]
+
+      def fetch_jwks_response: () -> (Net::HTTPSuccess | Net::HTTPResponse)
+
+      def parse_jwks: ((Net::HTTPSuccess | Net::HTTPResponse) response) -> Array[Hash[Symbol, untyped]]
+    end
+  end
+end