# `Oasis.Plug.BearerAuth`
[🔗](https://github.com/xinz/oasis/blob/main/lib/oasis/plug/bearer_auth.ex#L1)

Functionality for providing Bearer HTTP authentication.

It is recommended to only use this module in production if SSL is enabled and enforced.

## Example

As any other Plug, we can use the `bearer_auth/2` plug:

    # lib/pre_handler.ex
    import Oasis.Plug.BearerAuth

    plug :bearer_auth,
      security: Oasis.Gen.BearerAuth
      key_to_assigns: :user_id

    # lib/oasis/gen/bearer_auth.ex
    defmodule Oasis.Gen.BearerAuth do
      @behaviour Oasis.Token

      @impl true
      def crypto_config(_conn, _options) do
        # return a `Oasis.Token.Crypto` struct in your preferred way
        %Oasis.Token.Crypto{
          secret_key_base: "...",
          salt: "...",
          max_age: 7200
        }
      end
    end

Or directly plug `Oasis.Plug.BearerAuth`:

    # lib/pre_handler.ex

    plug(
      Oasis.Plug.BearerAuth,
      security: Oasis.Gen.BearerAuth,
      key_to_assigns: :user_id
    )

    # lib/oasis/gen/bearer_auth.ex
    defmodule Oasis.Gen.BearerAuth do
      @behaviour Oasis.Token

      @impl true
      def crypto_config(_conn, _options) do
        # ...
      end
    end

We define the [bearer security scheme](https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.1.0.md#securitySchemeObject)
of the OpenAPI specification in our API design document, and then generate the related module and provide the requried configuration,
let's take some examples from YAML specifications.

Here we apply a global security to all operation objects:

    openapi: 3.1.0

    components:
      securitySchemes:
        bearerAuth: # arbitrary name for the security scheme
          type: http
          scheme: bearer
          bearerFormat: JWT

    security:
      - bearerAuth: []

Here we apply a security to a operation object, and define an optional specification extension `"x-oasis-key-to-assigns"` field
to the `:key_to_assigns` option of `bearer_auth/2`:

    openapi: 3.1.0

    components:
      securitySchemes:
        bearerAuth: # arbitrary name for the security scheme
          type: http
          scheme: bearer
          bearerFormat: JWT
          x-oasis-key-to-assigns: user_id

    paths:
      /something:
        get:
          security:
            - bearerAuth: []

The above arbitrary name `"bearerAuth"` for the security scheme will be transferred into a generated module (see the above mentioned "Oasis.Gen.BearerAuth"
module) to provide the required crypto-related configuration, and use it as the value to the `:security` option of `bearer_auth/2`.

By default, the generated "BearerAuth" module will inherit the module name space in order from the paths object, and then the operation object if they defined
the `"x-oasis-name-space"` field, or defaults to `Oasis.Gen` if there are no any specification defined. As an option, we can add an `"x-oasis-name-space"`
field as a specification extension of the security scheme object to override the module name space, meanwhile, the optional `--name-space` argument to the
`mix oas.gen.plug` command line is in the highest priority to set the name space of the generated modules.

    components:
      securitySchemes:
        bearerAuth: # arbitrary name for the security scheme
          type: http
          scheme: bearer
          bearerFormat: JWT
          x-oasis-key-to-assigns: user_id
          x-oasis-name-space: MyAuth

In the above example, the final generated module name of `"bearerAuth"` is `MyAuth.BearerAuth` when there is no `--name-space` argument of mix task input.

After we define the bearer authentication into the specification, then run `mix oas.gen.plug` task with this spec file (via `--file` argument), there will
generate the above similar code to the related module file as long as it does not exist, it also follows the name space definition
of that module, and the generation does not override it once the file existed, we need to further edit this file to provide a crypto-related
configuration in your preferred way.

If we need a customization to verify the bearer token, we can implement a callback function `c:Oasis.Token.verify/3` to this scenario.

    # lib/bearer_auth.ex
    defmodule BearerAuth do
      @behaviour Oasis.Token

      @impl true
      def crypto_config(conn, options) do
        %Oasis.Token.Crypto{
          ...
        }
      end

      @impl true
      def verify(conn, token, options) do
        # write your rules to verify the token,
        # and return the expected results in:
        #   {:ok, data}, verified
        #   {:error, "expired"}, expired token
        #   {:error, "invalid"}, invalid token
      end
    end

# `bearer_auth`

High-level usage of Baerer HTTP authentication.

See the module docs for examples.

## Options

  * `:security`, required, a module be with `Oasis.Token` behaviour.
  * `:key_to_assigns`, optional, after the verification of the token, the original data
    will be stored into the `conn.assigns` once this option defined, for example, if set
    it as `:user_id`, we can access the verified data via `conn.assigns.user_id` in the
    next plug pipeline.

# `parse_bearer_auth`

Parses the request token from Bearer HTTP authentication.

It returns either `{:ok, token}` or `{:error, "invalid_request"}`.

# `request_bearer_auth`

Requests bearer authentication from the client.

It sets the response to status 401 with "Unauthorized" as body.
The response is not sent though (nor the connection is halted),
allowing developers to further customize it.

A response example:

    HTTP/1.1 401 Unauthorized
    www-authenticate: Bearer realm="Application",
                      error="invalid_token",
                      error_description="the access token expired"

## Options

  * `:realm` - the authentication realm. The value is not fully
    sanitized, so do not accept user input as the realm and use
    strings with only alphanumeric characters and space.
  * `:error` - an optional tuple to represent `"error"` and `"error_description"`
    attributes, for example, `{"invalid_token", "the access token expired"}`

---

*Consult [api-reference.md](api-reference.md) for complete listing*