Oasis.Token behaviour (oasis v0.4.0) View Source

A simple wrapper of Plug.Crypto to provide a way to generate and verify bearer token for use in the bearer security scheme of the OpenAPI Specification.

When we use sign/2 and verify/2, the data stored in the token is signed to prevent tampering but not encrypted, in this scenario, we can store identification information (such as user NON-PII data), but SHOULD NOT be used to store confidential information (such as credit card numbers, PIN code).

  • "NON-PII" means Non Personally Identifiable Information.

If you don't want clients to be able to determine the value of the token, you may use encrypt/2 and decrypt/2 to generate and verify the token.

Callback

There are two callback functions reserved for use in the generated modules when we use the bearer security scheme of the OpenAPI Specification.

  • crypto_config/2, provides a way to define the crypto-related key information for the high level useage, it required to return an Oasis.Token.Crypto struct.
  • verify/3, an optional function to provide a way to custom the verification of the token, you may want to use encrypt/decrypt to the token, or other more rules to verify it.

Link to this section Summary

Functions

A wrapper of Plug.Crypto.decrypt/4 to use Oasis.Token.Crypto to decrypt the original data from the token and verify its integrity, please see Plug.Crypto.decrypt/4 for details.

A wrapper of Plug.Crypto.encrypt/4 to use Oasis.Token.Crypto to encode, encrypt and sign data into a token you can send to clients, please see Plug.Crypto.encrypt/4 for details.

Generates a random string in N length via :crypto.strong_rand_bytes/1.

A wrapper of Plug.Crypto.sign/4 to use Oasis.Token.Crypto to sign data into a token you can send to clients, please see Plug.Crypto.sign/4 for details.

A wrapper of Plug.Crypto.verify/4 to use Oasis.Token.Crypto to decode the original data from the token and verify its integrity, please see Plug.Crypto.verify/4 for details.

Callbacks

Avoid using the application enviroment as the configuration mechanism for this library, and make crypto-related key information configurable when use bearer authentication.

An optional callback function to decode the original data from the token, and verify its integrity.

Link to this section Types

Specs

opts() :: Plug.opts()

Specs

verify_error() :: {:error, :expired} | {:error, :invalid}

Link to this section Functions

A wrapper of Plug.Crypto.decrypt/4 to use Oasis.Token.Crypto to decrypt the original data from the token and verify its integrity, please see Plug.Crypto.decrypt/4 for details.

Specs

encrypt(crypto :: Oasis.Token.Crypto.t(), data :: term()) :: String.t()

A wrapper of Plug.Crypto.encrypt/4 to use Oasis.Token.Crypto to encode, encrypt and sign data into a token you can send to clients, please see Plug.Crypto.encrypt/4 for details.

Specs

random_string(length :: non_neg_integer()) :: String.t()

Generates a random string in N length via :crypto.strong_rand_bytes/1.

Specs

sign(crypto :: Oasis.Token.Crypto.t(), data :: term()) :: String.t()

A wrapper of Plug.Crypto.sign/4 to use Oasis.Token.Crypto to sign data into a token you can send to clients, please see Plug.Crypto.sign/4 for details.

Specs

verify(crypto :: Oasis.Token.Crypto.t(), token :: String.t()) ::
  {:ok, term()} | {:error, term()}

A wrapper of Plug.Crypto.verify/4 to use Oasis.Token.Crypto to decode the original data from the token and verify its integrity, please see Plug.Crypto.verify/4 for details.

Link to this section Callbacks

Link to this callback

crypto_config(conn, opts)

View Source

Specs

crypto_config(conn :: Plug.Conn.t(), opts :: Keyword.t()) ::
  Oasis.Token.Crypto.t()

Avoid using the application enviroment as the configuration mechanism for this library, and make crypto-related key information configurable when use bearer authentication.

The Oasis.Plug.BearerAuth module invokes this callback function to fetch a predefined Oasis.Token.Crypto struct, and then use it to verify the bearer token of the request.

Link to this callback

verify(conn, token, opts)

View Source (optional)

Specs

verify(conn :: Plug.Conn.t(), token :: String.t(), opts()) ::
  {:ok, term()} | verify_error()

An optional callback function to decode the original data from the token, and verify its integrity.

If we use sign/2 to create a token, sign it, then provide it to a client application, the client will then use this token to authenticate requests for resources from the server, in this scenario, as a common use case, the Oasis.Plug.BearerAuth module uses verify/2 to finish the verification of the bearer token, so we do not need to implement this callback function in general.

But if we use encrypt/2 or other encryption methods to encode, encrypt, and sign data into a token and send to clients, we need to implement this callback function to custom the way to decrypt the token and verify its integrity.