Identification Failures in Grape with Bearer Tokens

Identification failures occur when an API fails to properly establish who is making a request. In Grape, this commonly happens when Bearer token authentication is set up but token validation, scope checks, or binding to a user identity are incomplete or misconfigured. Grape allows you to define authentication logic using helpers and before filters, but if these do not consistently reject requests with missing, malformed, or untrusted tokens, the endpoint may treat unauthenticated or weakly authenticated requests as authenticated.

Specifically, a Grape API might expose an identification failure with Bearer tokens in several ways: accepting tokens without verifying their signature or issuer; failing to map a valid token to an internal user or role; not enforcing token scopes or claims that restrict access to certain resources; or allowing a token intended for one resource to be reused across multiple endpoints. These gaps mean the API incorrectly identifies the requester as a legitimate user when they are not, which enables BOLA/IDOR and privilege escalation paths. Even if the API requires a token, missing validation of token metadata (such as audience, expiration, or revoked status) can lead to authentication bypass in practice.

Consider a Grape endpoint that uses a before filter to require authentication but does not validate the token beyond checking presence:

class API < Grape::API
  format :json

  helpers do
    def current_user
      @current_user ||= User.find_by(token: params[:token]) # weak: no validation
    end

    def authenticate!
      error!('Unauthorized', 401) unless current_user
    end
  end

  before { authenticate! }

  resource :reports do
    get ':id' do
      report = Report.find(params[:id])
      report.as_json
    end
  end
end

In this example, the token is read from request parameters rather than from the Authorization header, and there is no verification of token validity, scope, or revocation. An attacker who knows or guesses a valid token—or who intercepts a token—can access reports they should not see. This is an identification failure because the API incorrectly identifies the caller as the associated user based solely on a raw token value without cryptographic validation or proper binding.

Another common pattern is using a token helper without checking scopes or claims:

class API < Grape::API
  format :json

  helpers do
    def authenticate!
      token = request.env['HTTP_AUTHORIZATION']&.split(' ')&.last
      return unless token
      decoded = decode_token(token) # returns payload or nil
      @current_user = decoded && User.find_by(sub: decoded['sub'])
      error!('Forbidden', 403) unless @current_user&.active?
    end

    def decode_token(token)
      # simplified: real code should validate signature, issuer, audience, exp, nbf
      begin
        JWT.decode(token, nil, false).first
      rescue JWT::DecodeError
        nil
      end
    end
  end

  before { authenticate! }

  resource :admin do
    get :dashboard do
      { message: 'Admin area' }
    end
  end
end

Here, the token is decoded without signature verification (JWT decode with false for verification), and scope or role claims are not enforced. This allows any bearer token to be accepted as long as the format is plausible, leading to identification failures where unauthorized users are identified as admins. Proper identification requires validating the token signature, verifying claims like issuer and audience, and ensuring the token is not expired or revoked.

To fix identification failures with Bearer tokens in Grape, validate the token cryptographically, bind it to a user identity, and enforce scopes or roles required for the endpoint. Always extract the token from the Authorization header, verify its signature and claims, and map it to a trusted user record before granting access.

Below are concrete, secure examples you can apply in a Grape API.

1) Validate Bearer token signature and claims, and map to user:

class API < Grape::API
  format :json

  helpers do
    def current_user
      @current_user ||= begin
        auth = request.env['HTTP_AUTHORIZATION']
        return nil unless auth&.start_with?('Bearer ')
        token = auth.split(' ').last
        payload = decode_and_validate_token(token)
        payload && User.find_by(sub: payload['sub'])
      end
    end

    def decode_and_validate_token(token)
      # Use your actual key and algorithm; this uses jwt gem with HS256
      key = ENV['JWT_SECRET_KEY']
      options = {
        algorithm: 'HS256',
        iss: 'myapi.example.com',
        verify_expiration: true,
        verify_iat: true,
        verify_jti: true
      }
      decoded = JWT.decode(token, key, true, options)
      # decoded is an array; take the first payload hash
      decoded.first
    rescue JWT::ExpiredSignature, JWT::VerificationError, JWT::DecodeError
      nil
    end

    def authenticate!
      error!('Unauthorized', 401) unless current_user
    end

    def require_scope!(required_scope)
      auth = request.env['HTTP_AUTHORIZATION']&.split(' ')&.last
      return unless auth&.start_with?('Bearer ')
      token = auth.split(' ').last
      payload = decode_and_validate_token(token)
      return unless payload
      scopes = Array(payload['scope'])
      error!('Insufficient scope', 403) unless scopes.include?(required_scope)
    end
  end

  before { authenticate! }

  resource :reports do
    get ':id' do
      require_scope!('read:reports')
      report = Report.find(params[:id])
      report.as_json
    end
  end
end

This example extracts the Bearer token from the Authorization header, validates the signature using a secret (or public key for RS256), checks standard claims such as expiration (exp), issued at (iat), and a custom JWT ID (jti) to help detect revocation, and maps the subject (sub) to a user. It also shows scope enforcement via a custom helper, preventing privilege escalation by ensuring the token includes the required scope.

2) Centralize authentication logic in a base Grape::API class to avoid inconsistencies:

class BaseAPI < Grape::API
  format :json

  helpers do
    def current_user
      @current_user ||= verify_bearer_user
    end

    def verify_bearer_user
      auth = request.env['HTTP_AUTHORIZATION']
      return nil unless auth&.match?(/\ABeer\s+\S+\z/)
      token = auth.split(' ').last
      payload = verify_jwt(token)
      payload && User.find_by(sub: payload['sub'])
    end

    def verify_jwt(token)
      key = ENV['JWT_SECRET_KEY']
      JWT.decode(token, key, true, {
        algorithm: 'HS256',
        iss: 'myapi.example.com',
        verify_expiration: true
      })
    rescue JWT::ExpiredSignature, JWT::VerificationError
      nil
    end

    def authenticate!
      error!('Unauthorized', 401) unless current_user
    end
  end

  before { authenticate! }
end

class PublicAPI < BaseAPI
  # endpoints that do not require authentication can skip before filters
end

class ProtectedAPI < BaseAPI
  resource :admin do
    get :dashboard do
      { message: 'Admin dashboard' }
    end
  end
end

By centralizing token extraction, signature validation, and user mapping in a base class, you reduce the risk of inconsistent handling across endpoints and ensure identification is based on verified tokens. For production, rotate your secret keys, use asymmetric signing (RS256) with a public key for verification, and implement token revocation checks (e.g., via a denylist or short-lived tokens with refresh workflows).