rodauth-omniauth 0.5.1 → 0.6.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: dad995353c13952f65bb35c561c82d755f2319318ac2409adc948b4b95fd6171
-  data.tar.gz: 30bdc64ac42ad66ff6003e5d95ffd5123ce9564661157ffb25f0f496e2772a3e
+  metadata.gz: 0453fcafd04b57e1adf926663a9edb8d1f9f72f25aa952d193cf092fc877327f
+  data.tar.gz: 3a3211e64e8558d3fe5aea563498f79763e3ebed62e9bd964020f52f5be36857
 SHA512:
-  metadata.gz: '099007ffbf1e055d03625fbe9d90d3b032c27a83803a900e8f3b859dc2b8f350cc10fca07e92668dd49543c1e612a01bc4b0ba582066b633ef147883715a27fa'
-  data.tar.gz: 699b0e8890e5b117c69bf6b7a6aa89e140aebea976ec56455feaee688ef260e7dc71bb9cbc7bc05397ffef6a40f6c4d1260ef5f7885958e6213e4adc7541e270
+  metadata.gz: 005c3b00e023b15f033af4782dba58f0e8372b4573c17822d0d770a980568c691a85a8c16422b8d3193ade0e8bdcfdb5ca54a9cd0244465842ef51efb7a69b37
+  data.tar.gz: 282df1dd1951ce51c41af1622e95e486a925280e699e9e0caa438ff5528efea6954d8d1b20f412f620fa5a41f114872c4773aba110010f32cd19936540abc122

data/README.md

@@ -2,6 +2,15 @@
 
 [Rodauth] feature that offers login and registration via multiple external providers using [OmniAuth], together with the persistence of external identities.
 
+It comes with many features out of the box:
+
+* multiple external providers (with automatic identity linking)
+* automatic account creation (or login-only)
+* email verification on login
+* ability to count as two factors
+* JSON API support (+ JWT)
+* per-configuration strategies with inheritance
+
 ## Installation
 
 Add the gem to your project:
@@ -10,7 +19,11 @@ Add the gem to your project:
 $ bundle add rodauth-omniauth
 ```
 
-## Usage
+> [!NOTE]
+> Rodauth's CSRF protection will be used for the request validation phase, so there is no need for gems like `omniauth-rails_csrf_protection`.
+
+
+## Getting started
 
 You'll first need to create the table for storing external identities:
 
@@ -46,17 +59,16 @@ Then enable the `omniauth` feature and register providers in your Rodauth config
 $ bundle add omniauth-facebook omniauth-twitter, omniauth-google-oauth2
 ```
 ```rb
-plugin :rodauth do
-  enable :omniauth
+# in your Rodauth configuration
+enable :omniauth
 
-  omniauth_provider :facebook, ENV["FACEBOOK_APP_ID"], ENV["FACEBOOK_APP_SECRET"], scope: "email"
-  omniauth_provider :twitter, ENV["TWITTER_API_KEY"], ENV["TWITTER_API_SECRET"]
-  omniauth_provider :google_oauth2, ENV["GOOGLE_CLIENT_ID"], ENV["GOOGLE_CLIENT_SECRET"], name: :google
-end
+omniauth_provider :facebook, ENV["FACEBOOK_APP_ID"], ENV["FACEBOOK_APP_SECRET"], scope: "email"
+omniauth_provider :twitter, ENV["TWITTER_API_KEY"], ENV["TWITTER_API_SECRET"]
+omniauth_provider :google_oauth2, ENV["GOOGLE_CLIENT_ID"], ENV["GOOGLE_CLIENT_SECRET"], name: :google
 ```
 
-> [!NOTE]
-> It is important to note that `rodauth-omniauth` requires OmniAuth 2.x, so it's only compatible with providers gems that support it.
+> [!WARNING]
+> The `rodauth-omniauth` gem requires OmniAuth 2.x, so it's only compatible with providers gems that support it.
 
 You can now add authentication links to your login form:
 
@@ -88,14 +100,47 @@ account.identities #=> [#<Account::Identity ...>, ...]
 
 Currently, provider login is required to return the user's email address, and account creation is assumed not to require additional fields that need to be entered manually. There is currently also no built-in functionality for connecting/removing external identities when signed in. Both features are planned for future versions.
 
