Helps to build plug pipelines for use with Guardian and associated plugs.

All Guardian provided plugs have a number of features.

1. They take a :key option to know where to store information in the session and connection
2. They require a reference to the implementation (the module that use Guardian)
3. They require a reference to an error handling module

These references are passed through the connection so they must be put in place before the Guardian Plugs. By using a pipeline this is taken care of for you.

The easiest way to use Guardian.Plug.Pipeline is to create a module that defines your pipeline.

defmodule MyApp.AuthPipeline do
use Guardian.Plug.Pipeline, otp_app: :my_app,
module: MyApp.Tokens,
error_handler: MyApp.AuthErrorHandler

@claims %{iss: "IssuerApp"}

plug Guardian.Plug.VerifySession, claims: @claims
plug Guardian.Plug.VerifyHeader, claims: @claims, scheme: "Bearer"
plug Guardian.Plug.EnsureAuthenticated
plug Guardian.Plug.LoadResource, allow_blank: true
end

When you want to use the pipeline you just use it like a normal plug.

plug MyApp.AuthPipeline

This pipeline will look for tokens in either the session (it's ok if it's not loaded) followed by the header if one wasn't found in the session.

We then ensure that we found a token and fail if not.

Given that we found a token, we then attempt to load the resource the token refers to, failing if one is not found.

customizing-your-pipeline

Customizing your pipeline

Once you've created a pipeline, you can customize it when you call it with options.

plug MyApp.AuthPipeline, module: MyApp.ADifferentGuardianModule
# OR
plug MyApp.AuthPipeline, key: :impersonate

options

Options

You can provide options to the pipeline when you use Guardian.Plug.Pipeline or you can provide them when you call the plug.

Additionally, for every option other than :otp_app you can use elixir configuration, the use options, or inline options.

• :otp_app - The otp app where the pipeline modules can be found
• :module - The Guardian implementation module
• :error_handler - The error handler module
• :key - The key to use

keys

Keys

Using keys allows you to specify locations in the session/connection where the tokens and resources will be placed. This allows multiple authenticated tokens to be in play for a single request. This is useful for impersonation or higher security areas where you can have a specific set of privileges and still be logged in.

error-handler

Error handler

When using plugs, you'll need to specify an error handler module

See Guardian.Plug.ErrorHandler documentation for more details.

inline-pipelines

Inline pipelines

If you want to define your pipeline inline, you can do so by using Guardian.Plug.Pipeline as a plug itself.

You must supply the module and error handler inline if you do this.

plug Guardian.Plug.Pipeline, module: MyApp.Tokens,
error_handler: MyApp.AuthErrorHandler
plug Guardian.VerifyHeader, scheme: "Bearer"

Inline pipelines are also good to change the error handler that you want to use.

Note that you must set the pipeline before using other guardian plugs.

# Use the MyApp.AuthErrorHandler for downstream Guardian plugs
plug Guardian.Plug.Pipeline, module: MyApp.Tokens,
error_handler: MyApp.AuthErrorHandler
plug Guardian.VerifyHeader, scheme: "Bearer"

# Now change out the error handler for plugs downstream of this one.
plug Guardian.Plug.Pipeline, error_handler: MyApp.SpecialAuthErrorHandler