https://github.com/hopsoft/key_store
A simple api-key storage engine
https://github.com/hopsoft/key_store
Last synced: 6 months ago
JSON representation
A simple api-key storage engine
- Host: GitHub
- URL: https://github.com/hopsoft/key_store
- Owner: hopsoft
- License: mit
- Created: 2014-02-05T05:43:26.000Z (over 11 years ago)
- Default Branch: master
- Last Pushed: 2014-03-13T17:47:23.000Z (over 11 years ago)
- Last Synced: 2025-03-10T08:04:37.674Z (7 months ago)
- Language: Ruby
- Homepage:
- Size: 262 KB
- Stars: 0
- Watchers: 2
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- License: LICENSE.txt
Awesome Lists containing this project
README
# A simple api-key storage engine
[](https://travis-ci.org/hopsoft/key_store)
[](https://gemnasium.com/hopsoft/key_store)
[](https://codeclimate.com/github/hopsoft/key_store)Easily create & store api-keys to help secure your API.
* Simple
* Does 1 thing well
* Accepts custom key values
* Works with any framework
* Human friendly storage*KeyStore leverages a threadsafe [YAML::Store](http://ruby-doc.org/stdlib-2.1.0/libdoc/yaml/rdoc/YAML/Store.html)
backend for simple api-key management.***Note:** Best for smaller projects.
You should look elsewhere if you're managing more than a few hundred api-keys.## Usage
### Install
```sh
gem install key_store
```### Configure the storage location
```ruby
require "key_store"
KeyStore.set_file_path "/path/to/keys.yml"
```### Create an api-key
```ruby
key = KeyStore::Key.new("2de1c1c7aefee1f811a20dfdfa30597e")
# note: the key name can be any custom string value
```### Save an api-key
```ruby
key = KeyStore::key.new("2de1c1c7aefee1f811a20dfdfa30597e")
key.save!
```### Delete an api-key
```ruby
KeyStore.delete!("2de1c1c7aefee1f811a20dfdfa30597e")
```### See if an api-key exists
```ruby
KeyStore.exists?("2de1c1c7aefee1f811a20dfdfa30597e")
```### Find an api-key
```ruby
key = KeyStore.find("2de1c1c7aefee1f811a20dfdfa30597e")
```### Save an api-key with roles
```ruby
key = KeyStore::Key.new("2de1c1c7aefee1f811a20dfdfa30597e", roles: ["read", "write"])
key.roles << "admin"
key.save!
# note: roles are arbitrary... define as many as your app needs
```### Save an api-key with notes
```ruby
key = KeyStore::Key.new("2de1c1c7aefee1f811a20dfdfa30597e",
roles: ["read", "write"],
notes: "This key is for testing only."
)
key.notes += " One more thing..."
key.save!
```### Inspect an api-key's name
```ruby
key = KeyStore::Key.new("2de1c1c7aefee1f811a20dfdfa30597e")
key.name # => "2de1c1c7aefee1f811a20dfdfa30597e"
```### Inspect an api-key's HTTP header
```ruby
key = KeyStore::Key.new("2de1c1c7aefee1f811a20dfdfa30597e")
key.http_header # => "Authorization: Token token=\"2de1c1c7aefee1f811a20dfdfa30597e\""
```### Inspect an api-key's roles
```ruby
key = KeyStore::Key.new("2de1c1c7aefee1f811a20dfdfa30597e", roles: ["read", "write"])
key.roles # => ["read", "write"]
```### Review the YAML file
Keys are stored in a human friendly YAML file and can be manually edited.
*The location of this file is configurable. [See above](#configure-the-storage-location)*
```yaml
# /path/to/keys.yml
---
2de1c1c7aefee1f811a20dfdfa30597e:
:roles:
- read
- write
:notes: This key is for testing only. One more thing...
:http_header: 'Authorization: Token token="2de1c1c7aefee1f811a20dfdfa30597e"'
```## Example Rails Integration
First, ensure that any desired api-keys exist in the YAML file.
Then add the dependency to the Gemfile.```ruby
# Gemfile
gem "key_store"
```Next, use an initializer to configure the api-keys file location.
```ruby
# config/initializers/key_store.rb
KeyStore.set_file_path File.join(Rails.root, "db/keys.yml")# optionally ensure a test api-key exists
if Rails.env == "development"
test_key = KeyStore::Key.new("test-key",
roles: [:test],
notes: "This key is for testing only."
)
test_key.save!
end
```Finally, add authentication to your controllers.
```ruby
#app/controller/users_controller.rb
require "key_store"class UsersController < ActionController::Base
before_filter :verify_key_store
def show
# logic here ...
endprotected
def verify_key_store
# note: consumers should pass the api-key in the "Authorization" HTTP header
authenticate_or_request_with_http_token do |token, options|
# use the @api_key with your favorite authorization library
# cancan for example
@api_key = KeyStore.find(token)
end
endend
```**Note**: This authentication strategy is basic & should be secured with [TLS/SSL](http://en.wikipedia.org/wiki/Transport_Layer_Security).
Learn more about the capabilities built into Rails that can be used to secure an API at
[Rails Casts](http://railscasts.com/episodes/352-securing-an-api?view=asciicast).