-### Timestamps
-
-If you'll be adding created/updated timestamps to the identities table, also add these lines to your Rodauth configuration:
-
-```rb
-omniauth_identity_insert_hash { super().merge(created_at: Time.now) }
-omniauth_identity_update_hash { { updated_at: Time.now } }
-```
+## Configuration reference
+
+### Auth Value Methods
+
+| Method | Description |
+| :----  | :---------- |
+| `omniauth_verify_account?` | Automatically verify unverified accounts on login (defaults to true). |
+| `omniauth_login_unverified_account_error_flash` | Flash message for when existing account is unverified and automatic verification is disabled. |
+| `omniauth_login_failure_redirect` | Redirect location for when OmniAuth login failed. |
+| `omniauth_create_account?` | Automatically create account for new email address on OmniAuth login (defaults to true). |
+| `omniauth_login_no_matching_account_error_flash` | Flash message for when no existing account was found and automatic creation is disabled. |
+| `omniauth_two_factors?` | Treat OmniAuth login as two factors when using MFA (defaults to false). |
+| `omniauth_identities_table` | Table name for external identities (defaults to `account_identities`). |
+| `omniauth_identities_id_column` | Primary key column for identities table (defaults to `id`). |
+| `omniauth_identities_account_id_column` | Foreign key column for identities table (defaults to `account_id`). |
+| `omniauth_identities_provider_column` | Provider column for identities table (defaults to `provider`). |
+| `omniauth_identities_uid_column` | UID column for identities table (defaults to `uid`). |
+| `omniauth_prefix` | Path prefix to use for OmniAuth routes (defaults to `/auth`). |
+| `omniauth_failure_error_flash` | Flash message for failed OmniAuth login. |
+| `omniauth_failure_redirect` | Redirect location for failed OmniAuth login. |
+| `omniauth_failure_error_status` | Response status for failed OmniAuth login (defaults to 500). |
+| `omniauth_authorize_url_key` | Field name for authorization URL in JSON mode. |
+| `omniauth_error_type_key` | Field name for error type in JSON mode. |
+
+### Auth Methods
+
+| Method | Description |
+| :----  | :---------- |
+| `account_from_omniauth` | Find an existing account from OmniAuth login data (by default matches by email). |
+| `before_omniauth_callback_route` | Run arbitrary code before handling the callback route. |
+| `omniauth_identity_insert_hash` | Hash of column values used for creating a new identity on login. |
+| `omniauth_identity_update_hash` | Hash of column values used fro updating existing identities on login. |
+| `before_omniauth_create_account` | Any actions to take before creating a new account on OmniAuth login. |
+| `after_omniauth_create_account` | Any actions to take after creating a new account on OmniAuth login. |
+| `omniauth_setup` | Hook for OmniAuth setup phase |
+| `omniauth_request_validation_phase` | Hook for OmniAuth request validation phase (defaults to CSRF protection). |
+| `omniauth_before_request_phase` | Hook for OmniAuth before request phase. |
+| `omniauth_before_callback_phase` | Hook for OmniAuth  before callback phase. |
+| `omniauth_on_failure` | Hook for OmniAuth login failure. |
+
+## Customizing
 
 ### Login
 
@@ -163,9 +208,28 @@ You can change the default error message for when existing account wasn't found
 omniauth_login_no_matching_account_error_flash "No existing account found"
 ```
 
+### Multifactor authentication
+
+By default, OmniAuth login will count only as one factor. So, if the user has multifactor authentication enabled, they will be asked to authenticate with 2nd factor when required.
+
+If you're using OmniAuth login for SSO and want to rely on 2FA policies set on the external provider, you can have OmniAuth login count as two factors:
+
+```rb
+omniauth_two_factors? true
+```
+
+You can also make it conditional based on data from the external provider:
+
+```rb
+omniauth_two_factors? do
+  # only count as two factors if external account uses 2FA
+  omniauth_extra["raw_info"]["two_factor_authentication"]
+end
+```
+
 ### Identity data
 
-You can also store extra data on the external identities. For example, we could override the update hash to store `info`, `credentials`, and `extra` data from the auth hash into separate columns:
+You can also store extra data on the external identities. The most common use case is storing [timestamps](https://github.com/janko/rodauth-omniauth/wiki/Timestamps). You could also persist data about external identities, for example:
 
 ```rb
 alter_table :account_identities do
@@ -198,6 +262,8 @@ omniauth_identity_insert_hash do
 end
 ```
 
+### Identity schema
+
 You can change the table name or any of the column names:
 
 ```rb
