# eigenstate.ipa

`eigenstate.ipa` is an Ansible collection for Red Hat Identity Management
(IdM / FreeIPA). It exposes one inventory plugin, nine lookup plugins,
four modules, and an AAP execution-environment role 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.keytab_manage`
- `eigenstate.ipa.cert_request`
- `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-ee-quickstart.md](docs/aap-ee-quickstart.md)
- [docs/aap-ee-validation-walkthrough.md](docs/aap-ee-validation-walkthrough.md)
- [docs/aap-golden-path-roles.md](docs/aap-golden-path-roles.md)
- [docs/sealed-artifact-delivery-role.md](docs/sealed-artifact-delivery-role.md)
- [docs/temporary-access-window-role.md](docs/temporary-access-window-role.md)
- [docs/cert-expiry-report-role.md](docs/cert-expiry-report-role.md)
- [docs/phase2-validation-walkthrough.md](docs/phase2-validation-walkthrough.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/keytab-manage-module.md](docs/keytab-manage-module.md)
- [docs/cert-request-module.md](docs/cert-request-module.md)
- [docs/compatibility-policy.md](docs/compatibility-policy.md)
- [docs/mutation-surface-migration.md](docs/mutation-surface-migration.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.keytab_manage`

- module
- retrieves existing Kerberos keytabs or rotates principal keys through `ipa-getkeytab`
- requires `confirm_rotation: true` before key rotation
- writes keytabs to an optional destination with mode, owner, and group controls
- returns metadata by default and returns base64 keytab content only with `return_content: true`
- supports Ansible check mode

### `eigenstate.ipa.cert_request`

- module
- requests IdM CA certificates from inline CSR content or a CSR file
- writes issued certificates to an optional destination with mode, owner, and group controls
- returns safe certificate metadata by default
- returns certificate content only with `return_content: true`
- keeps private key handling outside the module

### `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/modules/keytab_manage.py` - keytab retrieval, deployment, and guarded rotation module
- `plugins/modules/cert_request.py` - certificate request 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
- `execution-environment/eigenstate-idm/` - ready-to-build AAP execution environment scaffold
- `roles/aap_execution_environment/` - role to render, build, smoke-test, push, and optionally register the AAP EE
- `roles/sealed_artifact_delivery/` - role to preflight, stage, hand off, clean up, and report sealed IdM vault artifacts
- `roles/temporary_access_window/` - role to preflight and manage IdM temporary access windows through `user_lease`
- `roles/cert_expiry_report/` - role to find IdM certificates and render JSON, Markdown, and CSV expiry reports
- `playbooks/aap-ee-*.yml` - wrapper playbooks for the AAP EE workflow
- `playbooks/sealed-artifact-delivery.yml`, `playbooks/temporary-access-window.yml`, and `playbooks/cert-expiry-report.yml` - wrapper playbooks for AAP golden-path roles
- `tests/` - unit coverage for inventory, vault, vault_write, keytab_manage, cert_request, 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.12.0`
- author: Greg Procunier
- license: GPL-3.0-or-later
- repository: https://github.com/gprocunier/eigenstate-ipa
