Devise::Sssecrets - Sssecrets For Devise's Friendly Token Generator

Purpose

Sssecrets is a handy gem for generating secure tokens that are easy for static analysis tools to identify. It works great as a standalone tool, but there are cases where developers may want to integrate it with authentication frameworks like Devise.

This gem provides a module to use sssecrets with Devise as a drop-in replacement for the framework's built-in friendly token generator. By introducing the use of sssecrets for token generation and enabling the configuration of token prefixes and organizations, developers can generate secure and unique tokens with consistent, configurable, identifiable prefixes to suit various use cases.

To learn more about the sssecrets gem and the case for using structured secrets in your application, check out the Sssecrets repository.

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.

Prefix Configuration

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

Sssecrets allows you to provide two abbreviated strings, org and type, which together make up the token prefix. Generally, org would be used to specify an overarching identifier (like your company or app), while type is intended to identify the token type (i.e., OAuth tokens, refresh tokens, etc) in some way. To maintain a compact and consistent format for Sssecret tokens, org and type together should not exceed 10 characters in length.

The overridden Devise#friendly_token implementation has been extended to accept two optional parameters:

• prefix_type: Specifies the type of the token prefix. If not provided, it defaults to :default.

• org: Specifies the organization for the friendly token. If not provided, the default organization is used.

Note: the original implementation's length parameter is now ignored.

How to Use

Before you begin, add devise-sssecrets to your gemfile and install it.

1. Open your Devise initializer file at config/initializers/devise.rb.

2. Use the Devise.setup block to configure your token organization and types.

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

3. Call Devise#friendly_token with your desired parameters to generate friendly tokens based on the configured sssecrets prefixes and organization.

Example

# Generate a friendly token with the default org 'dv' and default type of 'ft'
token_with_default_prefix = Devise.friendly_token
"dvft_3MU5bK5MChmzOmxCsQIhb7CEXgdcPj3tNmF9"

# Generate a friendly token with the 'org' of 'test' and type of 'user'
token_with_user_prefix = Devise.friendly_token(org: "test", prefix_type: :user)
"testusr_cFl9hMJTxPRxpnHBmiUNgKizhilscT4RfLk2"

# Generate a friendly token with the default 'org' and type of 'admin'
token_with_admin_prefix = Devise.friendly_token(prefix_type: :admin)
"dvadm_2Srrwf5IWVubTHmqBTVmvAraHgeCYO11ezUh"

Tests

Tests are included in this repository:

bundle exec rspec spec/devise/sssecrets_spec.rb

Development

After checking out the repo, run bin/setup to install dependencies. Then, run rake spec to run the tests. You can also run bin/console for an interactive prompt that will allow you to experiment.

To install this gem onto your local machine, run bundle exec rake install. To release a new version, update the version number in version.rb, and then run bundle exec rake release, which will create a git tag for the version, push git commits and the created tag, and push the .gem file to rubygems.org.

Contributing

Bug reports and pull requests are welcome on GitHub at https://github.com/chtzvt/devise-sssecrets.

License

The gem is available as open source under the terms of the MIT License.