View Source Oasis.Token behaviour (oasis v0.5.1)
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
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 usage, it required to return anOasis.Token.Cryptostruct.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
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.
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.
Link to this section Types
@type opts() :: Plug.opts()
@type verify_error() :: {:error, :expired} | {:error, :invalid}
Link to this section Callbacks
@callback 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.
@callback 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.
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.
@spec 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.
@spec random_string(length :: non_neg_integer()) :: String.t()
Generates a random string in N length via :crypto.strong_rand_bytes/1.
@spec 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.
@spec 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.