Secure download link for recovery codes

[janko]

In my upcoming screencast about multifactor authentication, I'm planning to show how to build a link for downloading recovery codes, which I often saw in other apps next to the actual recovery codes.

My initial version just featured a download endpoint, which called rodauth.require_authentication, and rendered the recovery codes. However, I realized this decreased the security, because it made it possible to retrieve recovery codes without entering the password.

r.get "/recovery-codes-download" do
  rodauth.require_authentication

  response.headers["Content-Disposition"] = "attachment; filename=myapp-recovery-codes.txt"
  rodauth.recovery_codes.join("\n")
end

My next version was to build the download link in plain JavaScript, passing it the recovery codes at render time. Given that this download link was only displayed alongside rendered recovery codes, it seemed to maintain the same level of security.

<!-- add_recovery_codes.erb -->
<!-- ... -->
<%= link_to "download", "#", data: {
  controller: "download",
  action: "download#perform",
  download_content_value: rodauth.recovery_codes.join("\n"),
  download_filename_value: "myapp-recovery-codes.txt",
} %>

// download_controller.js
import { Controller } from '@hotwired/stimulus'

export default class extends Controller {
  static values = { content: String, filename: String }

  perform(event) {
    event.preventDefault()

    const content = new Blob([this.contentValue])
    const contentURL = URL.createObjectURL(content)

    this.download(contentURL)
  }

  download(url) {
    const downloadLink = document.createElement('a')
    downloadLink.href = url
    downloadLink.setAttribute('download', this.filenameValue)

    document.body.appendChild(downloadLink)
    downloadLink.click()
    document.body.removeChild(downloadLink)
  }
}

However, I was thinking whether there is a JS-free way of keeping both security and UX. Initially I was thinking of making the download button a POST form where the user has to enter their password. However, given that they already entered the password to view the recovery codes, that would harm UX.

I then thought about using password_grace_period and only displaying the password if it hasn't recently been entered. However, then I would have to handle the scenario of the user keeping the recovery codes page open until the password grace period expires, and only then clicking at the download link, which didn't seem trivial.

The most recent idea I had yesterday was to combine password_grace_period with confirm_password, so that the user is redirected to the password confirmation page if the password grace period expires. However, in that case, the recovery codes download would start while they were still on the password confirmation page, which I didn't consider good UX.

r.get "/recovery-codes-download" do
  rodauth.require_authentication
  rodauth.require_password_authentication # <=====

  response.headers["Content-Disposition"] = "attachment; filename=myapp-recovery-codes.txt"
  rodauth.recovery_codes.join("\n")
end

I was wondering what are your thoughts on that?

[jeremyevans]

First, I'm not sure it's a good idea to offer a generic download feature for recovery codes. It does make it easier on the user, but it's less likely the user will put thought into how the recovery codes should be stored.

I think there is an easier solution. You could add a form on the page where you can view the recovery codes, which will submit the recovery codes to the server, and the server can just take the submitted data and return it as an attachment. That avoids the freshness issue, and there are no security concerns, because the server is only returning the input in a new format. What are your thoughts on that?

[janko]

Thanks for the help, your solution indeed sounds simpler. When I was about to try it out, I remembered that HTML anchor tags also support data URLs for href, and download for forcing the download, which together would eliminate the need for an additional endpoint. So, this is what I ended up with:

<a href="data:,<%= rodauth.recovery_codes.join("\n") %>" download="myapp-recovery-codes.txt">download</a>

First, I'm not sure it's a good idea to offer a generic download feature for recovery codes. It does make it easier on the user, but it's less likely the user will put thought into how the recovery codes should be stored.

Yeah, if you mean that the recovery codes might just stay on disk after download, instead of the user moving them to a safer location (such as 1Password), then I agree. It's just the level of convenience that I was used to when setting up MFA for other apps like Heroku and GitHub (at least that's how I recall it), so I wanted to show that possibility in the screencast.

[jeremyevans]

For the screencast, might be worth overriding add_recovery_codes_view, calling super, and appending that a tag, to show that all parts of Rodauth are easily overridable.

[janko]

I will be showing a custom recovery codes page, where recovery codes are displayed in two columns – the same that I described in this article. I do try to keep view changes in the ERB templates, as that's how it's easiest to modify and maintain.

I like showing Rodauth's flexibility in terms of changing behaviour. So far, I have the following planned:

• treating MFA as part of login (the user is always redirected to MFA, and without any flash message)
• remembering users after MFA and considering remembered users multifactor-authenticated (like GitHub)
• returning to originally requested location
• auto-adding recovery codes and displaying them after OTP setup (together with a download link)
• SMS codes via Twilio

[jeremyevans]

Sounds good. I would advise against using SMS, or if you are going to cover it, add a disclaimer that it is probably a bad idea, and should only be considered if WebAuthn or TOTP is not considered a viable option.

In regards to the multiple columns, is the CSS column-count property not sufficient for switching to a multi-column display?

[janko]

Thanks for the warning. I do intend to show SMS only as a backup MFA method once TOTP is setup, but I'll be sure to add that disclaimer, as I also heard that SMS is not secure enough. I will mention WebAuthn, and plan to cover it in a dedicated episode, as I feel like it's big enough topic for that.

In regards to the multiple columns, is the CSS column-count property not sufficient for switching to a multi-column display?

You're right, it is:

But I also wanted to make it look a bit nicer, which I can do with some Bootstrap classes and markup:

  <div class="d-inline-block mb-3 border border-primary rounded px-3 py-2">
    <% rodauth.recovery_codes.each_slice(2) do |code1, code2| %>
      <div class="row text-primary text-left">
        <div class="col-lg my-1 font-monospace"><%= code1 %></div>
        <div class="col-lg my-1 font-monospace"><%= code2 %></div>
      </div>
    <% end %>
  </div>

I could probably achieve a similar result with custom CSS, but I like it when I can change how something looks solely in the HTML, so I will usually prefer that solution over the one where I have to write CSS 🙂