token_manager 0.1.0 → 0.1.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: f1d30fc81116b96e15351a9208a870ddeab36d7c0c157b8375afd1d8f3100d47
-  data.tar.gz: 230a7ae244484bba33131dcf3cfed33713d3375b3f7813f1f90f7e30ac16eeee
+  metadata.gz: 0ff4a8194d49805843a8627838efc10e1d10775dec27f077c244469045bd4c07
+  data.tar.gz: 4eadf80e12f17624508f2dd00fb0ceaebcf937d72ed2e269f7f3cecf98b3ee77
 SHA512:
-  metadata.gz: c947a400ec247ff1003eb5c62ebea2464f07fc1077a28bf1329bd68c5c4c3f17c60b32a84cf0270226bed6137515fb944d43d5607339bc8def0eda94b732bf23
-  data.tar.gz: 3a76374f68ea875a88af3f11d9c590999dc50ff572fcd66fdaebb7d0b57ced8f8e0b42e33db70ab9d9bae03376bb5bbc2f84e7310e9ea40592b9bebe84448efd
+  metadata.gz: 1c5aec9184aabf13de9c6030a8903a289bee5a5b0821cf3f716c0c63d15db4026b5413b9a39472fc718e6df284f66d7759ac43c638377055c3d669336be0f49a
+  data.tar.gz: 1dcd35575c52d77b95e4d25b948a4635954d281105faa5f0f5b97c478a476fc1dcd69b0798eaa34eaa3fe408589d826a2a1131ff320c8a226df1964da47f9f93

data/Gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: .
   specs:
-    token_manager (0.1.0)
+    token_manager (0.1.1)
       activesupport
       curb
       jwt (~> 2.0)

data/README.md

@@ -1,24 +1,185 @@
 # TokenManager
 
-TODO: Delete this and the text below, and describe your gem
+`TokenManager` is designed to handle inter micro-service communication without sharing secrets between the services.
+It uses asymmetric signature to verify the hosts.
 
-Welcome to your new gem! In this directory, you'll find the files you need to be able to package up your Ruby library into a gem. Put your Ruby code in the file `lib/token_manager`. To experiment with that code, run `bin/console` for an interactive prompt.
+The workflow schema looks next:
+1. Service A generates a signed token and adds it to a request
+2. Service B receives the request with the token, takes a public_key id (`kid`) from the token and requests Service A for the public key via http request
+3. Service A responds with the public key
+4. Service B verifies the token using the public_key 
 
 ## Installation
 
-TODO: Replace `UPDATE_WITH_YOUR_GEM_NAME_PRIOR_TO_RELEASE_TO_RUBYGEMS_ORG` with your gem name right after releasing it to RubyGems.org. Please do not do it earlier due to security reasons. Alternatively, replace this section with instructions to install your gem from git if you don't plan to release to RubyGems.org.
-
 Install the gem and add to the application's Gemfile by executing:
 
-    $ bundle add UPDATE_WITH_YOUR_GEM_NAME_PRIOR_TO_RELEASE_TO_RUBYGEMS_ORG
+    $ bundle add token_manager
 
 If bundler is not being used to manage dependencies, install the gem by executing:
 
-    $ gem install UPDATE_WITH_YOUR_GEM_NAME_PRIOR_TO_RELEASE_TO_RUBYGEMS_ORG
+    $ gem install token_manager
 
 ## Usage
 
