Functionality for providing Bearer HTTP authentication.

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

example

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 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 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