rodauth-oauth 0.0.1

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: cea0f9a4896e57d535c2ef73eff0c1a9e6b4e25f4d53740c65171b8c098a8ac1
+  data.tar.gz: 96f78feb4157d6f940700fe658b7817b95bd79b61a6f02b9cc530947512a8ff0
+SHA512:
+  metadata.gz: 3b2bc30f8793a0ae0ef8a48b46fcd896494d6a941e57e66481d8b8197424c5a6da80761237e26b4eb70acf73ae933be40484d7ca06cf5191790ee83b62eb7411
+  data.tar.gz: 7a1cb3061c3eb9c271b04c35e970306a96018a40408c63c5fd5c815d62f3b4bfdf8c84f32c6947015c8a99a810a8cc904a1f6e10ca3f9eba842ec8575f975a11

data/CHANGELOG.md

@@ -0,0 +1,5 @@
+# CHANGELOG
+
+## 0.0.1
+
+Initial implementation of the Oauth 2.0 framework, with an example app done using roda.

data/README.md

@@ -0,0 +1,333 @@
+# Rodauth::Oauth
+
+[![pipeline status](https://gitlab.com/honeyryderchuck/rodauth-oauth/badges/master/pipeline.svg)](https://gitlab.com/honeyryderchuck/rodauth-oauth/-/commits/master)
+[![coverage report](https://gitlab.com/honeyryderchuck/rodauth-oauth/badges/master/coverage.svg)](https://gitlab.com/honeyryderchuck/rodauth-oauth/-/commits/master)
+
+This is an extension to the `rodauth` gem which adds support for the [OAuth 2.0 protocol](https://tools.ietf.org/html/rfc6749).
+
+## Features
+
+This gem implements:
+
+* [The OAuth 2.0 protocol framework](https://tools.ietf.org/html/rfc6749):
+  * [Authorization grant flow](https://tools.ietf.org/html/rfc6749#section-1.3);
+  * [Access Token generation](https://tools.ietf.org/html/rfc6749#section-1.4);
+  * [Access Token refresh](https://tools.ietf.org/html/rfc6749#section-1.5);
+  * [Token revocation](https://tools.ietf.org/html/rfc7009);
+  * [Implicit grant (off by default)[https://tools.ietf.org/html/rfc6749#section-4.2];
+* Access Type (Token refresh online and offline);
+* OAuth application and token management dashboards;
+
+
+This gem supports also rails (through [rodauth-rails]((https://github.com/janko/rodauth-rails))).
+
+
+## Installation
+
+Add this line to your application's Gemfile:
+
+```ruby
+gem 'rodauth-oauth'
+```
+
+And then execute:
+
+    $ bundle install
+
+Or install it yourself as:
+
+    $ gem install rodauth-oauth
+
+## Usage
+
+This tutorial assumes you already read the documentation and know how to set up `rodauth`. After that, integrating `roda-auth` will look like:
+
+```ruby
+plugin :rodauth do
+  # enable it in the plugin
+  enable :login, :oauth
+  oauth_application_default_scope %w[profile.read]
+  oauth_application_scopes %w[profile.read profile.write]
+end
+
+# then, inside roda
+
+route do |r|
+  r.rodauth
+
+  # public routes go here
+  # ...
+  # here you do your thing
+  # authenticated section is here
+
+  rodauth.require_authentication
+
+  # oauth will only kick in on ce you call #require_oauth_authorization
+
+  r.is "users" do
+    rodauth.require_oauth_authorization # defaults to profile.read
+    r.post do
+      rodauth.require_oauth_authorization("profile.write")
+    end
+    # ...
+  end
+
+  r.is "books" do
+    rodauth.require_oauth_authorization("books.read", "books.research")
+    r.get do
+      # ...
+    end
+  end
+end
+```
+
+You'll have to do a bit more boilerplate, so here's the instructions.
+
+### Example (TL;DR)
+
+If you're familiar with the technology and want to skip the next paragraphs, just [check our roda example](https://gitlab.com/honeyryderchuck/rodauth-oauth/-/tree/master/examples/roda).
+
+
+Generating tokens happens mostly server-to-server, so here's an example using:
+
+#### Access Token Generation
+
+##### HTTPX
+
+```ruby
+require "httpx"
+httpx = HTTPX.plugin(:authorization)
+response = httpx.with(headers: { "X-your-auth-scheme" => ENV["SERVER_KEY"] })
+                .post("https://auth_server/oauth-token",json: {
+                  client_id: ENV["OAUTH_CLIENT_ID"],
+                  grant_type: "authorization_code",
+                  code: "oiweicnewdh32fhoi3hf3ihfo2ih3f2o3as"
+                })
+response.raise_for_status
+payload = JSON.parse(response.to_s)
+puts payload #=> {"token" => "awr23f3h8f9d2h89...", "refresh_token" => "23fkop3kr290kc..." ....
+```
+
+##### cURL
+
+```
+> curl -H "X-your-auth-scheme: $SERVER_KEY" --data '{"client_id":"$OAUTH_CLIENT_ID","grant_type":"authorization_code","code":"oiweicnewdh32fhoi3hf3ihfo2ih3f2o3as"}' https://auth_server/oauth-token
+```
+
+#### Refresh Token
+
+Refreshing expired tokens also happens mostly server-to-server, here's an example:
+
+##### HTTPX
+
+```ruby
+require "httpx"
+httpx = HTTPX.plugin(:authorization)
+response = httpx.with(headers: { "X-your-auth-scheme" => ENV["SERVER_KEY"] })
+                .post("https://auth_server/oauth-token",json: {
+                  client_id: ENV["OAUTH_CLIENT_ID"],
+                  grant_type: "refresh_token",
+                  token: "2r89hfef4j9f90d2j2390jf390g"
+                })
+response.raise_for_status
+payload = JSON.parse(response.to_s)
+puts payload #=> {"token" => "awr23f3h8f9d2h89...", "token_type" => "Bearer" ....
+```
+
+##### cURL
+
+```
+> curl -H "X-your-auth-scheme: $SERVER_KEY" --data '{"client_id":"$OAUTH_CLIENT_ID","grant_type":"token","token":"2r89hfef4j9f90d2j2390jf390g"}' https://auth_server/oauth-token
+```
+
+#### Revoking tokens
+
+Token revocation can be done both by the idenntity owner or the application owner, and can therefore be done either online (browser-based form) or server-to-server. Here's an example using server-to-server:
+
+```ruby
+require "httpx"
+httpx = HTTPX.plugin(:authorization)
+response = httpx.with(headers: { "X-your-auth-scheme" => ENV["SERVER_KEY"] })
+                .post("https://auth_server/oauth-revoke",json: {
+                  client_id: ENV["OAUTH_CLIENT_ID"],
+                  token_type_hint: "access_token", # can also be "refresh:tokn"
+                  token: "2r89hfef4j9f90d2j2390jf390g"
+                })
+response.raise_for_status
+payload = JSON.parse(response.to_s)
+puts payload #=> {"token" => "awr23f3h8f9d2h89...", "token_type" => "Bearer" ....
+```
+
+##### cURL
+
+```
+> curl -H "X-your-auth-scheme: $SERVER_KEY" --data '{"client_id":"$OAUTH_CLIENT_ID","token_type_hint":"access_token","token":"2r89hfef4j9f90d2j2390jf390g"}' https://auth_server/oauth-revoke
+```
+
+### Database migrations
+
+You have to generate database tables for Oauth applications, grants and tokens. In order for you to hit the ground running, [here's a set of migrations (using `sequel`) to generate the needed tables](https://gitlab.com/honeyryderchuck/rodauth-oauth/-/tree/master/test/migrate) (omit the first 2 if you already have account tables).
+
+You can change column names or even use existing tables, however, be aware that you'll have to define new column accessors at the `rodauth` plugin declaration level. Let's say, for instance, you'd like to change the `oauth_grants` table name to `access_grants`, and it's `code` column to `authorization_code`; then, you'd have to do the following:
+
+```ruby
+plugin :rodauth do
+  # enable it in the plugin
+  enable :login, :oauth
+  # ...
+  oauth_grants_table "access_grants"
+  oauth_grants_code_column "authorization_code"
+end
+```
+
+If you're starting from scratch though, the recommendation is to stick to the defaults.
+
+### HTML views
+
+You'll have to generate HTML templates for the Oauth Authorization form.
+
+The rodauth default setup expects the roda `render` plugin to be activated; by default, it expects a `views` directory to be defined in the project root folder. The Oauth Authorization template must be therefore defined there, and it should be called `oauth_authorize.(erb|str|...)` (read the [roda `render` plugin documentation](http://roda.jeremyevans.net/rdoc/classes/Roda/RodaPlugins/Render.html) for more info about HTML templating).
+
+### Endpoints
+
+Once you set it up, by default, the following endpoints will be available:
+
+* `GET /oauth-authorize`: Loads the OAuth authorization HTML form;
+* `POST /oauth-authorize`: Responds to an OAuth authorization request, as [per the spec](https://tools.ietf.org/html/rfc6749#section-4);
+* `POST /oauth-token`: Generates OAuth tokens as [per the spec](https://tools.ietf.org/html/rfc6749#section-4.4.2);
+* `POST /oauth-revoke`: Revokes OAuth tokens as [per the spec](https://tools.ietf.org/html/rfc7009);
+
+### OAuth applications
+
+This feature is **optional**, as not all authorization servers will want a full oauth applications dashboard. However, if you do and you don't want to do the work yourself, you can set it up in your roda app like this:
+
+```ruby
+route do |r|
+  r.rodauth
+  # don't forget to authenticate to access the dashboard
+  rodauth.require_authentication
+  rodauth.oauth_applications
+  # ...
+end
+```
+
+This will define the following endpoints:
+
+* `GET /oauth-applications`: returns the OAuth applications HTML dashboard;
+* `GET /oauth-applications/{application_id}`: returns an OAuth application HTML page;
+* `GET /oauth-applications/{application_id}/oauth-tokens`: returns the OAuth tokens from an OAuth application HTML page;
+* `GET /oauth-applications/new`: returns a new OAuth application form;
+* `POST /oauth-applications`: processes a new OAuth application request;
+
+As in the OAuth authorization form example, you'll have to define the following HTML templates in order to use this feature:
+
+* `oauth_applications.(erb|str|...)`: the list of OAuth applications;
+* `oauth_application.(erb|str|...)`: the OAuth application page;
+* `new_oauth_application.(erb|str|...)`: the new OAuth application form;
+* `oauth_tokens.(erb|str|...)`: the list of OAuth tokens from an application;
+
+## Rails
+
+This library provides a thin integration layer on top of [rodauth-rails](https://github.com/janko/rodauth-rails). Therefore, the first step you'll have to take is to integrate it in your project. Fortunately, it's very straightforward.
+
+You'll have to run the generator task to create the necessary migrations and views:
+
+```
+> bundle exec rails generate rodauth:oauth:install
+# create a migration file, db/migrate(*_create_rodauth_oauth.rb);
+# Oauth Application, Grant and Token models into app/models;
+> bundle exec rails generate rodauth:oauth:views
+# creates view files under app/views/rodauth
+```
+
+You are encouraged to check the output and adapt it to your needs.
+
+You can then enable this feature in `lib/rodauth_app.rb` and set up any options you want:
+
+```ruby
+# lib/roudauth_app.rb
+enable :oauth
+# OAuth
+oauth_application_default_scope "profile.read"
+oauth_application_scopes %w[profile.read profile.write books.read books.write]
+```
+
+Now that you're set up, you can use the `rodauth` object to deny access to certain subsets of your app/API:
+
+```ruby
+class BooksController < ApplicationController
+  before_action :allow_read_access, only: %i[index show]
+  before_action :allow_write_access, only: %i[create update]
+
+  def index
+    # ...
+  end
+
+  def show
+    # ...
+  end
+
+  def create
+    # ...
+  end
+
+  def update
+    # ...
+  end
+
+  private
+
+  def allow_read_access
+    rodauth.require_oauth_authorization("books.read")
+  end
+
+  def allow_write_access
+    rodauth.require_oauth_authorization("books.write")
+  end
+end
+```
+
+## Features
+
+In this section, the non-standard features are going to be described in more detail.
+
+### Access Type (default: "offline")
+
+The "access_type" feature allows the authorization server to emit access tokens with no associated refresh token. This means that users with expired access tokens will have to go through the OAuth flow everytime they need a new one.
+
+In order to enable this option, add "access_type=online" to the query params section of the authorization url.
+
+**Note**: this feature does not yet support the "approval_prompt" feature.
+
+
+### Implicit Grant (default: disabled)
+
+The implicit grant flow is part of the original OAuth 2.0 RFC, however, if you care about security, you are **strongly recommended** not to enable it.
+
+However, if you really need it, just pass the option when enabling the `rodauth` plugin:
+
+```ruby
+plugin :rodauth do
+  enable :oauth
+  use_oauth_implicit_grant_type true
+end
+```
+
+And add "response_type=token" to the query params section of the authorization url.
+
+## Ruby support policy
+
+The minimum Ruby version required to run `rodauth-oauth` is 2.3 . Besides that, it should support all rubies that rodauth and roda support.
+
+### JRuby
+
+If you're interested in using this library in rails, be warned that `rodauth-rails` doesn't support it yet (although, this is expected to change at some point).
+
+## Development
+
+After checking out the repo, run `bundle install` to install dependencies. Then, run `rake test` to run the tests, and `rake rubocop` to run the linter.
+
+## Contributing
+
+Bug reports and pull requests are welcome on Gitlab at https://gitlab.com/honeyryderchuck/rodauth-oauth.
+

data/lib/generators/roda/oauth/install_generator.rb

@@ -0,0 +1,47 @@
+# frozen_string_literal: true
+
+require "rails/generators/base"
+require "rails/generators/migration"
+require "rails/generators/active_record"
+
+module Rodauth::OAuth::Rails
+  module Generators
+    class InstallGenerator < ::Rails::Generators::Base
+      include ::Rails::Generators::Migration
+
+      source_root "#{__dir__}/templates"
+      namespace "roda:oauth:install"
+
+      def create_rodauth_migration
+        return unless defined?(ActiveRecord::Base)
+
+        migration_template "db/migrate/create_rodauth_oauth.rb", "db/migrate/create_rodauth_oauth.rb"
+      end
+
+      def create_oauth_models
+        return unless defined?(ActiveRecord::Base)
+
+        template "app/models/oauth_application.rb"
+        template "app/models/oauth_grant.rb"
+        template "app/models/oauth_token.rb"
+      end
+
+      private
+
+      # required by #migration_template action
+      def self.next_migration_number(dirname)
+        ActiveRecord::Generators::Base.next_migration_number(dirname)
+      end
+
+      def migration_version
+        if ActiveRecord.version >= Gem::Version.new("5.0.0")
+          "[#{ActiveRecord::VERSION::MAJOR}.#{ActiveRecord::VERSION::MINOR}]"
+        end
+      end
+
+      def adapter
+        ActiveRecord::Base.connection_config.fetch(:adapter)
+      end
+    end
+  end
+end

data/lib/generators/roda/oauth/templates/app/models/oauth_application.rb

@@ -0,0 +1,4 @@
+# frozen_string_literal: true
+
+class OauthApplication < ApplicationRecord
+end

data/lib/generators/roda/oauth/templates/app/models/oauth_grant.rb

@@ -0,0 +1,4 @@
+# frozen_string_literal: true
+
+class OauthGrant < ApplicationRecord
+end

data/lib/generators/roda/oauth/templates/app/models/oauth_token.rb

@@ -0,0 +1,4 @@
+# frozen_string_literal: true
+
+class OauthToken < ApplicationRecord
+end

data/lib/generators/roda/oauth/templates/db/migrate/create_rodauth_oauth.rb

@@ -0,0 +1,47 @@
+class CreateRodauthOAuth < ActiveRecord::Migration<%= migration_version %>
+  def change
+    create_table :oauth_applications do |t|
+      t.integer :account_id
+      t.foreign_key :accounts, column: :account_id
+      t.string :name, null: false
+      t.string :description, null: false
+      t.string :homepage_url, null: false
+      t.string :redirect_uri, null: false
+      t.string :client_id, null: false, index: { unique: true }
+      t.string :client_secret, null: false, index: { unique: true }
+      t.string :scopes, null: false
+      t.datetime :created_at, null: false, default: -> { "CURRENT_TIMESTAMP" }
+    end
+
+    create_table :oauth_grants do |t|
+      t.integer :account_id
+      t.foreign_key :accounts, column: :account_id
+      t.integer :oauth_application_id
+      t.foreign_key :oauth_applications, column: :oauth_application_id
+      t.string :code, null: false
+      t.datetime :expires_in, null: false
+      t.string :redirect_uri
+      t.datetime :revoked_at
+      t.string :scopes, null: false
+      t.datetime :created_at, null: false, default: -> { "CURRENT_TIMESTAMP" }
+      t.index(%i[oauth_application_id code], unique: true)
+    end
+
+    create_table :oauth_tokens do |t|
+      t.integer :account_id
+      t.foreign_key :accounts, column: :account_id
+      t.integer :oauth_grant_id
+      t.foreign_key :oauth_grants, column: :oauth_grant_id
+      t.integer :oauth_token_id
+      t.foreign_key :oauth_tokens, column: :oauth_token_id
+      t.integer :oauth_application_id
+      t.foreign_key :oauth_applications, column: :oauth_application_id
+      t.string :token, null: false, token: true
+      t.string :refresh_token
+      t.datetime :expires_in, null: false
+      t.datetime :revoked_at
+      t.string :scopes, null: false
+      t.datetime :created_at, null: false, default: -> { "CURRENT_TIMESTAMP" }
+    end
+  end
+end