# eigenstate.ipa

`eigenstate.ipa` is an Ansible collection for Red Hat Identity Management
(IdM / FreeIPA). It exposes one inventory plugin and three lookup plugins for
live inventory, vault-backed secret retrieval, Kerberos keytab delivery, and
IdM CA certificate automation:

- `eigenstate.ipa.idm`
- `eigenstate.ipa.vault`
- `eigenstate.ipa.keytab`
- `eigenstate.ipa.cert`

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
- retrieves Kerberos keytab files for service and host principals
- requests, retrieves, and searches IdM CA certificates for host and service principals
- 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/keytab-plugin.md](docs/keytab-plugin.md)
- [docs/cert-plugin.md](docs/cert-plugin.md)
- [docs/inventory-capabilities.md](docs/inventory-capabilities.md)
- [docs/vault-capabilities.md](docs/vault-capabilities.md)
- [docs/keytab-capabilities.md](docs/keytab-capabilities.md)
- [docs/cert-capabilities.md](docs/cert-capabilities.md)
- [docs/inventory-use-cases.md](docs/inventory-use-cases.md)
- [docs/vault-use-cases.md](docs/vault-use-cases.md)
- [docs/keytab-use-cases.md](docs/keytab-use-cases.md)
- [docs/cert-use-cases.md](docs/cert-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.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

## Runtime Notes

- target Ansible floor: `2.14.0`
- RHEL 9 compatibility is intentional
- vault 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`
- 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/lookup/keytab.py` - keytab lookup plugin
- `plugins/lookup/cert.py` - IdM certificate lookup plugin
- `docs/` - operator-facing documentation
- `tests/` - unit coverage for the vault, keytab, and cert plugins
- `scripts/validate-collection.sh` - repo validation path
- `Makefile` - convenience wrapper for validation

## Publication Notes

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