Home Wiki

Home

Rodauth OAuth: The Oauth 2.0 provider toolkit

Rodauth Oauth is a ruby DSL to build OAuth 2.0 authorization servers and OpenID Connect Identity Providers in a seamless way. It integrates with any rack framework, including Ruby on Rails. It’s simple but also highly customizable, and can be used to build a new identity provider from the ground up, or integrate with any existing user/account management solution you might have.

How to install

# standalone gem
gem install rodauth-oauth

or in a Gemfile:

gem "rodauth-oauth"

How to use

This is the simplest Provider example:

# cat config.ru
require "roda"

class OAuthServer < Roda

  plugin :rodauth do
    enable :login, :oauth_authorization_code_grant
    oauth_application_scopes %w[profile.read profile.write books.read books.research]

    # or if you want to set up oidc
    enable :login, :oidc
    oauth_application_scopes %w[openid email profile profile.read profile.write books.read books.research]
  end

  route do |r|
    r.rodauth

    r.is "users" do
      r.get do
        rodauth.require_oauth_authorization("profile.read")
        # ...
      end

      r.post do
        rodauth.require_oauth_authorization("profile.write")
        # ...
      end
      # ...
    end

    r.is "books" do
      # must have at least of the scopes
      rodauth.require_oauth_authorization("books.read", "books.research")

      r.get do
        # ...
      end
    end
  end
end

Components

Features

OAuth 2.0 protocol framework

rodauth-oauth implements the several OAuth 2.0 specs as their own rodauth features. This means you can enable only the features you want.

When any of the features is enabled, rodauth-oauth provides the following functionality by default:

(This functionality is not available if the oauth_resource_server feature is enabled.)

The following OAuth 2.0 grant features are implemented:

OAuth 2.0 grant flows:
- Authorization Code Grant (via then oauth_authorization_code_grant feature)
- Implicit grant (via the oauth_implicit_grant feature)
- Client credentials grant (via oauth_client_credentials_grant feature, since v0.9)
- Device code grant (via the oauth_device_grant feature)
Proof Key for Code Exchange (PKCE) (via oauth_pkce feature)
Token Introspection (via oauth_token_introspection feature)
Token revocation (via oauth_token_revocation feature)
Mutual-TLS Client Authentication (via oauth_tls_client_auth feature)
JWT support:
- JWT Access Tokens (via oauth_jwtfeature)
- JWKs URI (via oauth_jwt_jwksfeature)
- JWT Secured Authorization Requests (JAR) (via oauth_jwt_secured_authorization_request feature);
- JWT Secured Authorization Response Mode (JARM) (via oauth_jwt_secured_authorization_response_mode feature);
Pushed Authorization Requests (PAR) (via oauth_pushed_authorization_request feature);
Client Assertion Framework (via oauth_assertion_base feature)
- JWT Bearer Assertions (via oauth_jwt_bearer_grant feature)
- SAML Bearer Assertions (via oauth_saml_bearer_grant feature)
OAuth 2.0 Demonstrating Proof-of-Possession at the Application Layer (DPoP) (via oauth_dpop feature)
Resource Indicators (via oauth_resource_indicators feature)
Dynamic Client Registration Protocol (via oauth_dynamic_client_registration feature)
Client ID Metadata Document (via oauth_client_id_metadata_document feature)
Resource Server Mode

OpenID Connect

Support for OpenID Connect is built on top of the existing OAuth and Oauth JWT functionality. It’s available via the oidc feature, and implements the following features:

ID Token Authentication through the Authorization Code and Implicit flow
UserInfo Endpoint
Multiple Response Types (aka the “Hybrid flow”)
OpenID Configuration/Discovery
Self-Issued OpenID Provider (via oidc_self_issued)
Session Management (via oidc_session_management)
RP-Initiated Logout (via oidc_rp_initiated_logout)
Frontchannel Logout (via oidc_frontchannel_logout)
Backchannel Logout (via oidc_backchannel_logout)
Dynamic Client Registration (via oidc_dynamic_client_registration feature)

Extras

Integration

Comparisons

Here’s how rodauth-oauth compares to the alternatives:

	rodauth-oauth	doorkeeper
Access Tokens	✅	✅
Refresh Token Grant	✅	✅
Authorization Code Grant	✅	✅
Implicit Grant	✅	✅
Client Credentials Grant	✅	✅
Resource Owner Password Credentials Grant	❌	✅
PKCE	✅	✅
Token Revocation	✅	✅
Token Introspection	✅	✅
Dynamic Client Registration	✅	❌
Device Code Grant	✅	✅ (* via the `doorkeeper-device_authorization_grant` extension)
JWT Access Tokens	✅	✅ (* via the `doorkeeper-jwt` extension)
JWE support	✅	❌
JWT Secured Authorization Requests (JAR)	✅	❌
JWT Secured Authorization Response Mode (JARM)	✅	❌
Pushed Authorization Requests (PAR)	✅	❌
OAuth 2.0 Demonstrating Proof-of-Possession at the Application Layer (DPoP)	✅	❌
Mutual-TLS Client Authentication	✅	❌
Assertion Grants Framework	✅	❌
SAML 2.0 Bearer Grant	✅	❌
JWT Bearer Grant	✅	❌
OpenID Connect	✅	✅ (* via the `doorkeeper-openid_connect` extension)
OpenID Dynamic Client Registration	✅	❌
OpenID Connect Session Management	✅	❌
OpenID RP Initiated Logout	✅	❌
Frontchannel Logout	✅	❌
Backchannel Logout	✅	❌

Appraisals

Roda/Sequel/Rodauth

A word of acknowledgement to Jeremy Evans, the maintainer of rodauth, roda, and sequel, on which shoulders rodauth-oauth stands, and on which philosophy and design principles it was based on.

Rodauth-Rails

A word of acknowledgement to Janko Marohnic, the maintainer of rodauth-rails and sequel-activerecord_connection, without which rodauth-oauth couldn’t work on Rails.

honeyryder