@@ -208,33 +274,25 @@ omniauth_identities_provider_column :provider
 omniauth_identities_uid_column :uid
 ```
 
-### Audit logging
-
-If you're using the `audit_logging` feature, it can be useful to include the external provider name in the `login` audit logs:
-
-```rb
-audit_log_metadata_for :login do
-  { "provider" => omniauth_provider } if authenticated_by.include?("omniauth")
-end
-```
-
 ## Base
 
 The `omniauth` feature builds on top of the `omniauth_base` feature, which sets up OmniAuth and routes its requests, but has no interaction with the database. So, if you would prefer to handle external logins differently, you can load just the `omniauth_base` feature, and implement your own callback phase.
 
 ```rb
-plugin :rodauth do
-  enable :omniauth_base
-
-  omniauth_provider :github, ENV["GITHUB_CLIENT_ID"], ENV["GITHUB_CLIENT_SECRET"], scope: "user"
-  omniauth_provider :apple, ENV["APPLE_CLIENT_ID"], ENV["APPLE_CLIENT_SECRET"], scope: "email name"
-end
+# in your Rodauth configuration
+enable :omniauth_base
 
-route do |r|
-  r.rodauth # routes Rodauth and OmniAuth requests
-
-  r.get "auth", String, "callback" do
-    # ... handle callback request ...
+omniauth_provider :github, ENV["GITHUB_CLIENT_ID"], ENV["GITHUB_CLIENT_SECRET"], scope: "user"
+omniauth_provider :apple, ENV["APPLE_CLIENT_ID"], ENV["APPLE_CLIENT_SECRET"], scope: "email name"
+```
+```rb
+# in your routes
+get "/auth/:provider/callback", to: "rodauth#omniauth_login"
+```
+```rb
+class RodauthController < ApplicationController
+  def omniauth_login
+    # ...
   end
 end
 ```
@@ -332,10 +390,6 @@ omniauth_on_failure do
 end
 ```
 
-#### CSRF protection
-
-The default request validation phase uses Rodauth's configured CSRF protection, so there is no need for external gems such as `omniauth-rails_csrf_protection`.
-
 ### Inheritance
 
 The registered providers are inherited between Rodauth auth classes, so you can have fine-grained configuration for different account types.
@@ -347,15 +401,13 @@ class RodauthBase < Rodauth::Auth
     omniauth_provider :google_oauth2, ...
   end
 end
-```
-```rb
+
 class RodauthMain < RodauthBase
   configure do
     omniauth_provider :facebook, ...
   end
 end
-```
-```rb
+
 class RodauthAdmin < RodauthBase
   configure do
     omniauth_provider :twitter, ...
@@ -364,12 +416,6 @@ class RodauthAdmin < RodauthBase
 end
 ```
 ```rb
-class RodauthApp < Roda
-  plugin :rodauth, auth_class: RodauthMain
-  plugin :rodauth, auth_class: RodauthAdmin, name: :admin
-end
-```
-```rb
 rodauth.omniauth_providers #=> [:google_oauth2, :facebook]
 rodauth(:admin).omniauth_providers #=> [:google_oauth2, :twitter, :github]
 ```
@@ -404,6 +450,9 @@ Content-Type: application/json
 { "success": "You have been logged in" }
 ```
 
