# eigenstate.ipa

`eigenstate.ipa` is an Ansible collection for Red Hat Identity Management
(IdM / FreeIPA). It exposes one inventory plugin, nine lookup plugins, and
two modules 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, HBAC rule inspection
and access testing, DNS inspection, sudo object inspection, and delegated
temporary user access leasing:

- `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`
- `eigenstate.ipa.dns`
- `eigenstate.ipa.sudo`
- `eigenstate.ipa.user_lease`

The collection treats IdM as both:

- a source of live infrastructure inventory
- a source of identity, policy, and supporting automation state

## 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
- inspects DNS zones and records through IdM DNS APIs
- inspects sudo rules, commands, and command groups through IdM sudo APIs
- manages temporary user access windows by setting or clearing IdM principal and password expiration attributes
- 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/index.md](docs/index.md)
- [docs/documentation-map.md](docs/documentation-map.md)
- [docs/vault-cyberark-primer.md](docs/vault-cyberark-primer.md)
- [docs/aap-integration.md](docs/aap-integration.md)
- [docs/openshift-primer.md](docs/openshift-primer.md)
- [docs/ephemeral-access-capabilities.md](docs/ephemeral-access-capabilities.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/dns-plugin.md](docs/dns-plugin.md)
- [docs/sudo-plugin.md](docs/sudo-plugin.md)
- [docs/user-lease-plugin.md](docs/user-lease-plugin.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
- can export curated IdM host attributes into hostvars

### `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` and `find`
- returns map configuration, linked HBAC rule names, and direct member lists
- 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`
- returns rule structure plus `hbactest` results for access verification
- supports `record` and `map_record` result shaping for `show` and `find`

### `eigenstate.ipa.dns`

- lookup plugin
- uses `ipalib` for read-only DNS zone and record inspection
- supports `show` and `find`
- covers forward records, reverse records, zone-apex entry checks, and zone searches
- supports `record` and `map_record` result shaping

### `eigenstate.ipa.sudo`

- lookup plugin
- uses `ipalib` for read-only sudo rule, command, and command group inspection
- supports `show` and `find`
- returns structured sudo objects for compliance, review, and automation pre-flight checks
- supports `record` and `map_record` result shaping

### `eigenstate.ipa.user_lease`

- module
- uses `ipalib` to set, clear, or immediately expire temporary user access windows
- manages `krbPrincipalExpiration` and optional password-expiry controls for existing users
- supports relative and absolute lease windows
- supports delegated-RBAC use cases where non-admin automation is allowed to manage expiry attributes
- supports Ansible check mode

## Runtime Notes

- target Ansible floor: `2.15.0`
- RHEL 9 compatibility is intentional
- vault lookup and vault write operations require `python3-ipalib` and `python3-ipaclient`
- principal, cert, otp, selinuxmap, hbacrule, dns, and sudo lookups require `python3-ipalib` and `python3-ipaclient`
- user_lease requires `python3-ipalib` and `python3-ipaclient`
- keytab lookups require the platform package that provides `ipa-getkeytab` on the control node or execution environment
- 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/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
- `plugins/lookup/dns.py` - DNS lookup plugin
- `plugins/lookup/sudo.py` - sudo object lookup plugin
- `plugins/modules/user_lease.py` - temporary user access lease module
- `plugins/module_utils/ipa_client.py` - shared Kerberos auth and `ipalib` connection layer for IPA operations
- `docs/` - operator-facing documentation
- `tests/` - unit coverage for inventory, vault, vault_write, principal, keytab, cert, otp, selinuxmap, hbacrule, dns, sudo, and user_lease
- `scripts/validate-collection.sh` - repo validation path
- `Makefile` - convenience wrapper for validation

## Publication Notes

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