Update README: document auto-registration, test helpers, active_for_authentication guard, redirect_uri, custom views

- Remove outdated devise.rb manual setup step (engine handles it)
- Add 'What the engine does automatically' section
- Add redirect_uri to config example and option table
- Document active_for_authentication? guard in sign-in flow
- Add 'Custom login view' section (host views take precedence)
- Add 'Testing' section with test helpers, CI job pattern
- Reduce setup checklist from 4 items to 3

Author: Fivell

README.md

@@ -1,253 +1,174 @@
-# activeadmin-oidc
+# Welcome to YETI
+![Tests](https://github.com/yeti-switch/yeti-web/workflows/Tests/badge.svg?branch=master)
+![Coverage Status](https://img.shields.io/badge/Code%20Coverage-87%25-success?style=flat)
+[![Made in Ukraine](https://img.shields.io/badge/made_in-ukraine-ffd700.svg?labelColor=0057b7)](https://stand-with-ukraine.pp.ua)
 
-[![CI](https://github.com/activeadmin-plugins/activeadmin-oidc/actions/workflows/ci.yml/badge.svg)](https://github.com/activeadmin-plugins/activeadmin-oidc/actions/workflows/ci.yml)
 
-OpenID Connect single sign-on for [ActiveAdmin](https://activeadmin.info/).
+[![Stand With Ukraine](https://raw.githubusercontent.com/vshymanskyy/StandWithUkraine/main/banner-direct-team.svg)](https://stand-with-ukraine.pp.ua)
 
-Plugs OIDC into ActiveAdmin's existing Devise stack: JIT user provisioning, an `on_login` hook for host-owned authorization, a login-button view override, and a one-shot install generator. The OIDC protocol layer (discovery, JWKS, token verification, PKCE, nonce, state) is delegated to [`omniauth_openid_connect`](https://github.com/omniauth/omniauth_openid_connect).
 
-Used in production by the authors against [Zitadel](https://zitadel.com/). Other compliant OIDC providers work via the standard omniauth_openid_connect options.
+# Contributing, Development setup
 
-## Installation
+## Ruby
 
-```ruby
-# Gemfile
-gem "activeadmin-oidc"
-```
-
-```sh
-bundle install
-bin/rails generate active_admin:oidc:install
-bin/rails db:migrate
-```
+You have to use Ruby version 3.3.9 with installed bundler.
 
-## Host-app setup checklist
+## Postgresql
 
-The generator creates the initializer and migration, but it cannot edit your `active_admin.rb` or `admin_user.rb`. Four things have to be in place:
+It is strongly recommended to use PostgreSQL version 16.
+The easiest way to install it - is to use Debian Linux and follow official PostgreSQL instruction
+https://www.postgresql.org/download/linux/debian/
 
-### 1. `config/initializers/active_admin.rb`
+You need to install:
 
-```ruby
-config.authentication_method = :authenticate_admin_user!
-config.current_user_method   = :current_admin_user
+```sh
+curl https://pkg.yeti-switch.org/key.gpg | sudo apt-key add -
+curl https://www.postgresql.org/media/keys/ACCC4CF8.asc	| sudo apt-key add -
+sudo add-apt-repository "deb http://pkg.yeti-switch.org/debian/buster unstable main"
+sudo add-apt-repository "deb http://deb.debian.org/debian buster main buster non-free"
+sudo add-apt-repository "deb http://apt.postgresql.org/pub/repos/apt/ buster-pgdg main"
+sudo apt-get install postgresql-16 postgresql-contrib-13 postgresql-16-prefix postgresql-16-pgq3 postgresql-16-pgq-ext postgresql-16-yeti postgresql-16-pllua
+sudo apt-get install -t buster-pgdg libpq-dev
 ```
+In addition you need to compile or install from .deb package Yeti PostgreSQL extension `postgresql-16-yeti` https://github.com/yeti-switch/yeti-pg-ext
 
-Without these, `/admin` is public to anyone and the utility navigation (including the logout button) renders empty.
-
-### 2. `app/models/admin_user.rb`
+## Preparing yeti-web application
 
-```ruby
-class AdminUser < ApplicationRecord
-  devise :database_authenticatable,
-         :rememberable,
-         :omniauthable, omniauth_providers: [:oidc]
+Fork and clone yeti-web repository and run:
 
-  serialize :oidc_raw_info, coder: JSON
-end
+```sh
+bundle install
 ```
 
-### 3. `config/initializers/devise.rb`
-
-ActiveAdmin mounts Devise under `/admin`, so OmniAuth's path prefix has to match:
-
-```ruby
-config.omniauth_path_prefix = "/admin/auth"
-```
+Then create `config/database.yml`, example is `config/database.yml.development`. Notice this project uses two databases main "yeti" and second database "cdr"
 
-### 4. `config/initializers/activeadmin_oidc.rb` (generated)
+Then create `config/yeti_web.yml`, example is `config/yeti_web.yml.development`.
+Then create `config/secrets.yml`, example is `config/secrets.yml.distr`.
 
-Fill in at minimum `issuer`, `client_id`, and an `on_login` hook. Full reference below.
+To disable the creation of new versions via paper_trail for some model please fill the array under key `versioning_disable_for_models` in the `config/yeti_web.yml`
 
-## Configuration
+Сreate `config/policy_roles.yml`, example is `config/policy_roles.yml.distr` or disable policy feature by changing following lines in `config/yeti_web.yml`:
 
-```ruby
-ActiveAdmin::Oidc.configure do |c|
-  # --- Provider endpoints -----------------------------------------------
-  c.issuer        = ENV.fetch("OIDC_ISSUER")
-  c.client_id     = ENV.fetch("OIDC_CLIENT_ID")
-  c.client_secret = ENV.fetch("OIDC_CLIENT_SECRET", nil) # blank ⇒ PKCE public client
-
-  # --- OIDC scopes ------------------------------------------------------
-  # c.scope = "openid email profile"
-
-  # --- Identity lookup --------------------------------------------------
-  # Which AdminUser column to match existing rows against, and which
-  # claim on the id_token/userinfo to read for the lookup.
-  # c.identity_attribute = :email
-  # c.identity_claim     = :email
-
-  # --- AdminUser model resolution ---------------------------------------
-  # Accepts a String (lazy constant lookup, recommended) or a Class.
-  # Use when your model is not literally ::AdminUser.
-  # c.admin_user_class = "Admin::User"
-
-  # --- UI copy ----------------------------------------------------------
-  # c.login_button_label    = "Sign in with Corporate SSO"
-  # c.access_denied_message = "Your account has no permission to access this admin panel."
-
-  # --- PKCE override ----------------------------------------------------
-  # By default PKCE is enabled iff client_secret is blank. Override:
-  # c.pkce = true
-
-  # --- Authorization hook (REQUIRED) ------------------------------------
-  c.on_login = ->(admin_user, claims) {
-    # ... see "The on_login hook" below
-    true
-  }
-end
+```yaml
+role_policy:
+  when_no_config: allow
+  when_no_policy_class: allow
 ```
 
-### Option reference
+And run command to create development database:
 
-| Option | Default | Purpose |
-|---|---|---|
-| `issuer` | — (required) | OIDC discovery base URL |
-| `client_id` | — (required) | IdP client identifier |
-| `client_secret` | `nil` | Blank ⇒ PKCE public client |
-| `scope` | `"openid email profile"` | Space-separated OIDC scopes |
-| `pkce` | auto | `true` when `client_secret` is blank; overridable |
-| `identity_attribute` | `:email` | AdminUser column used for lookup/adoption |
-| `identity_claim` | `:email` | Claim key read from the id_token/userinfo |
-| `admin_user_class` | `"AdminUser"` | String or Class for the host's admin user model |
-| `login_button_label` | `"Sign in with SSO"` | Label on the login-page button |
-| `access_denied_message` | generic | Flash shown on any denial |
-| `on_login` | — (required) | Authorization hook; see below |
+```sh
+RAILS_ENV=development bundle exec rake db:create db:schema:load db:migrate db:seed
+RAILS_ENV=development bundle exec rake custom_seeds[network_prefixes]
+```
 
-## The `on_login` hook
+You can skip `custom_seeds[network_prefixes]` is you want to use your own network prefixes.
 
-`on_login` is the **only** place authorization lives. The gem handles authentication (the user proved who they are via the IdP); deciding whether that user is allowed into the admin panel — and what they can see once they are in — is the host application's problem. The gem does not ship a role model.
+Then start rails server `bundle exec rails s` and login to http://localhost:3000/ with
+login `admin` and password `111111`
 
-### Signature
+Then prepare test database(do not use db:test:prepare).
 
-```ruby
-c.on_login = ->(admin_user, claims) {
-  # admin_user: an instance of the configured admin_user_class.
-  #             Either a pre-existing row (matched by provider/uid or by
-  #             identity_attribute) or an unsaved new record.
-  # claims:     a Hash of String keys. Contains everything the IdP
-  #             returned in the id_token/userinfo, plus the top-level
-  #             `sub` (copied from the OmniAuth uid) and `email`
-  #             (copied from info.email) for convenience.
-  #             access_token / refresh_token / id_token are NEVER
-  #             present — they are stripped before this hook runs.
-  #
-  # Return truthy to allow sign-in.
-  # Return falsy (false/nil) to deny: the user sees a generic denial
-  # flash and no AdminUser record is persisted or mutated.
-  #
-  # Any mutations you make to admin_user are persisted automatically
-  # after the hook returns truthy.
-  #
-  # Exceptions raised inside the hook are logged at :error via
-  # ActiveAdmin::Oidc.logger and surface to the user as the same
-  # generic denial flash — the callback action never 500s.
-  true
-}
+```sh
+RAILS_ENV=test bundle exec rake db:drop db:create db:schema:load db:migrate db:seed
+RAILS_ENV=test bundle exec rake custom_seeds[network_prefixes]
 ```
 
-### Example A — Zitadel nested project roles claim
+This project has CDR-database, configured as cdr
+see https://guides.rubyonrails.org/active_record_multiple_databases.html
+And all commands should be run explicitly by calling "db:*:cdr" commands.
 
-Zitadel emits roles under the custom claim `urn:zitadel:iam:org:project:roles`, shaped as `{ "role-name" => { "org-id" => "org-name" } }`. Flatten the keys into a string array on the AdminUser.
+NOTICE: Test DB needs seeds, actually only PGQ seed.
 
-```ruby
-c.on_login = ->(admin_user, claims) {
-  roles = claims["urn:zitadel:iam:org:project:roles"]&.keys || []
-  return false if roles.empty?
+And run tests:
 
-  admin_user.roles = roles
-  admin_user.name  = claims["name"] if claims["name"].present?
-  true
-}
+```sh
+bundle exec rspec
 ```
 
-### Example B — department-based gating
+## Migrations
 
-```ruby
-KNOWN_DEPARTMENTS = %w[ops eng support].freeze
+When you run several migrations in a row, you may wish to stop at some point. In this case you should add `stop_step` method to the migration:
 
-c.on_login = ->(admin_user, claims) {
-  dept = claims["department"]
-  return false unless KNOWN_DEPARTMENTS.include?(dept)
+```ruby
+# example /db/migrate/20171105085529_one.rb
+def change
+  # do something
+end
 
-  admin_user.department = dept
+def stop_step
   true
-}
+end
 ```
 
-### Example C — syncing from a standard `groups` claim (Keycloak-style)
-
-```ruby
-ADMIN_GROUP = "admins"
+In this case all migrations after this one will no be performed. To continue migration process you should run `rake db:migrate` command again.
 
-c.on_login = ->(admin_user, claims) {
-  groups = Array(claims["groups"])
-  return false unless groups.include?(ADMIN_GROUP)
+If you do not want to migrate with stops, use env-variable IGNORE_STOPS=true
 
-  admin_user.super_admin = groups.include?("super-admins")
-  true
-}
+```sh
+IGNORE_STOPS=true bundle exec rake db:migrate
 ```
 
-## Reading additional claims from the callback
+## Migrations that insert rows into yeti database
 
-Every key the IdP returns in the id_token or userinfo is passed to `on_login` as part of `claims`. Custom claims work the same as standard ones — just read them by key:
+```bash
+RAILS_ENV=test bundle exec rake db:create db:schema:load db:seed
+RAILS_ENV=test bundle exec rake custom_seeds[network_prefixes]
+# create migration inside db/migrations
+RAILS_ENV=test bundle exec rake db:migrate
+# SCHEMA_NAME - schema of table into which you've inserted row(s)
+# YETI_TEST_DB_NAME - yeti test database name on local machine
+pg_dump --column-inserts --data-only --schema=SCHEMA_NAME --file=db/seeds/main/SCHEMA_NAME.sql YETI_TEST_DB_NAME
+```
 
-```ruby
-c.on_login = ->(admin_user, claims) {
-  admin_user.employee_id    = claims["employee_id"]
-  admin_user.given_name     = claims["given_name"]
-  admin_user.family_name    = claims["family_name"]
-  admin_user.locale         = claims["locale"]
-  admin_user.email_verified = claims["email_verified"]
-  # Nested / structured claims come through as whatever the IdP sent.
-  # Zitadel metadata, for instance:
-  admin_user.tenant_id      = claims.dig("urn:zitadel:iam:user:metadata", "tenant_id")
-  true
-}
+If you want to use network prefixes from yaml you need to exclude them from db/seeds/main/sys.sql
+```bash
+pg_dump --column-inserts --data-only --schema=sys --file=db/seeds/main/sys.sql --exclude-table=countries --exclude-table=networks --exclude-table=network_prefixes --exclude-table=network_types YETI_TEST_DB_NAME
 ```
 
-The full claim hash (minus `access_token` / `refresh_token` / `id_token`) is also stored on the admin user as `oidc_raw_info` — a JSON column created by the install generator. Read it later outside the hook for debugging or for showing the user's profile from the IdP:
+## Dump network prefixes
 
 ```ruby
-AdminUser.last.oidc_raw_info
-# => { "sub" => "...", "email" => "...", "groups" => [...], ... }
+nt_keys = %w[id name uuid]
+network_types = System::NetworkType.order(id: :asc).pluck(*nt_keys).map { |values| Hash[nt_keys.zip(values)] }
+File.write('db/network_types.yml', network_types.to_yaml)
+network_keys = %w[id name uuid type_id]
+networks = System::Network.order(id: :asc).pluck(*network_keys).map { |values| Hash[network_keys.zip(values)] }
+File.write('db/networks.yml', networks.to_yaml)
+country_keys = %w[id iso2 name]
+countries = System::Country.order(id: :asc).pluck(*country_keys).map { |values| Hash[country_keys.zip(values)] }
+File.write('db/countries.yml', countries.to_yaml)
+np_keys = %w[id number_max_length number_min_length prefix uuid country_id network_id]
+network_prefixes = System::NetworkPrefix.order(id: :asc).pluck(*np_keys).map { |values| Hash[np_keys.zip(values)] }
+File.write('db/network_prefixes.yml', network_prefixes.to_yaml)
 ```
 
-## Sign-in flow
-
-* A login button is added to the ActiveAdmin sessions page via a prepended view override — no templates to edit.
-* Clicking it POSTs to `/admin/auth/oidc` with a Rails CSRF token. The gem loads `omniauth-rails_csrf_protection` so OmniAuth 2.x delegates its authenticity check to Rails' forgery protection and `button_to` just works.
-* After a successful callback the user is signed in and redirected to `/admin` (not the host app's `/`, which may not exist).
-* Logout goes through Devise's stock session destroy. No RP-initiated single-logout ping to the IdP — override the destroy action in your host app if you need that.
+## Use Docker Postgres for development
 
-## Security notes
+For development purpouse it is convinient to use PostgreSQL from Docker image. Here is the instruction how to set it up-and-running:
 
-### Choice of `identity_attribute`
+* Install Docker(Ubuntu example)
 
-The `identity_attribute` column is used to adopt existing AdminUser rows on first SSO login — an existing user with that value in that column, and no `provider`/`uid` yet, gets linked to the IdP identity. **Do not** point this at a column the IdP can influence and that is also security-sensitive. Safe choices: `:email`, `:username`, `:employee_id`. Unsafe choices: `:admin`, `:super_admin`, `:password_digest`, `:roles` — anything whose value encodes a permission.
+  [Install Docker on Ubuntu 18.10](https://www.thecodecampus.de/blog/install-docker-on-ubuntu-18-10/)
 
-### Unique index on the identity column
+* Run following commands in terminal from `yeti-web` projects directory
 
-To prevent concurrent first-logins from creating two AdminUser rows for the same person, the column used as `identity_attribute` should have a database-level unique index. For the default `:email` case the standard Devise migration already adds this. If you pick a custom attribute, add the index yourself:
-
-```ruby
-add_index :admin_users, :employee_id, unique: true
-```
+  ```
+  sudo docker build -t yeti_postgres -f ci/pg13.Dockerfile .
+  ```
 
-The gem also adds a unique `(provider, uid)` partial index in its own install migration.
+* Start the Postgres Server using docker image, with remapped port to 3010 and volume "yetiPgData" to persist data after docker container stops:
 
-### What's filtered from logs
+  ```
+  sudo docker run -p 3010:5432 --volume yetiPgData:/var/lib/postgresql yeti_postgres
+  ```
 
-The initializer merges `code`, `id_token`, `access_token`, `refresh_token`, `state`, and `nonce` into `Rails.application.config.filter_parameters` so a mid-callback crash can't dump them into production logs. Your own `filter_parameters` entries are preserved.
-
-## Logger
-
-The gem logs internal diagnostics (on_login exceptions, omniauth failures) via `ActiveAdmin::Oidc.logger`. It defaults to `Rails.logger` when Rails is booted, falling back to a null logger otherwise. Override by assigning directly:
-
-```ruby
-ActiveAdmin::Oidc.logger = MyStructuredLogger.new
-```
+* Update `config/database.yml` with
 
-## License
+  ```yml
+  username: postgres
+  password:
+  port: 3010
+  ```
 
-MIT — see [`LICENSE.txt`](LICENSE.txt).
+* Initialize database with instructions described in [Contributing, Development setup](#contributing-development-setup) section(db:create, db:schema:load, etc.)