Failures

When a failure occurs when authenticating a response in Warden, a rack endpoint is called. This Rack endpoint is referred to as the failure app.

When you add the middleware to the stack, you need to provide it with a rack endpoint to be called when there is a failure with the authentication.

Failing Authentication

To fail authentication simply throw a :warden symbol. You can throw it as a bare symbol, or with a hash.

# Bails out to the failure application:
throw(:warden)

# Bails out to the failure application and places
# the options hash in env['warden.options']:
throw(:warden, :some => :option) 

This can be thrown in any downstream middleware or endpoint.

When a failure occurs and :warden is thrown, here’s what happens:

1. The lazy auth object is checked for redirects, custom rack responses etc. If there is a failure, or nothing has occurred, the failure app is called.
2. env['PATH_INFO'] is re-written to "/unauthenticated".
3. Any options passed to the throw are included at env['warden.options'].
4. Any before_failure Callbacks are called.
5. The failure application is called.

If you want to change the action that is called on the failure app, simply pass the throw option an :action symbol. You can do this a couple of ways:

throw(:warden, :action => "different_action")

# or when authenticating
env['warden'].authenticate! :action => "different_action"

You can setup warden to throw to a different failure action per scope. See Setup for details.