/passwordless_auth

A library for simple passwordless authentication

Primary LanguageElixirApache License 2.0Apache-2.0

PasswordlessAuth

PasswordlessAuth provides functionality that can be used in an authentication or verification system, such as a passwordless or multi-factor authentication flow, or for verifying a user's ownership of a phone number, email address or any other identifying address.

  • Generate verification codes
  • Verify a user's attempt at entering a code
  • Rate limit attempts
  • Expire codes

This library doesn't deal with sending the codes to recipients.

See Usage for example usage.

Documentation

Documentation is available at https://hexdocs.pm/passwordless_auth

Installation

Add :passwordless_auth to your list of dependencies in mix.exs:

def deps do
  [
    {:passwordless_auth, "~> 0.3.0"}
  ]
end

Configuration

The following PasswordlessAuth config can be set in your config/config.exs file:

config :passwordless_auth,
  # How long codes are valid for
  verification_code_ttl: 300, # seconds; default: 300
  # Rate limiting: how many failed attempts are allowed before the timeout is applied
  num_attempts_before_timeout: 5, # default: 5
  # Rate limiting: how long to disallow attempts after the limit has been reached
  rate_limit_timeout_length: 60, # seconds; default: 60
  # How often to clear out expired codes
  garbage_collector_frequency: 30 # seconds; default: 30

Usage

Here's an example where the code is sent to a recipient's phone number using ExTwilio.

1. Generate a verification code for the recipient

User enters their phone number to request a verification code.

code = PasswordlessAuth.generate_code("+447123456789")
=> "123456"

2. Send the code to the recipient

This library doesn't deal with SMS or emails, so this bit is up to you.

ExTwilio.Message.create(%{
  to: "+447123456789",
  body: "Your code is #{code}"
})

3. Verify the code

Recipient receives a text message with their verification code. They enter it into your system and you verify that it is correct.

attempt_code = "123456" # The user's attempt at entering the correct verification code.
PasswordlessAuth.verify_code(
  "+447123456789",
  attempt_code
)

Returns true or false.

Once a code has been verified, you can remove it so that it can't be used again before it expires.

PasswordlessAuth.remove_code("+447123456789")