View Source Charon.AuthChallenge behaviour (Charon v0.0.4-alpha)

Behaviour for an authentication challenge module.

Link to this section Summary

Types

t()

A module that implements this behaviour.

Callbacks

Complete the challenge. This callback must validate the client's response to the challenge. Passing the challenge means passing the auth flow's stage.

Initiate the challenge. This callback can be used to issue the challenge, in response to the user picking it, for example by sending a code by email. This callback may optionally verify that the user has enabled the challenge.

Returns the challenge's name. Should be unique.

Complete the challenge's setup. This callback should enable the challenge for the user, when applicable.

Initiate the challenge's setup. This callback should at least generate a setup token to complete the challenge setup. Additionally, it can be used to generate an initial challenge (for example to verify that the user has successfully set up an OTP app).

Functions

Check a user's current password.

Generate a token that can be used to complete the setup of an auth challenge.

Validate a token to complete the setup of an auth challenge.

Verify that the user has enabled the challenge.

Link to this section Types

@type t() :: module()

A module that implements this behaviour.

Link to this section Callbacks

Link to this callback

challenge_complete( conn, params, user, config )

View Source
@callback challenge_complete(
  conn :: Plug.Conn.t(),
  params :: map(),
  user :: map() | struct(),
  config :: Charon.Config.t()
) :: {:ok, Plug.Conn.t(), nil | map()} | {:error, String.t()} | {:error, map()}

Complete the challenge. This callback must validate the client's response to the challenge. Passing the challenge means passing the auth flow's stage.

Returns:

  • {:ok, maybe-updated-conn, maybe-response-for-client}
  • {:error, message}
  • {:error, map} (update-user-callback-error)
Link to this callback

challenge_init( conn, params, user, config )

View Source
@callback challenge_init(
  conn :: Plug.Conn.t(),
  params :: map(),
  user :: map() | struct(),
  config :: Charon.Config.t()
) :: {:ok, Plug.Conn.t(), nil | map()} | {:error, String.t()} | {:error, map()}

Initiate the challenge. This callback can be used to issue the challenge, in response to the user picking it, for example by sending a code by email. This callback may optionally verify that the user has enabled the challenge.

Returns:

  • {:ok, maybe-updated-conn, maybe-response-for-client}
  • {:error, message}
  • {:error, map} (update-user-callback-error)
@callback name() :: String.t()

Returns the challenge's name. Should be unique.

Link to this callback

setup_complete( conn, params, user, config )

View Source
@callback setup_complete(
  conn :: Plug.Conn.t(),
  params :: map(),
  user :: map() | struct(),
  config :: Charon.Config.t()
) :: {:ok, Plug.Conn.t(), nil | map()} | {:error, String.t()} | {:error, map()}

Complete the challenge's setup. This callback should enable the challenge for the user, when applicable.

Returns:

  • {:ok, maybe-updated-conn, maybe-response-for-client}
  • {:error, message}
  • {:error, map} (update-user-callback-error)
Link to this callback

setup_init( conn, params, user, config )

View Source
@callback setup_init(
  conn :: Plug.Conn.t(),
  params :: map(),
  user :: map() | struct(),
  config :: Charon.Config.t()
) :: {:ok, Plug.Conn.t(), nil | map()} | {:error, String.t()} | {:error, map()}

Initiate the challenge's setup. This callback should at least generate a setup token to complete the challenge setup. Additionally, it can be used to generate an initial challenge (for example to verify that the user has successfully set up an OTP app).

Returns:

  • {:ok, maybe-updated-conn, maybe-response-for-client}
  • {:error, message}
  • {:error, map} (update-user-callback-error)

Link to this section Functions

Link to this function

check_current_password(user, params, config)

View Source
@spec check_current_password(map() | struct(), map(), Charon.Config.t()) ::
  :ok | {:error, String.t()}

Check a user's current password.

Link to this function

gen_setup_token(challenge_name, config, extra_payload \\ %{})

View Source
@spec gen_setup_token(String.t(), Charon.Config.t(), map()) :: String.t()

Generate a token that can be used to complete the setup of an auth challenge.

Link to this function

validate_setup_token(challenge_name, params, config)

View Source
@spec validate_setup_token(String.t(), map(), Charon.Config.t()) ::
  {:error, String.t()} | {:ok, map()}

Validate a token to complete the setup of an auth challenge.

Link to this function

verify_enabled(user, challenge_name, config)

View Source
@spec verify_enabled(map() | struct(), String.t(), Charon.Config.t()) ::
  :ok | {:error, String.t()}

Verify that the user has enabled the challenge.