keycloak_rack 1.0.0

data/lib/keycloak_rack/authenticate.rb

@@ -0,0 +1,115 @@
+# frozen_string_literal: true
+
+module KeycloakRack
+  # The core service that handles authenticating a request from Keycloak.
+  #
+  # @example
+  #  class ApplicationController < ActionController::API
+  #    before_action :authenticate_user!
+  #
+  #    # @return [void]
+  #    def authenticate_user!
+  #      # KeycloakRack::Session#authenticate! implements a Dry::Matcher::ResultMatcher
+  #      request.env["keycloak:session"].authenticate! do |m|
+  #        m.success(:authenticated) do |_, token|
+  #          # this is the case when a user is successfully authenticated
+  #
+  #          # token will be a KeycloakRack::DecodedToken instance, a
+  #          # hash-like PORO that maps a number of values from the
+  #          # decoded JWT that can be used to find or upsert a user
+  #
+  #          attrs = decoded_token.slice(:keycloak_id, :email, :email_verified, :realm_access, :resource_access)
+  #
+  #          result = User.upsert attrs, returning: %i[id], unique_by: %i[keycloak_id]
+  #
+  #          @current_user = User.find result.first["id"]
+  #        end
+  #
+  #        m.success do
+  #          # When allow_anonymous is true, or
+  #          # a URI is skipped because of skip_paths, this
+  #          # case will be reached. Requests from here on
+  #          # out should be considered anonymous and treated
+  #          # accordingly
+  #
+  #          @current_user = AnonymousUser.new
+  #        end
+  #
+  #        m.failure do |code, reason|
+  #          # All authentication failures are reached here,
+  #          # assuming halt_on_auth_failure is set to false
+  #          # This allows the application to decide how it
+  #          # wants to respond
+  #
+  #          render json: { errors: [{ message: "Auth Failure" }] }, status: :forbidden
+  #        end
+  #      end
+  #    end
+  #  end
+  class Authenticate
+    include Dry::Monads[:do, :result]
+
+    include Import[
+      config: "keycloak-rack.config",
+      key_resolver: "keycloak-rack.key_resolver",
+      read_token: "keycloak-rack.read_token",
+      skip_authentication: "keycloak-rack.skip_authentication"
+    ]
+
+    delegate :token_leeway, to: :config
+
+    # @param [Hash] env the rack environment
+    # @return [Dry::Monads::Success(:authenticated, KeycloakRack::DecodedToken)]
+    # @return [Dry::Monads::Success(:skipped, String)]
+    # @return [Dry::Monads::Success(:unauthenticated)]
+    # @return [Dry::Monads::Failure(:expired, String, String, Exception)]
+    # @return [Dry::Monads::Failure(:decoding_failed, String, String, Exception)]
+    def call(env)
+      return Success[:skipped] if yield skip_authentication.call(env)
+
+      token = yield read_token.call env
+
+      return Success[:unauthenticated] if token.blank?
+
+      decoded_token = yield decode_and_verify token
+
+      Success[:authenticated, decoded_token]
+    end
+
+    private
+
+    # @param [String] token
+    # @return [Dry::Monads::Success(KeycloakRack::DecodedToken)]
+    # @return [Dry::Monads::Failure(:expired, String, String, Exception)]
+    # @return [Dry::Monads::Failure(:decoding_failed, String, String, Exception)]
+    def decode_and_verify(token)
+      jwks = yield key_resolver.find_public_keys
+
+      algorithms = yield algorithms_for jwks
+
+      options = {
+        algorithms: algorithms,
+        leeway: token_leeway,
+        jwks: jwks
+      }
+
+      payload, headers = JWT.decode token, nil, true, options
+    rescue JWT::ExpiredSignature => e
+      Failure[:expired, "JWT is expired", token, e]
+    rescue JWT::DecodeError => e
+      Failure[:decoding_failed, "Failed to decode JWT", token, e]
+    else
+      Success DecodedToken.new payload.merge(original_payload: payload, headers: headers)
+    end
+
+    # @param [{ Symbol => <{ Symbol => String }> }] jwks
+    # @return [<String>]
+    def algorithms_for(jwks)
+      jwks.fetch(:keys, []).map do |k|
+        k[:alg]
+      end.uniq.compact.then do |algs|
+        algs.present? ? Success(algs) : Failure[:no_algorithms, "Could not derive algorithms from JWKS"]
+      end
+    end
+  end
+end

data/lib/keycloak_rack/authorize_realm.rb