+> [!NOTE]
+> Unless you're using JWT, make sure you're persisting cookies across requests, as most OmniAuth strategies rely on session storage.
+
 If there was an OmniAuth failure, the error type will be included in the response:
 
 ```http

data/lib/rodauth/features/omniauth.rb

@@ -20,6 +20,7 @@ module Rodauth
     auth_value_method :omniauth_identities_account_id_column, :account_id
     auth_value_method :omniauth_identities_provider_column, :provider
     auth_value_method :omniauth_identities_uid_column, :uid
+    auth_value_method :omniauth_two_factors?, false
 
     auth_value_methods(
       :omniauth_verify_account?,
@@ -57,14 +58,12 @@ module Rodauth
     def _handle_omniauth_callback
       before_omniauth_callback_route
 
-      retrieve_omniauth_identity
-
-      if !account && omniauth_identity
-        account_from_omniauth_identity
-      end
-
       unless account
-        account_from_omniauth
+        if omniauth_identity
+          account_from_omniauth_identity
+        else
+          account_from_omniauth
+        end
       end
 
       if account && !open_account?
@@ -80,10 +79,7 @@ module Rodauth
       transaction do
         if !account
           if omniauth_create_account?
-            omniauth_new_account
-            before_omniauth_create_account
-            omniauth_save_account
-            after_omniauth_create_account
+            omniauth_create_account
           else
             set_redirect_error_flash omniauth_login_no_matching_account_error_flash
             redirect omniauth_login_failure_redirect
@@ -97,11 +93,17 @@ module Rodauth
         end
       end
 
-      login("omniauth")
+      login("omniauth") do
+        two_factor_update_session("omniauth-two") if omniauth_second_factor?
+      end
+    end
+
+    def omniauth_identity
+      @omniauth_identity ||= retrieve_omniauth_identity
     end
 
     def retrieve_omniauth_identity
-      @omniauth_identity = _retrieve_omniauth_identity(omniauth_provider, omniauth_uid)
+      _retrieve_omniauth_identity(omniauth_provider, omniauth_uid)
     end
 
     def account_from_omniauth_identity
@@ -142,7 +144,9 @@ module Rodauth
       remove_omniauth_identities
     end
 
-    attr_reader :omniauth_identity
+    def omniauth_second_factor?
+      features.include?(:two_factor_base) && uses_two_factor_authentication? && omniauth_two_factors?
+    end
 
     def omniauth_verify_account?
       features.include?(:verify_account) && account[login_column] == omniauth_email
@@ -159,6 +163,13 @@ module Rodauth
       true
     end
 
+    def omniauth_create_account
+      omniauth_new_account
+      before_omniauth_create_account
+      omniauth_save_account
+      after_omniauth_create_account
+    end
+
     def _omniauth_new_account(login)
       acc = { login_column => login }
       unless skip_status_checks?
@@ -205,7 +216,7 @@ module Rodauth
     end
 
     def _account_from_omniauth_identity
-      account_ds(omniauth_identity_account_id).first
+      _account_from_id(omniauth_identity_account_id)
     end
 
     def omniauth_identity_id

data/lib/rodauth/features/omniauth_base.rb

@@ -195,10 +195,12 @@ module Rodauth
     end
 
     def self.included(auth)
-      auth.extend ClassMethods
+      auth.extend OmniauthBase::ClassMethods
       auth.instance_variable_set(:@omniauth_providers, [])
     end
+  end
 
+  module OmniauthBase
     module ClassMethods
       def inherited(subclass)
         super

data/rodauth-omniauth.gemspec

@@ -1,6 +1,6 @@
 Gem::Specification.new do |spec|
   spec.name          = "rodauth-omniauth"
-  spec.version       = "0.5.1"
+  spec.version       = "0.6.1"
   spec.authors       = ["Janko Marohnić"]
   spec.email         = ["janko@hey.com"]
 
@@ -17,7 +17,7 @@ Gem::Specification.new do |spec|
   spec.files         = Dir["README.md", "LICENSE.txt", "*.gemspec", "lib/**/*", "locales/**/*"]
   spec.require_paths = ["lib"]
 
-  spec.add_dependency "rodauth", "~> 2.13"
+  spec.add_dependency "rodauth", "~> 2.36"
   spec.add_dependency "omniauth", "~> 2.0"
 
   spec.add_development_dependency "minitest"

metadata

@@ -1,14 +1,13 @@
 --- !ruby/object:Gem::Specification
 name: rodauth-omniauth
 version: !ruby/object:Gem::Version
-  version: 0.5.1
+  version: 0.6.1
 platform: ruby
 authors:
 - Janko Marohnić
-autorequire:
 bindir: bin
 cert_chain: []
-date: 2024-10-12 00:00:00.000000000 Z
+date: 1980-01-02 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: rodauth
@@ -16,14 +15,14 @@ dependencies:
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '2.13'
+        version: '2.36'
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '2.13'
+        version: '2.36'
 - !ruby/object:Gem::Dependency
   name: omniauth
   requirement: !ruby/object:Gem::Requirement
@@ -197,7 +196,6 @@ licenses:
 metadata:
   homepage_uri: https://github.com/janko/rodauth-omniauth
   source_code_uri: https://github.com/janko/rodauth-omniauth
-post_install_message:
 rdoc_options: []
 require_paths:
 - lib
@@ -212,8 +210,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.5.11
-signing_key:
+rubygems_version: 3.6.9
 specification_version: 4
 summary: Rodauth extension for logging in and creating account via OmniAuth authentication.
 test_files: []