-TODO: Write usage instructions here
+### Basic configuration
+
+Create classes that inherit from TokenManager. 
+
+You need to override `with_redis` method. It must `yield` the given block and
+provide `Redis::Client` instance as an argument (the implementation depends on your redis config).
+
+Also it can be useful to make a "factory" method that will return an instance of the token manager. 
+
+Token manager expects to receive next arguments:
+
+* service_name (required) is a string that represents the current micro-service name. It will be used as `iss` 
+in the JWT. It must be in the `trusted_issuers` (see below) in the receiver's config to be able to verify during the decoding.
+
+* trusted_issuers (optional) is a hash where the keys represent allowed issuer and value is a config to retrieve a public_key for
+that issuer. TokenManager will send a GET request to the provided url with `kid` (key id) parameter. As a result it 
+expects a JSON response like { public_key: "...public_key_here..." }
+
+* token_ttl (optional) will add an expiration claim to every encoded JWT (`exp: Time.now + token_ttl`). If the config 
+is skipped it will require to pass `exp` claim explicitly to every `encode` method call.
+
+* public_key_ttl (default 1 month) not to retrieve the public_key each time the receiver caches it in Redis. 
+This is the Redis cache TTL
+
+* old_key_ttl (default 1 week) after you regenerate the `private_key` its `public_key` still must be 
+stored to verify already generated tokens. This is the Redis cache TTL for the private and public keys.
+
+```ruby
+######### micro-service A
+
+# app/models/a_token.rb 
+class AToken < TokenManager
+  def self.instance
+    @instance ||= new(
+      service_name: 'a_service',
+      token_ttl: 1.minute,
+      trusted_issuers: { 
+        b_service: { url: 'http://localhost:3001/public_keys' } 
+      }
+    )
+  end
+
+  # uses redis for caching
+  private def with_redis
+    Rails.cache.redis.with { |redis| yield(redis) }
+  end
+end
+
+# app/controllers/public_keys_controller
+class PublicKeysController < ApplicationController
+  def index
+    return render(json: { error: '`kid` is required' }, status: 400) unless params[:kid]
+
+    public_key = AToken.instance.public_key(params[:kid])
+    return render(json: { error: 'public_keys not found' }, status: 404) unless public_key
+    
+    render json: {
+      kid: params[:kid],
+      public_key: public_key,
+    }
+  end
+end
+# config/routes.rb
+get 'public_keys', to: 'public_keys#index'
+
+######### micro-service B
+
+# app/models/a_token.rb
+class BToken < TokenManager
+  def self.instance
+    @instance ||= new(
+      service_name: 'b_service',
+      token_ttl: 10.minutes,
+      trusted_issuers: {
+        a_service: { url: 'https://localhost:3000/public_keys' }
+      }
+    )
+  end
+
+  # uses redis for caching
+  private def with_redis
+    @redis ||= ::Redis.new
+    yield(@redis)
+  end
+  
+  def retrieve_issuer_key(iss, kid)
+    AToken.instance.public_key(kid)
+  end
+end
+
+# app/controllers/public_keys_controller
+class PublicKeysController < ApplicationController
+  def index
+    return render(json: { error: '`kid` is required' }, status: 400) unless params[:kid]
+
+    public_key = BToken.instance.public_key(params[:kid])
+    return render(json: { error: 'public_keys not found' }, status: 404) unless public_key
+
+    render json: {
+      kid: params[:kid],
+      public_key: public_key,
+    }
+  end
+end
+
+# config/routes.rb
+get 'public_keys', to: 'public_keys#index'
+```
+
+Now you need to run `rails s -p 3000` for service A and `rails s -p 3001` for service B in different terminals 
+so the services can retrieve public keys. Open services' consoles and try next: 
+
+```ruby
+# console A
+token = AToken.instance.encode(aud: 'b_service', foo: 'bar') # "eyJraWQiOiJjNTcxNDRjYS04YWJhLTRlMWMtOGUwNC05YjZkYTc..."
+# console B
+BToken.instance.decode(token) # [{"exp"=>1679914355, "aud"=>"b_service", "foo"=>"bar", "iss"=>"a_service"}, {"kid"=>"c57144ca-8aba-4e1c-8e04-9b6da70a5dc6", "alg"=>"RS256"}]
+```
+As you can see the `encode` method requires you to specify `aud` claim with the destination service name. Also it adds
+`iss` and `exp` claims (`exp` claim adds automatically only if `token_ttl` was specified).
+
+### Helpers
+
+#### Faraday middleware
+
+If you use libraries which create a connection instance an reuse it you can face a problem that you can't just generate 
+a token and specify it in the connection because the token has its TTL. To solve it you can 
+use `TokenManager::FaradayMiddleware` that receives a block to generate tokens on the fly. 
+Here is an example of the middleware usage with JsonApiClient gem:
+
+```ruby
+ServiceB::Resources::Base.connection do |connection|
+  connection.use TokenManager::FaradayMiddleware do
+    AToken.instance.encode(aud: 'service_b')
+  end
+end
+```
+
+On the ServiceB side you can use `token_from` method to retrieve the token:
+
+```ruby
+class ApplicationController < ActionController::API
+  # ... code ...
+  before_action :authenticate
+
+  private
+
+  def authenticate
+    raise(Unauthorized, 'not authorized') unless token['iss'] == 'service_a' # only service_a has access
+  end
+
+  def token
+    return @token if defined?(@token)
+
+    encoded_token = BToken.token_from(request.headers) || raise(Unauthorized, 'token is absent')
+    @token = BToken.instance.decode(encoded_token).first
+  end
+end
+```
 
 ## Development
 

data/lib/token_manager/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 class TokenManager
-  VERSION = '0.1.0'
+  VERSION = '0.1.1'
 end

data/lib/token_manager.rb

@@ -21,8 +21,8 @@ class TokenManager
     @service_name = options['service_name'] || raise(ArgumentError, '`service_name` is required')
     @trusted_issuers = options['trusted_issuers'] || {}
     @token_ttl = options['token_ttl']
-    @public_key_ttl = options['public_key_ttl'] || 1.day
-    @old_key_ttl = options['public_key_ttl'] || 1.month
+    @public_key_ttl = options['public_key_ttl'] || 1.month
+    @old_key_ttl = options['old_key_ttl'] || 1.week
   end
 
   def encode(payload)

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: token_manager
 version: !ruby/object:Gem::Version
-  version: 0.1.0
+  version: 0.1.1
 platform: ruby
 authors:
 - Bogdan Guban
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2023-03-23 00:00:00.000000000 Z
+date: 2023-03-27 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: activesupport