thecore_auth_commons 3.5.13 → 3.5.15

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 9adb75c5f18c265f09ea114168ffef23573cb3331f0f9a2ed9b7ab87d46f3813
-  data.tar.gz: f25d391c389a2e521bf7e86314a68837e1ce3b92c028cec9a19492cb232e7160
+  metadata.gz: 2a5d019d73046f1ba808347236d3e26474d57f7f72c15e5f616d667271d6164e
+  data.tar.gz: bd140a9026819eaca4e6fe0759ade000115b5aa74785ade45d9963985eb753cb
 SHA512:
-  metadata.gz: 569320497ba05528a7a972866aa3e2cb742139a331f25b66466786bb55fc8fe33933388fadce770b80d696c9eeb10fd5a63a811abda8d2122b32dc5830f50583
-  data.tar.gz: 730e678b864fe11d7b6dd40ab3a43a7dd44f591b3a34289d315fa29630eb6f0abab4d858195efd33d41bd7f3aeffac358e0f822f295d0a05e19d593a7df25897
+  metadata.gz: 96510a81f013f4ad7503844d9daf60c2f7292b038c43cb245d8fe519c164eadaeab710022593a75a8fd61322f9842c2e2019505dfdc39a524745d8c829bce7fc
+  data.tar.gz: d2992fec30b632567a9781fe5d3af2d479f6829d6390ee25403f2da932a611ecaf57c915a00606e8b010bc3e7b62803ca5375e3c2ed4e4a4e1f566d7264bfdfb

data/README.md

@@ -1,6 +1,127 @@
-This is part of Thecore framework: https://github.com/gabrieletassoni/thecore/tree/release/3
+# thecore_auth_commons
 
