# eigenstate.ipa

`eigenstate.ipa` is an Ansible collection for Red Hat Identity Management
(IdM / FreeIPA). It exposes one inventory plugin, seven lookup plugins, and
one vault lifecycle module for live inventory, vault-backed secret retrieval
and storage, Kerberos principal state, Kerberos keytab delivery, IdM CA
certificate automation, OTP workflows, SELinux user map inspection, and
HBAC rule inspection and access testing:

- `eigenstate.ipa.idm`
- `eigenstate.ipa.vault`
- `eigenstate.ipa.vault_write`
- `eigenstate.ipa.principal`
- `eigenstate.ipa.keytab`
- `eigenstate.ipa.cert`
- `eigenstate.ipa.otp`
- `eigenstate.ipa.selinuxmap`
- `eigenstate.ipa.hbacrule`

The collection treats IdM as both:

- a source of live infrastructure inventory
- a source of truth for secret retrieval

## What It Does

- builds dynamic inventory from IdM-managed hosts, hostgroups, netgroups, and
  HBAC policy
- retrieves secrets from IdM vaults through Kerberos-authenticated lookups
- manages vault lifecycle with create, archive, modify, and delete operations
- queries user, host, and service principal state before enrollment or secret issuance steps
- retrieves Kerberos keytab files for service and host principals
- requests, retrieves, and searches IdM CA certificates for host and service principals
- issues OTP tokens for users and one-time enrollment passwords for IdM hosts
- inspects SELinux user map state including linked HBAC rule names and direct member lists
- inspects HBAC rule state and runs live access tests via the FreeIPA hbactest engine
- supports user, service, and shared vault scopes
- supports standard, symmetric, and asymmetric vault retrieval
- supports metadata inspection, scoped search, and structured return shapes
- supports text and binary payload handling for Ansible and AAP workflows

## Best Entry Points

- [README.md](README.md)
- [docs/README.md](docs/README.md)
- [docs/inventory-plugin.md](docs/inventory-plugin.md)
- [docs/vault-plugin.md](docs/vault-plugin.md)
- [docs/vault-write-plugin.md](docs/vault-write-plugin.md)
- [docs/principal-plugin.md](docs/principal-plugin.md)
- [docs/keytab-plugin.md](docs/keytab-plugin.md)
- [docs/cert-plugin.md](docs/cert-plugin.md)
- [docs/otp-plugin.md](docs/otp-plugin.md)
- [docs/selinuxmap-plugin.md](docs/selinuxmap-plugin.md)
- [docs/hbacrule-plugin.md](docs/hbacrule-plugin.md)
- [docs/inventory-capabilities.md](docs/inventory-capabilities.md)
- [docs/vault-capabilities.md](docs/vault-capabilities.md)
- [docs/vault-write-capabilities.md](docs/vault-write-capabilities.md)
- [docs/principal-capabilities.md](docs/principal-capabilities.md)
- [docs/keytab-capabilities.md](docs/keytab-capabilities.md)
- [docs/cert-capabilities.md](docs/cert-capabilities.md)
- [docs/otp-capabilities.md](docs/otp-capabilities.md)
- [docs/selinuxmap-capabilities.md](docs/selinuxmap-capabilities.md)
- [docs/hbacrule-capabilities.md](docs/hbacrule-capabilities.md)
- [docs/inventory-use-cases.md](docs/inventory-use-cases.md)
- [docs/vault-use-cases.md](docs/vault-use-cases.md)
- [docs/vault-write-use-cases.md](docs/vault-write-use-cases.md)
- [docs/principal-use-cases.md](docs/principal-use-cases.md)
- [docs/keytab-use-cases.md](docs/keytab-use-cases.md)
- [docs/cert-use-cases.md](docs/cert-use-cases.md)
- [docs/otp-use-cases.md](docs/otp-use-cases.md)
- [docs/selinuxmap-use-cases.md](docs/selinuxmap-use-cases.md)
- [docs/hbacrule-use-cases.md](docs/hbacrule-use-cases.md)
- [docs/aap-integration.md](docs/aap-integration.md)

## Plugin Summary

### `eigenstate.ipa.idm`

- inventory plugin
- queries IdM JSON-RPC APIs
- builds live inventory for enrolled infrastructure
- supports password auth and Kerberos keytab auth

### `eigenstate.ipa.vault`

- lookup plugin
- uses `ipalib` for vault transport and retrieval
- supports `retrieve`, `show`, and `find`
- supports `value`, `record`, `map`, and `map_record`
- supports `encoding='utf-8'` and `encoding='base64'`
- supports `decode_json` and `strip_trailing_newline` for retrieved UTF-8 text

### `eigenstate.ipa.vault_write`

