cognito_idp_rails 1.0.0 → 1.1.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: f2e90ec3ceff76f7525a0cb71ab3f0457fef60d32cfe41fe5d4f27a3a2b0e916
-  data.tar.gz: 62218081d1ebd666aa06280a31b2e2ae8a587a3abe5858b086bcabaebdc6aaf2
+  metadata.gz: cd19a4834a4a544ed409f858802b2587ceb41238b760000f99c64f225e8aa75a
+  data.tar.gz: 314efa955ed11cf93b4001acd66bbcd57e91310fc24999760c4ea4b844a43bff
 SHA512:
-  metadata.gz: '0793b32cdb97929f1cc53a49a51b087efb6a9053e380e4aae97ba58b42310a86227fe87f82bd5e3a25d1e668499ad0643519d470cf24761ef6a12355adeff9c1'
-  data.tar.gz: 34e1e1c5930521393a61c4ed1b04da405035d8c58b6f8da845db1c871a87237ded53b4d2fddd9a0dfc17d7dc4c912f107618f82925b12edefc42090f22daf534
+  metadata.gz: '0903452da2cff398668f3494f10ba811bed64cd34c90726da50bcaaa307107413d609aceb644c3301ca45912f43435c14e294d4d4e6b39465869a69588e9c286'
+  data.tar.gz: bd52e9bbc6bf2d313f9931d1bd63fddd9a0faf81e7f3c20aef0d173c9a07af5936e0d7964fea0b2624c6e7f3df1f381cf60bab38f53269f606e1d835e6e3cbff

data/README.md

@@ -1,6 +1,12 @@
-# CognitoIdpRails
+# CognitoIdpRails [![Ruby](https://github.com/appercept/cognito_idp_rails/actions/workflows/main.yml/badge.svg)](https://github.com/appercept/cognito_idp_rails/actions/workflows/main.yml)
 
