omniauth-identity 3.1.4 → 3.2.0

data/RUBOCOP.md

@@ -0,0 +1,71 @@
+# RuboCop Usage Guide
+
+## Overview
+
+A tale of two RuboCop plugin gems.
+
+### RuboCop Gradual
+
+This project uses `rubocop_gradual` instead of vanilla RuboCop for code style checking. The `rubocop_gradual` tool allows for gradual adoption of RuboCop rules by tracking violations in a lock file.
+
+### RuboCop LTS
+
+This project uses `rubocop-lts` to ensure, on a best-effort basis, compatibility with Ruby >= 1.9.2.
+RuboCop rules are meticulously configured by the `rubocop-lts` family of gems to ensure that a project is compatible with a specific version of Ruby. See: https://rubocop-lts.gitlab.io for more.
+
+## Checking RuboCop Violations
+
+To check for RuboCop violations in this project, always use:
+
+```bash
+bundle exec rake rubocop_gradual:check
+```
+
+**Do not use** the standard RuboCop commands like:
+- `bundle exec rubocop`
+- `rubocop`
+
+## Understanding the Lock File
+
+The `.rubocop_gradual.lock` file tracks all current RuboCop violations in the project. This allows the team to:
+
+1. Prevent new violations while gradually fixing existing ones
+2. Track progress on code style improvements
+3. Ensure CI builds don't fail due to pre-existing violations
+
+## Common Commands
+
+- **Check violations**
+    - `bundle exec rake rubocop_gradual`
+    - `bundle exec rake rubocop_gradual:check`
+- **(Safe) Autocorrect violations, and update lockfile if no new violations**
+  - `bundle exec rake rubocop_gradual:autocorrect`
+- **Force update the lock file (w/o autocorrect) to match violations present in code**
+  - `bundle exec rake rubocop_gradual:force_update`
+
+## Workflow
+
+1. Before submitting a PR, run `bundle exec rake rubocop_gradual:autocorrect`
+   a. or just the default `bundle exec rake`, as autocorrection is a pre-requisite of the default task.
+2. If there are new violations, either:
+   - Fix them in your code
+   - Run `bundle exec rake rubocop_gradual:force_update` to update the lock file (only for violations you can't fix immediately)
+3. Commit the updated `.rubocop_gradual.lock` file along with your changes
+
+## Never add inline RuboCop disables
+
+Do not add inline `rubocop:disable` / `rubocop:enable` comments anywhere in the codebase (including specs, except when following the few existing `rubocop:disable` patterns for a rule already being disabled elsewhere in the code). We handle exceptions in two supported ways:
+
+- Permanent/structural exceptions: prefer adjusting the RuboCop configuration (e.g., in `.rubocop.yml`) to exclude a rule for a path or file pattern when it makes sense project-wide.
+- Temporary exceptions while improving code: record the current violations in `.rubocop_gradual.lock` via the gradual workflow:
+  - `bundle exec rake rubocop_gradual:autocorrect` (preferred; will autocorrect what it can and update the lock only if no new violations were introduced)
+  - If needed, `bundle exec rake rubocop_gradual:force_update` (as a last resort when you cannot fix the newly reported violations immediately)
+
+In general, treat the rules as guidance to follow; fix violations rather than ignore them. For example, RSpec conventions in this project expect `described_class` to be used in specs that target a specific class under test.
+
+## Benefits of rubocop_gradual
+
+- Allows incremental adoption of code style rules
+- Prevents CI failures due to pre-existing violations
+- Provides a clear record of code style debt
+- Enables focused efforts on improving code quality over time

data/SECURITY.md

@@ -2,13 +2,9 @@
 
 ## Supported Versions
 
-| Version | Supported |
-|---------|-----------|
-| 3.1.x   | ✅         |
-| 3.0.x   | ❌         |
-| 2.x     | ❌         |
-| 1.x     | ❌         |
-| 0.x     | ❌         |
+| Version  | Supported |
+|----------|-----------|
+| 3.1.latest | ✅         |
 
 ## Security contact information
 
@@ -18,28 +14,8 @@ Tidelift will coordinate the fix and disclosure.
 
 ## Additional Support
 
-Interested in support for versions older than the latest release?
-Consider sponsoring the project / maintainer.
+If you are interested in support for versions older than the latest release,
+please consider sponsoring the project / maintainer @ https://liberapay.com/pboling/donate,
+or find other sponsorship links in the [README].
 
-[![Liberapay Goal Progress][⛳liberapay-img]][⛳liberapay] [![Sponsor Me on Github][🖇sponsor-img]][🖇sponsor] [![Buy me a coffee][🖇buyme-small-img]][🖇buyme] [![Donate on Polar][🖇polar-img]][🖇polar] [![Donate to my FLOSS or refugee efforts at ko-fi.com][🖇kofi-img]][🖇kofi] [![Donate to my FLOSS or refugee efforts using Patreon][🖇patreon-img]][🖇patreon]
-
-[⛳liberapay-img]: https://img.shields.io/liberapay/goal/pboling.svg?logo=liberapay
-[⛳liberapay]: https://liberapay.com/pboling/donate
-[🖇sponsor-img]: https://img.shields.io/badge/Sponsor_Me!-pboling.svg?style=social&logo=github
-[🖇sponsor]: https://github.com/sponsors/pboling
-[🖇polar-img]: https://img.shields.io/badge/polar-donate-yellow.svg
-[🖇polar]: https://polar.sh/pboling
-[🖇kofi-img]: https://img.shields.io/badge/a_more_different_coffee-✓-yellow.svg
-[🖇kofi]: https://ko-fi.com/O5O86SNP4
-[🖇patreon-img]: https://img.shields.io/badge/patreon-donate-yellow.svg
-[🖇patreon]: https://patreon.com/galtzo
-[🖇buyme]: https://www.buymeacoffee.com/pboling
-[🖇buyme-small-img]: https://img.shields.io/badge/buy_me_a_coffee-✓-yellow.svg?style=flat
-
-## Enterprise Support
-
-Available as part of the Tidelift Subscription.
-
-The maintainers of this library and thousands of other packages are working with Tidelift to deliver commercial support and maintenance for the open source packages you use to build your applications. Save time, reduce risk, and improve code health, while paying the maintainers for the exact packages you use. [Learn more.][tidelift-ref]
-
-[tidelift-ref]: https://tidelift.com/subscription/pkg/rubygems-omniauth-identity?utm_source=rubygems-omniauth-identity&utm_medium=referral&utm_campaign=enterprise&utm_term=repo
+[README]: README.md

data/certs/pboling.pem

@@ -0,0 +1,27 @@
+-----BEGIN CERTIFICATE-----
+MIIEgDCCAuigAwIBAgIBATANBgkqhkiG9w0BAQsFADBDMRUwEwYDVQQDDAxwZXRl
+ci5ib2xpbmcxFTATBgoJkiaJk/IsZAEZFgVnbWFpbDETMBEGCgmSJomT8ixkARkW
+A2NvbTAeFw0yNTA1MDQxNTMzMDlaFw00NTA0MjkxNTMzMDlaMEMxFTATBgNVBAMM
+DHBldGVyLmJvbGluZzEVMBMGCgmSJomT8ixkARkWBWdtYWlsMRMwEQYKCZImiZPy
+LGQBGRYDY29tMIIBojANBgkqhkiG9w0BAQEFAAOCAY8AMIIBigKCAYEAruUoo0WA
+uoNuq6puKWYeRYiZekz/nsDeK5x/0IEirzcCEvaHr3Bmz7rjo1I6On3gGKmiZs61
+LRmQ3oxy77ydmkGTXBjruJB+pQEn7UfLSgQ0xa1/X3kdBZt6RmabFlBxnHkoaGY5
+mZuZ5+Z7walmv6sFD9ajhzj+oIgwWfnEHkXYTR8I6VLN7MRRKGMPoZ/yvOmxb2DN
+coEEHWKO9CvgYpW7asIihl/9GMpKiRkcYPm9dGQzZc6uTwom1COfW0+ZOFrDVBuV
+FMQRPswZcY4Wlq0uEBLPU7hxnCL9nKK6Y9IhdDcz1mY6HZ91WImNslOSI0S8hRpj
+yGOWxQIhBT3fqCBlRIqFQBudrnD9jSNpSGsFvbEijd5ns7Z9ZMehXkXDycpGAUj1
+to/5cuTWWw1JqUWrKJYoifnVhtE1o1DZ+LkPtWxHtz5kjDG/zR3MG0Ula0UOavlD
+qbnbcXPBnwXtTFeZ3C+yrWpE4pGnl3yGkZj9SMTlo9qnTMiPmuWKQDatAgMBAAGj
+fzB9MAkGA1UdEwQCMAAwCwYDVR0PBAQDAgSwMB0GA1UdDgQWBBQE8uWvNbPVNRXZ
+HlgPbc2PCzC4bjAhBgNVHREEGjAYgRZwZXRlci5ib2xpbmdAZ21haWwuY29tMCEG
+A1UdEgQaMBiBFnBldGVyLmJvbGluZ0BnbWFpbC5jb20wDQYJKoZIhvcNAQELBQAD
+ggGBAJbnUwfJQFPkBgH9cL7hoBfRtmWiCvdqdjeTmi04u8zVNCUox0A4gT982DE9
+wmuN12LpdajxZONqbXuzZvc+nb0StFwmFYZG6iDwaf4BPywm2e/Vmq0YG45vZXGR
+L8yMDSK1cQXjmA+ZBKOHKWavxP6Vp7lWvjAhz8RFwqF9GuNIdhv9NpnCAWcMZtpm
+GUPyIWw/Cw/2wZp74QzZj6Npx+LdXoLTF1HMSJXZ7/pkxLCsB8m4EFVdb/IrW/0k
+kNSfjtAfBHO8nLGuqQZVH9IBD1i9K6aSs7pT6TW8itXUIlkIUI2tg5YzW6OFfPzq
+QekSkX3lZfY+HTSp/o+YvKkqWLUV7PQ7xh1ZYDtocpaHwgxe/j3bBqHE+CUPH2vA
+0V/FwdTRWcwsjVoOJTrYcff8pBZ8r2MvtAc54xfnnhGFzeRHfcltobgFxkAXdE6p
+DVjBtqT23eugOqQ73umLcYDZkc36vnqGxUBSsXrzY9pzV5gGr2I8YUxMqf6ATrZt
+L9nRqA==
+-----END CERTIFICATE-----

data/lib/omniauth/identity/model.rb

@@ -1,7 +1,11 @@
 # frozen_string_literal: true
 
+require "auth_sanitizer/loader"
+
 module OmniAuth
   module Identity
+    AUTH_SANITIZER = AuthSanitizer::Loader.load_isolated unless const_defined?(:AUTH_SANITIZER, false)
+
     # This module provides an include-able interface for implementing the
     # necessary API for OmniAuth Identity to properly locate identities
     # and provide all necessary information.
@@ -9,22 +13,41 @@ module OmniAuth
     # All methods marked as abstract must be implemented in the
     # including class for things to work properly.
     #
-    ### Singleton API
+    # ### Singleton API
     #
     # * locate(key)
     # * create(*args) - Deprecated in v3.0.5; Will be removed in v4.0
     #
-    ### Instance API
+    # ### Instance API
     #
     # * save
     # * persisted?
     # * authenticate(password)
     #
+    # @example Including the Model
+    #   class User
+    #     include OmniAuth::Identity::Model
+    #     # Implement required methods...
+    #   end
     module Model
+      # @!attribute [r] SCHEMA_ATTRIBUTES
+      # Standard OmniAuth schema attributes that may be stored in the model.
+      # @return [Array<String>] List of attribute names.
       SCHEMA_ATTRIBUTES = %w[name email nickname first_name last_name location description image phone].freeze
+      FILTERED_INSPECT_ATTRIBUTES = %i[password password_confirmation password_digest].freeze
 
       class << self
+        # Called when this module is included in a model class.
+        #
+        # Extends the base class with ClassMethods and includes necessary APIs
+        # if they are not already defined.
+        #
+        # @param base [Class] the model class including this module
+        # @return [void]
         def included(base)
+          base.include(OmniAuth::Identity::AUTH_SANITIZER::FilteredAttributes)
+          base.prepend(OmniAuth::Identity::AUTH_SANITIZER::FilteredAttributes)
+          base.filtered_attributes(*FILTERED_INSPECT_ATTRIBUTES)
           base.extend(ClassMethods)
           base.extend(ClassCreateApi) unless base.respond_to?(:create)
           i_methods = base.instance_methods
@@ -33,12 +56,16 @@ module OmniAuth
         end
       end
 
+      # Class-level methods for OmniAuth Identity models.
       module ClassMethods
+        AUTH_KEY_MUTEX = Mutex.new
+        private_constant :AUTH_KEY_MUTEX
+
         # Authenticate a user with the given key and password.
         #
         # @param [String] conditions The unique login key provided for a given identity.
         # @param [String] password The presumed password for the identity.
-        # @return [Model, false] An instance of the identity model class.
+        # @return [Model, false] An instance of the identity model class or false if authentication fails.
         def authenticate(conditions, password)
           instance = locate(conditions)
           return false unless instance
@@ -46,19 +73,28 @@ module OmniAuth
           instance.authenticate(password)
         end
 
+        def inherited(subclass)
+          super if defined?(super)
+          subclass.filtered_attributes(*filtered_attribute_names) if subclass.respond_to?(:filtered_attributes)
+        end
+
         # Used to set or retrieve the method that will be used to get
         # and set the user-supplied authentication key.
+        #
+        # @param method [String, Symbol, false] The method name to set, or false to retrieve.
         # @return [String] The method name.
         def auth_key(method = false)
-          @auth_key = method.to_s unless method == false
-          @auth_key = nil if !defined?(@auth_key) || @auth_key == ""
+          AUTH_KEY_MUTEX.synchronize do
+            @auth_key = method.to_s unless method == false
+            @auth_key = nil if !defined?(@auth_key) || @auth_key == ""
 
-          @auth_key || "email"
+            @auth_key || "email"
+          end
         end
 
         # Locate an identity given its unique login key.
         #
-        # @abstract
+        # @abstract Subclasses must implement this method.
         # @param [String] _key The unique login key.
         # @return [Model] An instance of the identity model class.
         def locate(_key)
@@ -66,6 +102,7 @@ module OmniAuth
         end
       end
 
+      # Provides a create method for models that don't have one.
       module ClassCreateApi
         # Persists a new Identity object to the ORM.
         # Only included if the class doesn't define create, as a reminder to define create.
@@ -81,6 +118,7 @@ module OmniAuth
         end
       end
 
+      # Provides a save method for models that don't have one.
       module InstanceSaveApi
         # Persists a new Identity object to the ORM.
         # Default raises an error.  Override as needed per ORM.
@@ -88,6 +126,7 @@ module OmniAuth
         #   since it is a pattern many ORMs follow
         #
         # @abstract
+        # @param _options [Hash] Options for saving.
         # @return [Model] An instance of the identity model class.
         # @since 3.0.5
         def save(**_options, &_block)
@@ -95,12 +134,13 @@ module OmniAuth
         end
       end
 
+      # Provides a persisted? method for models that don't have one.
       module InstancePersistedApi
         # Checks if the Identity object is persisted in the ORM.
         # Default raises an error.  Override as needed per ORM.
         #
         # @abstract
-        # @return [true or false] true if object exists, false if not.
+        # @return [true, false] true if object exists, false if not.
         # @since 3.0.5
         def persisted?
           raise NotImplementedError
@@ -110,9 +150,9 @@ module OmniAuth
       # Returns self if the provided password is correct, false
       # otherwise.
       #
-      # @abstract
+      # @abstract Subclasses must implement this method.
       # @param [String] _password The password to check.
-      # @return [self or false] Self if authenticated, false if not.
+      # @return [self, false] Self if authenticated, false if not.
       def authenticate(_password)
         raise NotImplementedError
       end
@@ -152,7 +192,7 @@ module OmniAuth
       # @param [String] value The value to which the auth key should be
       #   set.
       def auth_key=(value)
-        auth_key_setter = "#{self.class.auth_key}=".to_sym
+        auth_key_setter = :"#{self.class.auth_key}="
         if respond_to?(auth_key_setter)
           send(auth_key_setter, value)
         else

data/lib/omniauth/identity/models/active_record.rb

@@ -6,8 +6,34 @@ module OmniAuth
   module Identity
     module Models
       # ActiveRecord is an ORM for MySQL, PostgreSQL, and SQLite3:
-      #   https://guides.rubyonrails.org/active_record_basics.html
-      # NOTE: ActiveRecord is based on ActiveModel.
+      # https://guides.rubyonrails.org/active_record_basics.html
+      #
+      # This class provides a base for OmniAuth Identity models using ActiveRecord,
+      # including secure password handling and authentication key management.
+      #
+      # @example Usage
+      #   class User < OmniAuth::Identity::Models::ActiveRecord
+      #     # Add your fields here, e.g.:
+      #     # self.table_name = 'users'
+      #     # has_many :posts
+      #   end
+      #
+      #   # Migration example:
+      #   # create_table :users do |t|
+      #   #   t.string :email, null: false
+      #   #   t.string :password_digest, null: false
+      #   #   t.timestamps
+      #   # end
+      #
+      #   user = User.new(email: 'user@example.com', password: 'password')
+      #   user.save
+      #
+      #   # Authenticate a user
+      #   authenticated_user = User.locate(email: 'user@example.com')
+      #   authenticated_user.authenticate('password') # => user or false
+      #
+      # @note ActiveRecord is based on ActiveModel, so validations are enabled by default.
+      # @note This is an abstract class; inherit from it to create your user model.
       class ActiveRecord < ::ActiveRecord::Base
         include ::OmniAuth::Identity::Model
         include ::OmniAuth::Identity::SecurePassword
@@ -16,14 +42,34 @@ module OmniAuth
         # validations: true (default) incurs a dependency on ActiveModel, but ActiveRecord is ActiveModel based.
         has_secure_password
 
-        def self.auth_key=(key)
-          super
-          validates_uniqueness_of(key, case_sensitive: false)
-        end
+        # @!method self.auth_key=(key)
+        # Sets the authentication key for the model and adds uniqueness validation.
+        #
+        # @param key [Symbol, String] the attribute to use as the authentication key
+        # @return [void]
+        # @example
+        #   class User < OmniAuth::Identity::Models::ActiveRecord
+        #     self.auth_key = :email
+        #   end
+        class << self
+          def auth_key=(key)
+            super
+            validates_uniqueness_of(key, case_sensitive: false)
+          end
 
-        def self.locate(search_hash)
-          search_hash = search_hash.reverse_merge!("provider" => "identity") if column_names.include?("provider")
-          where(search_hash).first
+          # @!method self.locate(search_hash)
+          # Finds a record by the given search criteria.
+          #
+          # If the model has a 'provider' column, it defaults to 'identity'.
+          #
+          # @param search_hash [Hash] the attributes to search for
+          # @return [ActiveRecord::Base, nil] the first matching record or nil
+          # @example
+          #   User.locate(email: 'user@example.com')
+          def locate(search_hash)
+            search_hash = search_hash.reverse_merge!("provider" => "identity") if column_names.include?("provider")
+            where(search_hash).first
+          end
         end
       end
     end

data/lib/omniauth/identity/models/couch_potato.rb

@@ -6,30 +6,86 @@ module OmniAuth
   module Identity
     module Models
       # CouchPotato is an ORM adapter for CouchDB:
-      #   https://github.com/langalex/couch_potato
-      # NOTE: CouchPotato is based on ActiveModel.
-      # NOTE: CouchPotato::Persistence must be included before OmniAuth::Identity::Models::CouchPotatoModule
-      # NOTE: Includes "Module" in the name for invalid legacy reasons. Rename only with a major version bump.
+      # https://github.com/langalex/couch_potato
+      #
+      # This module provides OmniAuth Identity functionality for CouchPotato models,
+      # including secure password handling and authentication key management.
+      #
+      # @example Usage
+      #   class User
+      #     include CouchPotato::Persistence
+      #
+      #     include OmniAuth::Identity::Models::CouchPotatoModule
+      #
+      #     property :email
+      #     property :password_digest
+      #   end
+      #
+      #   user = User.new(email: 'user@example.com', password: 'password')
+      #   user.save
+      #
+      #   # Authenticate a user
+      #   authenticated_user = User.locate(email: 'user@example.com')
+      #   authenticated_user.authenticate('password') # => user or false
+      #
+      # @note CouchPotato is based on ActiveModel, so validations are enabled by default.
+      # @note CouchPotato::Persistence must be included before OmniAuth::Identity::Models::CouchPotatoModule.
+      # @note Includes "Module" in the name for invalid legacy reasons. Rename only with a major version bump.
       module CouchPotatoModule
-        def self.included(base)
-          base.class_eval do
-            include(::OmniAuth::Identity::Model)
-            include(::OmniAuth::Identity::SecurePassword)
+        class << self
+          # Called when this module is included in a model class.
+          #
+          # This method extends the base class with OmniAuth Identity functionality,
+          # including secure password support and authentication key validation.
+          #
+          # @param base [Class] the model class including this module
+          # @return [void]
+          def included(base)
+            base.class_eval do
+              include(::OmniAuth::Identity::Model)
+              include(::OmniAuth::Identity::SecurePassword)
 
-            # validations: true (default) incurs a dependency on ActiveModel, but CouchPotato is ActiveModel based.
-            has_secure_password
+              # validations: true (default) incurs a dependency on ActiveModel, but CouchPotato is ActiveModel based.
+              has_secure_password
 
-            def self.auth_key=(key)
-              super
-              validates_uniqueness_of(key, case_sensitive: false)
-            end
+              class << self
+                # @!method self.auth_key=(key)
+                # Sets the authentication key for the model and adds uniqueness validation.
+                #
+                # @param key [Symbol, String] the attribute to use as the authentication key
+                # @return [void]
+                # @example
+                #   class User
+                #     include OmniAuth::Identity::Models::CouchPotatoModule
+                #     self.auth_key = :email
+                #   end
+                def auth_key=(key)
+                  super
+                  validates_uniqueness_of(key, case_sensitive: false)
+                end
 
-            def self.locate(search_hash)
-              where(search_hash).first
-            end
+                # @!method self.locate(search_hash)
+                # Finds a record by the given search criteria.
+                #
+                # @param search_hash [Hash] the attributes to search for
+                # @return [Object, nil] the first matching record or nil
+                # @example
+                #   User.locate(email: 'user@example.com')
+                def locate(search_hash)
+                  where(search_hash).first
+                end
+              end
 
-            def save
-              CouchPotato.database.save_document(self)
+              # @!method save
+              # Saves the document to the CouchDB database.
+              #
+              # @return [Boolean] true if saved successfully, false otherwise
+              # @example
+              #   user = User.new(email: 'user@example.com', password: 'password')
+              #   user.save # => true
+              def save
+                CouchPotato.database.save_document(self)
+              end
             end
           end
         end

data/lib/omniauth/identity/models/mongoid.rb

@@ -6,24 +6,73 @@ module OmniAuth
   module Identity
     module Models
       # Mongoid is an ORM adapter for MongoDB:
-      #   https://github.com/mongodb/mongoid
-      # NOTE: Mongoid is based on ActiveModel.
+      # https://github.com/mongodb/mongoid
+      #
+      # This module provides OmniAuth Identity functionality for Mongoid models,
+      # including secure password handling and authentication key management.
+      #
+      # @example Usage
+      #   class User
+      #     include Mongoid::Document
+      #
+      #     include OmniAuth::Identity::Models::Mongoid
+      #
+      #     field :email, type: String
+      #     field :password_digest, type: String
+      #   end
+      #
+      #   user = User.new(email: 'user@example.com', password: 'password')
+      #   user.save
+      #
+      #   # Authenticate a user
+      #   authenticated_user = User.locate(email: 'user@example.com')
+      #   authenticated_user.authenticate('password') # => user or false
+      #
+      # @note Mongoid is based on ActiveModel, so validations are enabled by default.
       module Mongoid
-        def self.included(base)
-          base.class_eval do
-            include(::OmniAuth::Identity::Model)
-            include(::OmniAuth::Identity::SecurePassword)
+        class << self
+          # Called when this module is included in a model class.
+          #
+          # This method extends the base class with OmniAuth Identity functionality,
+          # including secure password support and authentication key validation.
+          #
+          # @param base [Class] the model class including this module
+          # @return [void]
+          def included(base)
+            base.class_eval do
+              include(::OmniAuth::Identity::Model)
+              include(::OmniAuth::Identity::SecurePassword)
 
-            # validations: true (default) incurs a dependency on ActiveModel, but Mongoid is ActiveModel based.
-            has_secure_password
+              # validations: true (default) incurs a dependency on ActiveModel, but Mongoid is ActiveModel based.
+              has_secure_password
 
-            def self.auth_key=(key)
-              super
-              validates_uniqueness_of(key, case_sensitive: false)
-            end
+              class << self
+                # @!method self.auth_key=(key)
+                # Sets the authentication key for the model and adds uniqueness validation.
+                #
+                # @param key [Symbol, String] the attribute to use as the authentication key
+                # @return [void]
+                # @example
+                #   class User
+                #     include OmniAuth::Identity::Models::Mongoid
+                #     self.auth_key = :email
+                #   end
+                def auth_key=(key)
+                  super
+                  validates_uniqueness_of(key, case_sensitive: false)
+                end
 
-            def self.locate(search_hash)
-              where(search_hash).first
+                # @!method self.locate(search_hash)
+                # Finds a record by the given search criteria.
+                #
+                # @param search_hash [Hash] the attributes to search for
+                # @return [Mongoid::Document, nil] the first matching record or nil
+                # @example
+                #   User.locate(email: 'user@example.com')
+                def locate(search_hash)
+                  where(search_hash).first
+                end
+              end
             end
           end
         end