eigenstate.ipa Documentation

eigenstate.ipa

IdM-native Ansible collection for inventory, vault, Kerberos, certificates, OTP, policy, AAP workflows, and temporary access boundaries.

How-to

Use this before keytab retrieval, certificate issuance, OTP enrollment, or access workflows that depend on an existing principal.

Boundary
Read-only
Authority
idm, collection, ansible
Evidence
command-output

Query principal state

When To Use This

Use this before keytab retrieval, certificate issuance, OTP enrollment, or access workflows that depend on an existing principal.

Required Authority

IdM owns principal state. The lookup reads existence, object type, lock, key, and last-auth facts.

Safety Boundary

This workflow is read-only. Confirm that this is the intended boundary before placing it in a scheduled job or AAP workflow.

Inputs

  • User, host, or service principal names
  • Read access to IdM principal records

Steps

  1. Run a show lookup for specific principals.
  2. Gate downstream tasks on exists and object type.
  3. Use find when discovery is needed before a batch workflow.
- name: Check service principal
  ansible.builtin.debug:
    var: lookup('eigenstate.ipa.principal', 'HTTP/app.example.com', principal_type='service', result_format='record')

Example Principal Preflight

This playbook checks that the service principal exists and already has key material before a workflow retrieves a keytab or requests a certificate.

preflight-principal.yml

---
- name: Verify service principal readiness
  hosts: localhost
  gather_facts: false
  vars:
    ipa_server: idm-01.example.com
    ipa_keytab: /runner/env/ipa/automation.keytab
    service_principal: HTTP/app01.example.com@EXAMPLE.COM
  tasks:
    - name: Read principal state from IdM
      ansible.builtin.set_fact:
        principal_state: >-
          {{ lookup('eigenstate.ipa.principal',
                    service_principal,
                    server=ipa_server,
                    kerberos_keytab=ipa_keytab,
                    result_format='record') }}

    - name: Stop before any downstream workflow if IdM is not ready
      ansible.builtin.assert:
        that:
          - principal_state.exists
          - principal_state.has_keytab
        fail_msg: >-
          {{ service_principal }} must exist and have key material
          before keytab retrieval or certificate issuance runs.

Run It

ansible-playbook preflight-principal.yml

Expected Evidence

result_format='record' returns principal state that can drive assertions:

principal_state:
  exists: true
  principal: HTTP/app.example.com@EXAMPLE.COM
  principal_type: service
  has_keytab: true
  disabled: false

Troubleshooting

  • Wrong type: set principal_type to user, host, or service.
  • Missing key material: inspect returned key state before keytab work.
  • Locked account: stop the workflow and resolve IdM state.