-Simple integration of Amazon Cognito IdP (User Pools) for Rails applications.
+Simple integration of Amazon Cognito IdP (User Pools) for Rails applications. Provides OAuth + PKCE authentication with sensible defaults and minimal configuration.
+
+## Requirements
+
+- Ruby >= 3.2.0
+- Rails >= 7.0.0
+- [cognito_idp](https://github.com/appercept/cognito_idp) ~> 1.0 (installed automatically)
 
 ## Installation
 
@@ -12,17 +18,100 @@ If bundler is not being used to manage dependencies, install the gem by executin
 
     $ gem install cognito_idp_rails
 
-## Usage
+## Setup
 
-After adding the gem to your application, run the install generator:
+Run the install generator:
 
     $ rails generate cognito_idp_rails:install
 
-This generator will add `cognito_idp` to your routes and install an initializer at `config/initializers/cognito_idp.rb`.
-
-Be sure to review and edit the initializer to configure options for your Amazon Cognito User Pool configuration. You
-must also provide an implementation for the `after_login` function in the initializer appropriate for any actions you
-want to take when a user signed in.
+This will:
+
+1. Add a `cognito_idp` route entry to `config/routes.rb`
+2. Create an initializer at `config/initializers/cognito_idp.rb`
+
+Review and edit the initializer to match your Amazon Cognito User Pool configuration.
+
+## Configuration
+
+```ruby
+CognitoIdpRails.configure do |config|
+  config.domain = ENV["COGNITO_DOMAIN"]
+  config.client_id = ENV["COGNITO_CLIENT_ID"]
+  config.client_secret = ENV["COGNITO_CLIENT_SECRET"]
+
+  config.scope = "openid"          # OAuth scope(s)
+  config.after_login_route = "/"   # Redirect after login
+  config.after_logout_route = "/"  # Redirect after logout
+
+  config.after_login = lambda do |token, user_info, request|
+    user = User.where(identifier: user_info.sub).first_or_create do |u|
+      u.email = user_info.email
+    end
+    request.session[:user_id] = user.id
+  end
+
+  config.before_logout = lambda do |request|
+    # Runs before the session is reset on logout
+  end
+
+  config.on_login_error = lambda do |error, request|
+    # Runs when token exchange or user info retrieval fails
+    Rails.logger.error("Login failed: #{error.message}")
+  end
+end
+```
+
+### Options
+
+| Option | Required | Default | Description |
+|---|---|---|---|
+| `domain` | Yes | — | Your Cognito User Pool domain (e.g. `your-app.auth.us-east-1.amazoncognito.com`) |
+| `client_id` | Yes | — | The app client ID from your Cognito User Pool |
+| `client_secret` | Yes | — | The app client secret from your Cognito User Pool |
+| `scope` | No | `"openid"` | OAuth scope(s) to request |
+| `after_login_route` | No | `"/"` | Path to redirect to after login |
+| `after_logout_route` | No | `"/"` | Path to redirect to after logout |
+| `after_login` | No | no-op | `lambda { \|token, user_info, request\| }` — called after successful authentication |
+| `before_logout` | No | no-op | `lambda { \|request\| }` — called before session reset on logout |
+| `on_login_error` | No | no-op | `lambda { \|error, request\| }` — called when login fails (receives a `CognitoIdp::Error`) |
+
+## Routes
+
+The `cognito_idp` route helper adds four routes:
+
+| Route | Controller Action | Purpose |
+|---|---|---|
+| `GET /login` | `sessions#login` | Redirects to Cognito authorization endpoint |
+| `GET /auth/login_callback` | `sessions#login_callback` | Handles the OAuth callback from Cognito |
+| `GET /logout` | `sessions#logout` | Redirects to Cognito logout endpoint |
+| `GET /auth/logout_callback` | `sessions#logout_callback` | Handles the logout callback from Cognito |
+
+## How it works
+
+CognitoIdpRails implements the OAuth 2.0 Authorization Code flow with PKCE (Proof Key for Code Exchange):
+
+1. User visits `/login`
+2. A PKCE code verifier/challenge pair and CSRF state token are generated and stored in the session
+3. User is redirected to your Cognito User Pool's authorization endpoint
+4. After authenticating with Cognito, the user is redirected back to `/auth/login_callback`
+5. The CSRF state is verified, and the authorization code is exchanged for tokens using the PKCE code verifier
+6. User info is fetched from Cognito using the access token
+7. The session is reset, the `after_login` callback is called, and the user is redirected to `after_login_route`
+
+On logout, the user is redirected to Cognito's logout endpoint, then back to `/auth/logout_callback` where `before_logout` is called and the session is reset.
+
+## Customizing flash messages (i18n)
+
+Flash messages are set via i18n. Override them in your application's locale files:
+
+```yaml
+en:
+  cognito_idp_rails:
+    sessions:
+      login_success: "You have been successfully logged in."
+      login_failed: "Login failed."
+      logout_success: "You have been successfully logged out."
+```
 
 ## Development
 

data/app/controllers/cognito_idp_rails/sessions_controller.rb

@@ -9,15 +9,16 @@ module CognitoIdpRails
     end
 
     def login_callback
-      client.get_token(grant_type: :authorization_code, code: params[:code], redirect_uri: auth_login_callback_url) do |token|
-        client.get_user_info(token) do |user_info|
-          reset_session
-          configuration.after_login.call(token, user_info, request)
-          redirect_to configuration.after_login_route, notice: "You have been successfully logged in."
-          return
-        end
-      end
-      redirect_to configuration.after_login_route, notice: "Login failed."
+      verifier = session.delete(:code_verifier)
+      session.delete(:login_state)
+      token = client.get_token(grant_type: :authorization_code, code: params[:code], redirect_uri: auth_login_callback_url, code_verifier: verifier)
+      user_info = client.get_user_info(token)
+      reset_session
+      configuration.after_login.call(token, user_info, request)
+      redirect_to configuration.after_login_route, notice: I18n.t("cognito_idp_rails.sessions.login_success")
+    rescue CognitoIdp::Error => e
+      configuration.on_login_error.call(e, request)
+      redirect_to configuration.after_login_route, notice: I18n.t("cognito_idp_rails.sessions.login_failed")
     end
 
     def logout
@@ -27,13 +28,19 @@ module CognitoIdpRails
     def logout_callback
       configuration.before_logout.call(request)
       reset_session
-      redirect_to configuration.after_logout_route, notice: "You have been successfully logged out."
+      redirect_to configuration.after_logout_route, notice: I18n.t("cognito_idp_rails.sessions.logout_success")
     end
 
     private
 
     def authorization_url
-      client.authorization_uri(redirect_uri: auth_login_callback_url, scope: scope, state: login_state)
+      client.authorization_uri(
+        redirect_uri: auth_login_callback_url,
+        scope: scope,
+        state: login_state,
+        code_challenge: code_challenge,
+        code_challenge_method: "S256"
+      )
     end
 
     def client
@@ -48,6 +55,14 @@ module CognitoIdpRails
       configuration.scope
     end
 
+    def code_verifier
+      session[:code_verifier] ||= SecureRandom.urlsafe_base64(32)
+    end
+
+    def code_challenge
+      Base64.urlsafe_encode64(Digest::SHA256.digest(code_verifier), padding: false)
+    end
+
     def login_state
       session[:login_state] ||= SecureRandom.urlsafe_base64
     end
@@ -55,7 +70,7 @@ module CognitoIdpRails
     def verify_state
       return if params[:state] == login_state
 
-      redirect_to configuration.after_login_route, notice: "Login failed."
+      redirect_to configuration.after_login_route, notice: I18n.t("cognito_idp_rails.sessions.login_failed")
     end
   end
 end

data/config/locales/en.yml

@@ -0,0 +1,6 @@
+en:
+  cognito_idp_rails:
+    sessions:
+      login_success: "You have been successfully logged in."
+      login_failed: "Login failed."
+      logout_success: "You have been successfully logged out."

data/lib/cognito_idp_rails/configuration.rb

@@ -1,13 +1,24 @@
 module CognitoIdpRails
   class Configuration
     attr_accessor :after_login_route, :after_logout_route, :domain, :client_id,
-      :client_secret, :after_login, :before_logout, :scope
+      :client_secret, :after_login, :before_logout, :on_login_error, :scope
+
+    REQUIRED_ATTRIBUTES = %i[domain client_id client_secret].freeze
 
     def initialize
       @after_login_route = "/"
       @after_logout_route = "/"
       @after_login = lambda { |token, user_info, request| }
       @before_logout = lambda { |request| }
+      @on_login_error = lambda { |error, request| }
+      @scope = "openid"
+    end
+
+    def validate!
+      missing = REQUIRED_ATTRIBUTES.select { |attr| public_send(attr).nil? }
+      return if missing.empty?
+
+      raise ConfigurationError, "Missing required configuration: #{missing.join(", ")}"
     end
   end
 end

data/lib/cognito_idp_rails/version.rb

@@ -1,3 +1,3 @@
 module CognitoIdpRails
-  VERSION = "1.0.0"
+  VERSION = "1.1.0"
 end

data/lib/cognito_idp_rails.rb

@@ -3,6 +3,8 @@ require "cognito_idp_rails/version"
 require "cognito_idp"
 
 module CognitoIdpRails
+  class ConfigurationError < StandardError; end
+
   autoload :Configuration, "cognito_idp_rails/configuration"
 
   module Routing
@@ -11,11 +13,14 @@ module CognitoIdpRails
 
   class << self
     def client
-      @client ||= CognitoIdp::Client.new(
-        client_id: configuration.client_id,
-        client_secret: configuration.client_secret,
-        domain: configuration.domain
-      )
+      @client ||= begin
+        configuration.validate!
+        CognitoIdp::Client.new(
+          client_id: configuration.client_id,
+          client_secret: configuration.client_secret,
+          domain: configuration.domain
+        )
+      end
     end
 
     def configuration

metadata

@@ -1,29 +1,28 @@
 --- !ruby/object:Gem::Specification
 name: cognito_idp_rails
 version: !ruby/object:Gem::Version
-  version: 1.0.0
+  version: 1.1.0
 platform: ruby
 authors:
 - Richard Hatherall
-autorequire:
 bindir: bin
 cert_chain: []
-date: 2023-12-14 00:00:00.000000000 Z
+date: 1980-01-02 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: cognito_idp
   requirement: !ruby/object:Gem::Requirement
     requirements:
-    - - ">="
+    - - "~>"
       - !ruby/object:Gem::Version
-        version: 0.1.1
+        version: '1.0'
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
-    - - ">="
+    - - "~>"
       - !ruby/object:Gem::Version
-        version: 0.1.1
+        version: '1.0'
 - !ruby/object:Gem::Dependency
   name: rails
   requirement: !ruby/object:Gem::Requirement
@@ -56,8 +55,8 @@ files:
 - app/helpers/cognito_idp_rails/application_helper.rb
 - app/jobs/cognito_idp_rails/application_job.rb
 - app/mailers/cognito_idp_rails/application_mailer.rb
-- app/models/cognito_idp_rails/application_record.rb
 - app/views/layouts/cognito_idp_rails/application.html.erb
+- config/locales/en.yml
 - config/routes.rb
 - lib/cognito_idp_rails.rb
 - lib/cognito_idp_rails/configuration.rb
@@ -74,7 +73,6 @@ metadata:
   homepage_uri: https://github.com/appercept/cognito_idp_rails
   source_code_uri: https://github.com/appercept/cognito_idp_rails
   changelog_uri: https://github.com/appercept/cognito_idp_rails/CHANGELOG.md
-post_install_message:
 rdoc_options: []
 require_paths:
 - lib
@@ -82,15 +80,14 @@ required_ruby_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
-      version: 2.6.0
+      version: 3.2.0
 required_rubygems_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.4.10
-signing_key:
+rubygems_version: 3.7.2
 specification_version: 4
 summary: Simple Rails integration for Amazon Cognito IdP (User Pools)
 test_files: []

data/app/models/cognito_idp_rails/application_record.rb

@@ -1,5 +0,0 @@
-module CognitoIdpRails
-  class ApplicationRecord < ActiveRecord::Base
-    self.abstract_class = true
-  end
-end