@@ -0,0 +1,53 @@
+# frozen_string_literal: true
+
+module KeycloakRack
+  # A service that allows someone to check if the current token has a realm-level role.
+  #
+  # It is instantiated in `keycloak:authorize_realm` after the middleware runs.
+  #
+  # This can greatly simplify access control for rack services (for instance, to gate uploading files outside of Rails).
+  #
+  # @example
+  #   class UploadProcessor
+  #     def initialize(app)
+  #       @app = app
+  #     end
+  #
+  #     def call(env)
+  #       env["keycloak.authorize_realm"].call("upload_permission") do |m|
+  #         m.success do
+  #           # allow the upload to proceed
+  #         end
+  #
+  #         m.failure do
+  #           # fail the response, return 403, etc
+  #         end
+  #       end
+  #     end
+  #   end
+  class AuthorizeRealm
+    extend Dry::Initializer
+
+    include Dry::Monads[:result]
+    include Dry::Matcher.for(:call, with: Dry::Matcher::ResultMatcher)
+
+    param :session, Types.Instance(KeycloakRack::Session)
+
+    # Check to see if the current user session has a certain realm-level role.
+    #
+    # @see KeycloakRack::DecodedToken#has_realm_role?
+    # @param [String] role_name
+    # @return [Dry::Monads::Success(:authorized, String)]
+    # @return [Dry::Monads::Failure(:unauthorized, String)]
+    # @return [Dry::Monads::Failure(:unauthenticated, String)]
+    def call(role_name)
+      if session.has_realm_role?(role_name)
+        Success[:authorized, role_name]
+      elsif session.authenticated?
+        Failure[:unauthorized, "You do not have #{role_name.to_s.inspect} access"]
+      else
+        Failure[:unauthenticated, "You are not authenticated"]
+      end
+    end
+  end
+end

data/lib/keycloak_rack/authorize_resource.rb

@@ -0,0 +1,54 @@
+# frozen_string_literal: true
+
+module KeycloakRack
+  # A service that allows someone to check if the current token has a resource-level role.
+  #
+  # It is instantiated in `keycloak:authorize_resource` after the middleware runs.
+  #
+  # This can greatly simplify access control for rack services (for instance, to gate modifications to a certain type of resource).
+  #
+  # @example
+  #   class WidgetCombobulator
+  #     def initialize(app)
+  #       @app = app
+  #     end
+  #
+  #     def call(env)
+  #       env["keycloak.authorize_resource"].call("widgets", "recombobulate") do |m|
+  #         m.success do
+  #           # allow the user to recombobulate the widget
+  #         end
+  #
+  #         m.failure do
+  #           # return forbidden, log the attempt, etc
+  #         end
+  #       end
+  #     end
+  #   end
+  class AuthorizeResource
+    extend Dry::Initializer
+
+    include Dry::Monads[:result]
+    include Dry::Matcher.for(:call, with: Dry::Matcher::ResultMatcher)
+
+    param :session, Types.Instance(KeycloakRack::Session)
+
+    # Check that the current session has a certain resource role.
+    #
+    # @see KeycloakRack::DecodedToken#has_resource_role?
+    # @param [String] resource_name
+    # @param [String] role_name
+    # @return [Dry::Monads::Success(:authorized, String)]
+    # @return [Dry::Monads::Failure(:unauthorized, String)]
+    # @return [Dry::Monads::Failure(:unauthenticated, String)]
+    def call(resource_name, role_name)
+      if session.has_resource_role?(resource_name, role_name)
+        Success[:authorized, resource_name, role_name]
+      elsif session.authenticated?
+        Failure[:unauthorized, "You do not have #{role_name.to_s.inspect} access on #{resource_name.to_s.inspect}"]
+      else
+        Failure[:unauthenticated, "You are not authenticated"]
+      end
+    end
+  end
+end

data/lib/keycloak_rack/config.rb

