ExFTP.Authenticator behaviour (ExFTP v1.2.0)

View Source

A behaviour defining an Authenticator.

Authenticators are used by the FTP interface to verify login credentials.

👀 See Also

📖 Resources

Summary

Types

authenticator_state()

State held onto by the server and modified by the Authenticator.

password()

The string value of the security challenge.

username()

A string representing a user (e.g "jsmith")

Callbacks

authenticated?(authenticator_state)

Given the current state, whether this session is still considered authenticated

login(password, authenticator_state)

Request a login given a security challenge value.

valid_user?(username)

Whether a given username is valid.

Types

authenticator_state()

@type authenticator_state() :: %{}

State held onto by the server and modified by the Authenticator.

It may be used by the authenticator to keep stateful values.

⚠️ Reminders

Special Keys

  • authenticated: true will exist if the current user has successfully called login/2 during this session (and the Authenticator hasn't otherwise removed it)
  • username: username/0 will exist if the current session has defined the user (but hasn't necessarily supplied a password)

👀 See Also

📖 Resources

password()

@type password() :: String.t()

The string value of the security challenge.

⚠️ Reminders

What is a password, really?

A password could be used in the traditional sense; but this could also be a OTP, a hash, or any string value that the user would use to authenticate

👀 See Also

📖 Resources

username()

@type username() :: String.t()

A string representing a user (e.g "jsmith")

👀 See Also

📖 Resources

Callbacks

authenticated?(authenticator_state)

@callback authenticated?(authenticator_state()) :: boolean()

Given the current state, whether this session is still considered authenticated

🏷️ Params

⤵️ Returns

✅ On Success

  `true` or `false`

💻 Examples

iex> alias ExFTP.Auth.PassthroughAuth
iex> PassthroughAuth.authenticated?(%{authenticated: true})
true
iex> PassthroughAuth.authenticated?(%{})
false

⚠️ Reminders

Authenticator State

The authenticator_state/0 will contain authenticated: true if login has succeeded before in this session.

Authenticators may choose to drop that key for their own use cases (e.g if a TTL expires)

📖 Resources

login(password, authenticator_state)

@callback login(password(), authenticator_state()) ::
  {:ok, authenticator_state()} | {:error, term()}

Request a login given a security challenge value.

🏷️ Params

⤵️ Returns

✅ On Success

  {:ok, authenticator_state}

❌ On Failure

  {:error, bad_login}

💻 Examples

iex> alias ExFTP.Auth.PassthroughAuth
iex> {:ok, _auth_state} = PassthroughAuth.login("password", %{username: "jsmith"})
iex> {:error, _} = PassthroughAuth.login("password", %{})
iex> # "root" is a disallowed user in PassthroughAuth
iex> {:error, _} = PassthroughAuth.login("password", %{username: "root"})

⚠️ Reminders

Authenticator State

The authenticator_state/0 will contain a :username key, if one was provided.

On success, the authenticator_state will be automatically updated to include authenticated: true. See authenticated?/1 for more information.

📖 Resources

valid_user?(username)

@callback valid_user?(username()) :: boolean()

Whether a given username is valid.

🏷️ Params

⤵️ Returns

✅ On Success

  `true` or `false`

💻 Examples

iex> alias ExFTP.Auth.PassthroughAuth
iex> PassthroughAuth.valid_user?("jsmith")
true
iex> PassthroughAuth.valid_user?("root")
false

⚠️ Reminders

🔒 Security

The client will never be informed that a username is invalid.

The server uses this method to short-circuit auth calls.

📖 Resources