- module
- uses `ipalib` for vault lifecycle management
- supports `state: present`, `state: absent`, and `state: archived`
- creates standard, symmetric, and asymmetric vaults
- standard vault archives are idempotent; symmetric and asymmetric archives are write-always
- supports delta-only member management via `members` and `members_absent`
- supports Ansible check mode

### `eigenstate.ipa.principal`

- lookup plugin
- uses `ipalib` for Kerberos principal state queries
- supports `show` and `find`
- returns existence, key, lock, and last-auth state for user, host, and service principals
- supports `record` and `map_record` result shaping

### `eigenstate.ipa.keytab`

- lookup plugin
- uses `ipa-getkeytab` from the platform IPA client tooling for keytab
  retrieval
- no ipalib dependency at retrieval time
- supports `retrieve` mode (safe default, existing keys only) and `generate`
  mode (rotates principal keys; invalidates all existing keytabs)
- supports per-principal encryption-type selection via `enctypes`
- returns base64-encoded keytab content in `value`, `record`, or `map` format

### `eigenstate.ipa.cert`

- lookup plugin
- uses `ipalib` for IdM CA request, retrieval, and search operations
- supports `request`, `retrieve`, and `find`
- accepts inline CSRs or controller-local CSR files
- supports PEM and base64-encoded DER output
- supports `value`, `record`, `map`, and `map_record` result shaping

### `eigenstate.ipa.otp`

- lookup plugin
- uses `ipalib` for OTP token issue, lookup, and revoke operations
- supports `totp`, `hotp`, and one-time host enrollment password generation
- supports `add`, `find`, `show`, and `revoke`
- returns OTP URIs, host enrollment passwords, or structured token metadata

### `eigenstate.ipa.selinuxmap`

- lookup plugin
- uses `ipalib` for read-only SELinux user map state queries
- supports `show` (named map lookup) and `find` (bulk enumeration)
- returns `name`, `selinuxuser`, `enabled`, `hbacrule` (linked rule name
  extracted from `seealso` DN), `users`, `groups`, `hosts`, `hostgroups`,
  and `description`
- supports `record` and `map_record` result shaping

### `eigenstate.ipa.hbacrule`

- lookup plugin
- uses `ipalib` for read-only HBAC rule state queries and live access testing
- supports `show`, `find`, and `test`
- `show`/`find` return `name`, `enabled`, `usercategory`, `hostcategory`,
  `servicecategory`, `users`, `groups`, `hosts`, `hostgroups`, `services`,
  `servicegroups`, and `description`
- `test` invokes the FreeIPA `hbactest` engine (same logic SSSD uses at login)
  and returns `user`, `targethost`, `service`, `denied`, `matched`, and
  `notmatched`
- supports `record` and `map_record` result shaping for `show`/`find`

## Runtime Notes

- target Ansible floor: `2.14.0`
- RHEL 9 compatibility is intentional
- vault lookup and vault write operations require `python3-ipalib` and `python3-ipaclient`
- principal lookups require `python3-ipalib` and `python3-ipaclient`
- keytab lookups require the platform package that provides `ipa-getkeytab`
  on the control node or execution environment
- cert lookups require `python3-ipalib` and `python3-ipaclient`
- otp lookups require `python3-ipalib` and `python3-ipaclient`
- selinuxmap lookups require `python3-ipalib` and `python3-ipaclient`
- hbacrule lookups require `python3-ipalib` and `python3-ipaclient`
- controller or execution-environment usage may also require Kerberos client
  tooling

## Repository Layout

- `plugins/inventory/idm.py` - dynamic inventory plugin
- `plugins/lookup/vault.py` - vault lookup plugin
- `plugins/modules/vault_write.py` - vault write module
- `plugins/module_utils/ipa_client.py` - shared Kerberos auth and `ipalib` connection layer for IPA write operations
- `plugins/lookup/principal.py` - Kerberos principal state lookup plugin
- `plugins/lookup/keytab.py` - keytab lookup plugin
- `plugins/lookup/cert.py` - IdM certificate lookup plugin
- `plugins/lookup/otp.py` - OTP and host enrollment password lookup plugin
- `plugins/lookup/selinuxmap.py` - SELinux user map lookup plugin
- `plugins/lookup/hbacrule.py` - HBAC rule query and hbactest lookup plugin
- `docs/` - operator-facing documentation
- `tests/` - unit coverage for the vault, vault_write, principal, keytab, cert, otp, selinuxmap, and hbacrule components
- `scripts/validate-collection.sh` - repo validation path
- `Makefile` - convenience wrapper for validation

## Publication Notes

- collection name: `eigenstate.ipa`
- namespace: `eigenstate`
- current version: `1.6.0`
- author: Greg Procunier
- license: GPL-3.0-or-later
- repository: https://github.com/gprocunier/eigenstate-ipa