@@ -0,0 +1,84 @@
+# frozen_string_literal: true
+
+module KeycloakRack
+  # Configuration model for KeycloakRack.
+  #
+  # Uses [anyway_config](https://github.com/palkan/anyway_config)
+  # to permit flexible approaches to configuration.
+  class Config < Anyway::Config
+    config_name "keycloak"
+
+    env_prefix "KEYCLOAK"
+
+    # @!attribute [rw] server_url
+    #
+    # The URL of your Keycloak installation. Be sure to include `/auth` if necessary.
+    #
+    # @note Required config value
+    # @return [String]
+    attr_config :server_url
+
+    # @!attribute [rw] realm_id
+    #
+    # The ID of the realm used to authenticate requests.
+    #
+    # @note Required config value
+    # @return [String]
+    attr_config :realm_id
+
+    # @!attribute [rw] ca_certificate_file
+    # The optional path to the CA Certificate to validate connections to a keycloak server.
+    # @return [String, nil]
+    attr_config :ca_certificate_file
+
+    # @!attribute [r] skip_paths
+    # @return [{ #to_s => <String, Regexp> }]
+    attr_config skip_paths: {}
+
+    # @!attribute [rw] token_leeway
+    # The number of seconds to allow for tokens to be expired to allow for clock drift.
+    #
+    # @see https://github.com/jwt/ruby-jwt#expiration-time-claim
+    # @return [Integer]
+    attr_config token_leeway: 10
+
+    # @!attribute [rw] cache_ttl
+    # The interval (in seconds) that cached public keys in {KeycloakRack::KeyResolver} should be cached.
+    # @return [Integer]
+    attr_config cache_ttl: 86_400
+
+    # @!attribute [rw] halt_on_auth_failure
+    # @return [Boolean]
+    attr_config halt_on_auth_failure: true
+
+    # @!attribute [rw] allow_anonymous
+    # @return [Boolean]
+    attr_config allow_anonymous: false
+
+    # required :server_url, :realm_id
+
+    def cache_ttl=(value)
+      super Types::Coercible::Integer[value]
+    end
+
+    def skip_paths=(value)
+      super Types::SkipPaths[value]
+    end
+
+    def token_leeway=(value)
+      super Types::Coercible::Integer[value]
+    end
+
+    # @api private
+    # @!visibility private
+    # @return [OpenSSL::X509::Store]
+    def build_x509_store
+      # :nocov:
+      OpenSSL::X509::Store.new.tap do |store|
+        store.set_default_paths
+        store.add_file(ca_certificate_file) if ca_certificate_file.present?
+      end
+      # :nocov:
+    end
+  end
+end

data/lib/keycloak_rack/container.rb

@@ -0,0 +1,53 @@
+# frozen_string_literal: true
+
+module KeycloakRack
+  # Dependency injection container for various `KeycloakRack` objects
+  #
+  # @api private
+  # @!visibility private
+  class Container
+    extend Dry::Container::Mixin
+
+    namespace "keycloak-rack" do
+      register :config do
+        # :nocov:
+        KeycloakRack::Config.new
+        # :nocov:
+      end
+
+      register :authenticate do
+        KeycloakRack::Authenticate.new
+      end
+
+      register :http_client do
+        KeycloakRack::HTTPClient.new
+      end
+
+      register :key_fetcher do
+        KeycloakRack::KeyFetcher.new
+      end
+
+      register :key_resolver, memoize: true do
+        # :nocov:
+        KeycloakRack::KeyResolver.new
+        # :nocov:
+      end
+
+      register :read_token do
+        KeycloakRack::ReadToken.new
+      end
+
+      register :server_url do
+        resolve(:config).server_url
+      end
+
+      register :skip_authentication do
+        KeycloakRack::SkipAuthentication.new
+      end
+
+      register :x509_store do
+        resolve(:config).build_x509_store
+      end
+    end
+  end
+end

data/lib/keycloak_rack/decoded_token.rb

