A Guardian Pipeline is a composable way to manage authentication using Plug. It provides two primary components to the Plug.Conn struct, making them available to all downstream plugs:

1. Implementation Module: Your custom Guardian module.
2. Error Handler: A module responsible for handling unauthenticated requests.

By injecting these into the conn struct at the start of a plug chain, you can easily swap them out downstream for different parts of your application (e.g., switching from a JSON error handler to an HTML error handler).

Guardian is an Elixir authentication toolkit providing token-based authentication. It focuses on two core responsibilities:

1. Creating Tokens
2. Verifying Tokens

Note that Guardian does not handle the initial 'challenge phase' (the first verification of a user/resource). You should use a methodology like Ueberauth to handle the initial authentication before using Guardian for token management.

Guardian uses tokens as the currency for authentication credentials. A valid token must be:

1. Tamper proof: It must be signed or encrypted such that it is verifiable by your application.
2. Payload-bearing: It must include claims, which should be a map using string keys.

By default, Guardian uses JWT tokens (JSON Web Tokens), which are widely supported and can use either hashed or certificate-based signing algorithms. However, you can implement other behaviors such as revocation, database tracking, or different token standards.

To use Guardian with Plugs in 1.0, you must define a pipeline module using Guardian.Plug.Pipeline. This pipeline handles implementation selection, error handling, and the plug sequence.

defmodule MyApp.Guardian.AuthPipeline do
  @claims %{typ: "access"}

  use Guardian.Plug.Pipeline, otp_app: :my_app,
                              module: MyApp.Guardian,
                              error_handler: MyApp.Guardian.AuthErrorHandler

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

Guardian uses an adapter pattern. You can implement the Guardian.Token behaviour to create a custom backend. You specify this backend using the token_module option, either directly in the use statement or via your application's configuration.

# Option 1: Specify token_module in the use call
```elixir
defmodule MyApp.TokenModuleCustom do
  use Guardian, otp_app: :my_app,
      token_module: MyApp.CustomTokenBackend

  # ...
end

Option 2: Specify token_module via Mix configuration

defmodule MyApp.TokenModuleCustom do
  use Guardian, otp_app: :my_app

  # ...
end

use Mix.Config

config :my_app, MyApp.TokenModuleCustom,
  token_module: MyApp.CustomTokenBackend

Because the pipeline configuration is injected into the conn struct, you can override the error_handler at any point downstream in your plug chain by calling Guardian.Plug.Pipeline again with a different error_handler option.

  pipeline :auth do
    plug AuthMe.UserManager.Pipeline
  end

  pipeline :auth_html_errors do
    plug Guardian.Plug.Pipeline, error_handler: AuthMe.UserManager.ErrorHandlers.HTML
  end

  pipeline :auth_json_errors do
    plug Guardian.Plug.Pipeline, error_handler: AuthMe.UserManager.ErrorHandlers.JSON
  end

  scope "/api" do
    pipe_through [:auth, :auth_json_errors]
    # ...
  end

  scope "/www" do
    pipe_through [:auth, :auth_html_errors]
    # ...
  end