Update friendly_token to issue Structured Secrets

[chtzvt]

Hey folks,

I'd like to propose an update to the current implementation of Devise#friendly_token to use Structured Secrets. I've put together a demo, but would like to collect feedback on this from the Devise team and its users before opening a pull request to propose changes to the core library.

Sssecrets is a reusable implementation of GitHub's API token format (which is also used by NPM), and it's designed to make it simple for developers to issue secure secret tokens that are easy to detect when leaked.

Token prefixes are a simple and effective method to make tokens identifiable. Slack, Stripe, GitHub, and others have adopted this approach to great effect.

You can learn more about GitHub's design process and the properties of this API token format on the GitHub blog.

Background

Why Structured Secrets?

If you're a developer and your application issues some kind of access tokens (API keys, PATs, etc), it's important to format these in a way that both identifies the string as a secret token and provides insight into its permissions.

Simple Structured Secrets help solve this problem: They're a compact format with properties that are optimized for detection with static analysis tools. That makes it possible to automatically detect when secrets are leaked in a codebase using features like GitHub Secret Scanning or GitLab Secret Detection.

Here's an example. HashiCorp Vault's API access tokens look like this (ref):

f3b09679-3001-009d-2b80-9c306ab81aa6

You might think that this is pretty is a pretty easy pattern to search for, but here's the issue: It's just a UUID string.

While random, strings in this format are used in many places for non-sensitive purposes. Meaning that, given a random UUID formatted string, it's impossible to know whether it's a sensitive API credential or a garden-variety identifier for something mundane. In cases like these, secret scanning can't help much.

What's in a Structured Secret?

Structured secrets have three parts:

• A prefix (2-10 characters, defined by you)
• 30 characters of randomness
• A 6 character checksum

That's it!

Here's the format:

[prefix]_[randomness][checksum]

An example Sssecret, with an org of t and a type of k, looks like this:

tk_GNrRoBa1p9nuwm7XrWkrhYUNQ7edOw4GUp8I

Current behavior

Currently, Devise uses the following format for friendly tokens:

irb(main):001:0> Devise.friendly_token
=> "eaeTJwV3ZvEweRVnZYyE"

Expected behavior

With this new implementation, Devise generates friendly tokens using the Structured Secret format:

irb(main):001:0> Devise.friendly_token
=> "dvft_6VBhR4ODS2fygr0KzXvwpvXj6ILunQQMBbR0"

irb(main):003:0> Devise.friendly_token(org: "demo", type: :admin)
=> "demoadm_6dSZp4nWvgWaM6mEHYwXmrxRksPkOd2AdqDX"

These prefixes are configurable in the Devise.setup block, like so:

Devise.setup do |config|
  config.friendly_token_org = 'dv' # Set your sssecret token organization. Defaults to "dv".
  config.friendly_token_types[:default] = 'ft' # Add your sssecret token types like so. Default is "ft".
  config.friendly_token_types[:user] = 'usr'
  config.friendly_token_types[:admin] = 'adm'

  # Any other Devise configuration...
end

Demo

I've put together a demo showing how to integrate Sssecrets with Devise in the following repository:

https://github.com/chtzvt/sssecrets-devise

The core of the demo implementation can be found in the project's Devise initializer.

I'd like to collect feedback on this proposal from the Devise team, along with users of Devise, before opening a pull request to propose changes to Devise core.

[mvz]

Is this issue still relevant now that the devise-sssecrets gem exists?

[chtzvt]

@mvz Potentially. This issue was intended as a proposal to suggest improvements to the current friendly_token implementation. Devise-sssecrets was meant to serve partly as a first-draft reference implementation, and also as a way to bring structured secrets to existing projects using Devise.