@@ -0,0 +1,191 @@
+# frozen_string_literal: true
+
+module KeycloakRack
+  # PORO that wraps the result of decoding the JWT into something slightly more usable,
+  # with some type-safety and role checking features.
+  class DecodedToken < KeycloakRack::FlexibleStruct
+    # Mapping used to remap keys from a Keycloak JWT payload into something more legible.
+    # @api private
+    KEY_MAP = {
+      "allowed-origins" => :allowed_origins,
+      "auth_time" => :authorized_at,
+      "aud" => :audience,
+      "azp" => :authorized_party,
+      "exp" => :expires_at,
+      "iat" => :issued_at,
+      "typ" => :type,
+    }.with_indifferent_access.freeze
+
+    private_constant :KEY_MAP
+
+    transform_keys do |k|
+      KEY_MAP[k] || k.to_sym
+    end
+
+    # @!attribute [r] sub
+    # The user id / subject for the JWT. Corresponds to `user_id` in Keycloak's rest API,
+    # and suitable for linking your local user records to Keycloak's.
+    # @return [String]
+    attribute :sub, Types::String
+
+    # @!attribute [r] realm_access
+    # @return [KeycloakRack::RoleMap]
+    attribute :realm_access, RoleMap
+
+    # @!attribute [r] resource_access
+    # @return [{ String => KeycloakRack::RoleMap }]
+    attribute :resource_access, ResourceRoleMap
+
+    # @!attribute [r] email_verified
+    # @return [Boolean]
+    attribute? :email_verified, Types::Bool
+
+    # @!attribute [r] name
+    # @return [String, nil]
+    attribute? :name, Types::String.optional
+
+    # @!attribute [r] preferred_username
+    # @return [String, nil]
+    attribute? :preferred_username, Types::String.optional
+
+    # @!attribute [r] given_name
+    # @return [String, nil]
+    attribute? :given_name, Types::String.optional
+
+    # @!attribute [r] family_name
+    # @return [String, nil]
+    attribute? :family_name, Types::String.optional
+
+    # @!attribute [r] email
+    # @return [String, nil]
+    attribute? :email, Types::String.optional
+
+    # @!group Token Details
+
+    # @!attribute [r] expires_at
+    # The `exp` claim
+    # @return [Time]
+    attribute :expires_at, Types::Timestamp
+
+    # @!attribute [r] issued_at
+    # The `iat` claim
+    # @return [Time]
+    attribute :issued_at, Types::Timestamp
+
+    # @!attribute [r] authorized_at
+    # The `auth_time` value from Keycloak.
+    # @return [Time]
+    attribute :authorized_at, Types::Timestamp
+
+    # @!attribute [r] jti
+    # @return [String]
+    attribute :jti, Types::String
+
+    # @!attribute [r] audience
+    # @return [String]
+    attribute :audience, Types::String
+
+    # @!attribute [r] type
+    # The `typ` claim in the JWT. Keycloak sets this to `"JWT"`.
+    # @return [String]
+    attribute :type, Types::String
+
+    # @!attribute [r] authorized_party
+    # The `azp` claim
+    # @return [String]
+    attribute :authorized_party, Types::String
+
+    # @!attribute [r] nonce
+    # Cryptographic nonce for the token
+    # @return [String]
+    attribute :nonce, Types::String
+
+    # @!attribute [r] scope
+    # @return [String]
+    attribute :scope, Types::String
+
+    # @!attribute [r] session_state
+    # @return [String]
+    attribute :session_state, Types::String
+
+    # @!attribute [r] locale
+    # @return [String, nil]
+    attribute? :locale, Types::String.optional
+
+    # @!attribute [r] allowed_origins
+    # @return [<String>]
+    attribute :allowed_origins, Types::StringList
+
+    # @!attribute [r] headers
+    # The JWT headers, provided for debugging
+    # @return [ActiveSupport::HashWithindifferentAccess]
+    attribute? :headers, Types::IndifferentHash
+
+    # @!attribute [r] original_payload
+    # The original JWT payload, unmodified, for extracting potential additional attributes.
+    # @return [ActiveSupport::HashWithIndifferentAccess]
+    attribute? :original_payload, Types::IndifferentHash
+
+    # @!endgroup
+
+    alias keycloak_id sub
+
+    alias first_name given_name
+
+    alias last_name family_name
+
+    ALIASES = %i[keycloak_id first_name last_name].freeze
+
+    private_constant :ALIASES
+
+    delegate :attribute_names, to: :class
+
+    # @param [#to_sym] key
+    # @raise [KeycloakRack::DecodedToken::UnknownAttribute] if it is an unknown attribute
+    # @return [Object]
+    def fetch(key)
+      key = key.to_sym
+
+      if key.in?(attribute_names)
+        self[key]
+      elsif key.in?(ALIASES)
+        public_send(key)
+      elsif key.in?(original_payload)
+        original_payload[key]
+      else
+        raise UnknownAttribute, "Cannot fetch #{key.inspect}"
+      end
+    end
+
+    # Check if the current user has a certain realm role
+    #
+    # @param [#to_s] name
+    def has_realm_role?(name)
+      name.to_s.in? realm_access.roles
+    end
+
+    # Check if the user has a certain role on a certain resource.
+    #
+    # @param [#to_s] resource_name
+    # @param [#to_s] role_name
+    def has_resource_role?(resource_name, role_name)
+      resource_access[resource_name.to_s]&.has_role?(role_name)
+    end
+
+    # Extract keys into something hash-like
+    #
+    # @param [<String, Symbol>] keys
+    # @return [ActiveSupport::HashWithIndifferentAccess]
+    def slice(*keys)
+      keys.flatten!
+
+      keys.each_with_object({}.with_indifferent_access) do |key, h|
+        h[key] = fetch(key)
+      end
+    end
+
+    # An error raised by {KeycloakRack::DecodedToken#fetch} when
+    # trying to fetch something the token doesn't know about
+    class UnknownAttribute < KeyError; end
+  end
+end