simple_auth-magic_link

simple_auth-magic_link

Passwordless authentication for simple_auth.

Installation

gem install simple_auth-magic_link

Or add the following line to your project's Gemfile:

gem "simple_auth-magic_link"

Usage

First, you need to copy the migration files and apply the migrations to your database.

$ rails simple_auth_magic_link_engine:install:migrations
$ rails db:migrate

You can configure the magic link's ttl, code generator and default purpose by setting these options directly to SimpleAuth::MagicLink:

SimpleAuth::MagicLink.tap do |magic_link|
  # Optional. By default 6 random numbers.
  magic_link.code = > { Array.new(6) { SecureRandom.random_number(0..9) }.join }

  # Optional. By default, links expires 3 minutes from now.
  magic_link.ttl = 1.minute

  # Optional. By default, uses "default".
  magic_link.purpose = :default

  # Required. The lambda that will be used to generate the magic link.
  # This will require the default url options like in
  # `Rails.application.routes.default_url_options = {host: "example.com"}`
  magic_link.url = -> { verify_email_url }

  # Required. The keyring that will be used to encrypt the user's email.
  # Generate the keyring secret and digest salt with the following command:
  # dd if=/dev/urandom bs=32 count=1 2>/dev/null | openssl base64 -A
  keyring = {"1" => "<32 bytes>"}
  magic_link.attr_keyring keyring, digest_salt: "<32 bytes>"
end

Then, you can create magic links by using magic_link = SimpleAuth::MagicLink.create!(options), where options can be:

• email: required. The email tied to this magic link.
• purpose: optional. A string that identifies the purpose of the magic link. Defaults to default. You can use this to discern links that will be used for other purposes (e.g. confirm an action, login, signup, etc).
• expires_at: optional. The code's expiration time. Defaults to three minutes from now.
• code: optional. The code that tied to this magic link. Defaults to haikunate.

After you create a link, you can send it by email by using magic_link.url.

[!IMPORTANT]

Save magic_link.id on the session. This id will be used later on to ensure that the link was generated on the same browser/device.

To verify the magic link, you can use email = SimpleAuth::MagicLink.verify(url: request.original_url, id: session[:magic_link_id], **options), where options can be:

• purpose: required. The purpose of the code being verified.

If the url is valid (i.e. it hasn't been tempered and it hasn't expired), then you'll get the email tied to the token back. Otherwise, you'll get nil.

[!INFO]

Verified magic links are automatically removed upon verification.

You can also verify the magic link by using just the code (maybe you sent this by SMS instead). In this case, you need to call something like email = SimpleAuth::MagicLink.verify_code(code:, id: session[:magic_link_id], **options). It expects the same options as SimpleAuth::MagicLink.verify.

To remove expires links, use SimpleAuth::MagicLink.clean!.

Notice that this plugin doesn't implement any mailers, so you'll need to handle that yourself. For example, a complete flow for a login/signup process would be something like this:

1. User fills in log-in form with email address
2. You call magic_link = SimpleAuth::MagicLink.create!(email: params[:email])
3. You persist the magic link id with session[:magic_link_id] = magic_link.id
4. You then pass this in to your mailer with something like Mailer.login(magic_link).send_later
5. On your mailer, you can then have access to the user email via magic_link.email, the code via magic_link.code and the signed url via magic_link.url.

Maintainer

• [e-mail]

Contributors

• https://github.com/fnando/simple_auth-magic_link/contributors

Contributing

For more details about how to contribute, please read https://github.com/fnando/simple_auth-magic_link/blob/main/CONTRIBUTING.md.

License

The gem is available as open source under the terms of the MIT License. A copy of the license can be found at https://github.com/fnando/simple_auth-magic_link/blob/main/LICENSE.md.

Code of Conduct

Everyone interacting in the simple_auth-magic_link project's codebases, issue trackers, chat rooms and mailing lists is expected to follow the code of conduct.