-It exposes two Env vars to chage the behaviour of Devise at startup:
+Part of the [Thecore framework](https://github.com/gabrieletassoni/thecore/tree/release/3).
 
-- MIN_PASSWORD_LENGTH: the minimum length of the password (default: 8)
-- SESSION_TIMEOUT_IN_MINUTES: the session timeout in minutes (default: 30)
+Provides authentication and role-based authorization for Rails applications in the Thecore ecosystem. Integrates Devise (local + LDAP + OAuth2), CanCanCan with database-driven permissions, and LDAP user synchronization.
+
+## Features
+
+- **Devise authentication** — local credentials, LDAP, Microsoft Entra ID (Azure AD), Google OAuth2
+- **Role-based authorization** — roles assigned to users; permissions (predicate + action + target) assigned to roles; resolved at runtime by CanCanCan
+- **LDAP sync** — import users and groups from one or more LDAP/AD servers; group membership maps to Roles
+- **Dynamic SMTP-less** — no restart needed to update auth settings; reads from ThecoreSettings at runtime
+
+## Environment variables
+
+| Variable | Default | Purpose |
+|---|---|---|
+| `MIN_PASSWORD_LENGTH` | `8` | Minimum password length enforced by Devise |
+| `SESSION_TIMEOUT_IN_MINUTES` | `31` | Idle session timeout |
+| `ENTRA_CLIENT_ID` | — | Microsoft Entra ID (Azure AD) OAuth2 client ID |
+| `ENTRA_CLIENT_SECRET` | — | Microsoft Entra ID OAuth2 client secret |
+| `ENTRA_TENANT_ID` | — | Microsoft Entra ID tenant ID |
+| `GOOGLE_CLIENT_ID` | — | Google OAuth2 client ID |
+| `GOOGLE_CLIENT_SECRET` | — | Google OAuth2 client secret |
+| `BASE_DOMAIN` | `example.com` | Used to build the default admin email at seed time |
+| `ADMIN_PASSWORD` | `Change#1` | Default admin password at seed time |
+
+OmniAuth providers are registered only when their respective env vars are all present.
+
+## Authorization model
+
+```
+User ──< RoleUser >── Role ──< PermissionRole >── Permission
+                                                       │
+                                                 ┌─────┼─────┐
+                                              Predicate Action Target
+```
+
+### Tables
+
+| Table | Content |
+|---|---|
+| `predicates` | `can`, `cannot` |
+| `actions` | `manage`, `create`, `read`, `update`, `destroy` |
+| `targets` | `all`, plus one row per `ApplicationRecord` subclass (underscore-cased) |
+| `permissions` | Combination of one predicate + one action + one target (unique triplet) |
+| `permission_roles` | Join between `permissions` and `roles` |
+| `roles` | Named roles |
+| `role_users` | Join between `roles` and `users` |
+
+### How permissions are resolved
+
+At login, `Ability#initialize` runs three layers in order (CanCan **last-wins**):
+
+1. `Abilities::ThecoreAuthCommons` — hardcoded base: admins get `can :manage, :all`; nobody can `create Action`; no one can destroy their own User record.
+2. All other `Abilities::*` modules defined in the host app or other engines.
+3. Database-driven permissions — every `Permission` linked to the current user (via their roles) is translated into a live CanCan call:
+
+```ruby
+self.send(predicate.name, action.name, target.name.classify.constantize)
+# e.g.  can(:manage, Task)  /  cannot(:destroy, User)
+```
+
+Permissions are applied in ascending `id` order, so a later `cannot` can override an earlier `can`.
+
+### Seeding
+
+`db/seeds.rb` populates the three vocabulary tables on first run:
+
+```ruby
+predicates: [:can, :cannot]
+actions:    [:manage, :create, :read, :update, :destroy]
+targets:    ["all"] + ApplicationRecord.subclasses.map { |m| m.to_s.underscore }
+```
+
+It also creates the first admin user (`admin@BASE_DOMAIN` / `ADMIN_PASSWORD`) if no admin exists yet.
+
+To add a permission via console:
+
+```ruby
+perm = Permission.create!(
+  predicate: Predicate.find_by(name: "can"),
+  action:    Action.find_by(name: "manage"),
+  target:    Target.find_by(name: "task")
+)
+role = Role.find_or_create_by(name: "manager")
+PermissionRole.create!(role: role, permission: perm)
+user.roles << role
+```
+
+## Authentication flow
+
+### Local + LDAP fallback
+
+`Users::SessionsController#create` tries Devise first; if that fails it tries `Ldap::Authenticator`. On successful LDAP auth the user is created/updated via `ThecoreAuthCommons.align_user` and signed in.
+
+### LDAP servers (`LdapServer` model)
+
+Multiple servers are supported, ordered by `priority` (ascending). Each server configures:
+
+- `host`, `port`, `use_ssl`, `base_dn`, `admin_user`, `admin_password`
+- `auth_field` — LDAP attribute used as login (e.g. `mail`, `sAMAccountName`)
+- `name`, `surname`, `phone`, `code` — LDAP attributes mapped to User fields
+
+On LDAP login or import, `memberOf` groups are read; matching group names become `Role` records assigned to the user. Groups named `Administrators`, `Domain Admins`, `Schema Admins`, `Enterprise Admins`, `admins`, or `administrators` also grant `user.admin = true`.
+
+Deleting a `LdapServer` record destroys all users whose `auth_source` is `"ldap #{id}"`.
+
+### Background LDAP import
+
+`BackgroundLdapImportJob` calls `ThecoreAuthCommons.import_ldap_users_task`, which iterates all `LdapServer` records and upserts matching users. Uses the same queue name as the host app (`#{COMPOSE_PROJECT_NAME}_default`).
+
+### OAuth2 (Entra ID / Google)
+
+Handled by `Users::OmniauthCallbacksController`. On callback, `ThecoreAuthCommons.check_user` finds or creates the user (with a random secure password) and sets `auth_source` to `'google'` or `'microsoft'`. New OAuth users are created as admin.
+
+## Password policy
+
+Passwords must contain at least one uppercase letter, one lowercase letter, one digit, and one special character. Minimum length is controlled by `MIN_PASSWORD_LENGTH`.
+
+`ThecoreAuthCommons.generate_secure_password(length = 20)` generates a compliant random password (used for LDAP/OAuth users who never type their password locally).
+
+## User model validations
+
+- Cannot remove admin flag from the last remaining admin.
+- Cannot lock the last non-locked account.
+- Email must match a standard address format and be unique (case-insensitive).

data/app/models/concerns/api/ldap_server.rb

@@ -12,7 +12,9 @@ module Api::LdapServer
     # - methods: include the result of some method defined in the model
     # - include: include associated models, it's an object {} which also accepts the keys described here
     cattr_accessor :json_attrs
-    self.json_attrs = ::ModelDrivenApi.smart_merge (json_attrs || {}), {}
+    # No ::ModelDrivenApi.smart_merge here: this is the lowest Thecore layer and model_driven_api
+    # (which sits above it) is not a dependency; merging {} was a no-op anyway.
+    self.json_attrs = json_attrs || {}
 
     # Custom action callable by the API must be defined in /app/models/concerns/endpoints/
   end

data/app/models/concerns/rails_admin/ldap_server.rb

@@ -2,9 +2,13 @@ module RailsAdmin::LdapServer
   extend ActiveSupport::Concern
 
   included do
-    rails_admin do
-      navigation_label I18n.t('admin.settings.label')
-      navigation_icon 'fa fa-passport'
+    # rails_admin is not a dependency of this gem (thecore_ui_rails_admin, a layer above, brings
+    # it): configure only when RailsAdmin is loaded, so apps/dummies without it can load the model.
+    if respond_to?(:rails_admin)
+      rails_admin do
+        navigation_label I18n.t('admin.settings.label')
+        navigation_icon 'fa fa-passport'
+      end
     end
   end
 end

data/lib/thecore_auth_commons/version.rb

@@ -1,3 +1,3 @@
 module ThecoreAuthCommons
-  VERSION = "3.5.13".freeze
+  VERSION = "3.5.15".freeze
 end

data/lib/thecore_auth_commons.rb

@@ -1,6 +1,11 @@
 require "devise"
 require "cancancan"
 require "kaminari"
+# activerecord-nulldb-adapter reaches into ActiveRecord::ConnectionAdapters internals
+# (e.g. SqlTypeMetadata::Deduplicable) that aren't necessarily loaded yet under a bare,
+# non-Rails-booted `require` chain (e.g. model_driven_api's plain minitest path) — make sure
+# ActiveRecord itself is fully loaded first.
+require "active_record"
 require "activerecord-nulldb-adapter"
 require "thecore_settings"
 require "net/ldap"

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: thecore_auth_commons
 version: !ruby/object:Gem::Version
-  version: 3.5.13
+  version: 3.5.15
 platform: ruby
 authors:
 - Gabriele Tassoni
@@ -212,19 +212,47 @@ dependencies:
       - !ruby/object:Gem::Version
         version: '2.18'
 - !ruby/object:Gem::Dependency
-  name: sqlite3
+  name: pg
   requirement: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '1.4'
+        version: '1.1'
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '1.4'
+        version: '1.1'
+- !ruby/object:Gem::Dependency
+  name: actionmailer
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: activestorage
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
 description: Provides common User and Role models to attach Authentication and Authorization
   via your preferred gem.
 email: