thecore_auth_commons 3.5.13 → 3.5.14

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 9adb75c5f18c265f09ea114168ffef23573cb3331f0f9a2ed9b7ab87d46f3813
-  data.tar.gz: f25d391c389a2e521bf7e86314a68837e1ce3b92c028cec9a19492cb232e7160
+  metadata.gz: f66435a76d0089d6e52de71c3fc7239470ec7c91ca241ba242bce9a5d1bdea1d
+  data.tar.gz: b9130fc3d425a86abb0b8c83a0880aedc6be121a2cf634e2e5821320d2a27e2e
 SHA512:
-  metadata.gz: 569320497ba05528a7a972866aa3e2cb742139a331f25b66466786bb55fc8fe33933388fadce770b80d696c9eeb10fd5a63a811abda8d2122b32dc5830f50583
-  data.tar.gz: 730e678b864fe11d7b6dd40ab3a43a7dd44f591b3a34289d315fa29630eb6f0abab4d858195efd33d41bd7f3aeffac358e0f822f295d0a05e19d593a7df25897
+  metadata.gz: 5ac374cf84bf7220b9c74f27732bf1f4723b60f11970594c20f6ef9544b00e4e2eaef5e4c0170ea6cb515846958dd05b3ed5cc57f3366ba9fec175678550ad50
+  data.tar.gz: a55c49bb2b11e7486d3603b8f9719380cdb535f2dd1f36d1f746643afe6f269747cbaa51f6a8fed362db379426990bd6dbbfab352384f86826a466afd270f78f

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/lib/thecore_auth_commons/version.rb

@@ -1,3 +1,3 @@
 module ThecoreAuthCommons
-  VERSION = "3.5.13".freeze
+  VERSION = "3.5.14".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.14
 platform: ruby
 authors:
 - Gabriele Tassoni
@@ -215,16 +215,44 @@ dependencies:
   name: sqlite3
   requirement: !ruby/object:Gem::Requirement
     requirements:
-    - - "~>"
+    - - ">="
       - !ruby/object:Gem::Version
-        version: '1.4'
+        version: '0'
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
-    - - "~>"
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !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: '1.4'
+        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: