IPA enrollment agent for Red Hat Hybrid Cloud Console
Project description
IPA plugin for Hybrid Cloud Console
The ipa-hcc plugin provides schema extension of IPA for Hybrid Cloud Console integration. The plugin must be installed on all FreeIPA servers, preferable before the server/replica is installed.
If the plugin is installed later, then the local schema cache may be
outdated and ipa
command may not be aware of the new attributes.
In that case the local schema cache can be refreshed by enforcing
a schema check ipa -eforce_schema_check=True ping
or by purging
the cache with rm -rf ~/.cache/ipa
.
Installation requires a server upgrade ipa-server-upgrade
and
restart of services ipactl restart
. The post transaction hook
of the RPM package takes care of both. A server upgrade can take a
while and can disrupt normal operations on the machine. It is advised
to serialize the operation and install the plugin on one server at a
time.
Additional host attributes
- HCCOrgId: string
- HCCSubscriptionId: string
- HCCInventoryId: string
- HCCCertSubject: string (auto-generated)
Server config
- HCCOrgId: string
- HCCDomainId: string
Host groups
Host group hcc-enrollment
is created on server upgrade. Hosts with
a HCCSubscriptionId
are automatically added to the host group by
an automember rule.
certmap rule
A certmap rule rhsm-cert
matches subject of RHSM certificates to host's
``HCCCertSubject` attribute.
service principal
Each IPA server has a hcc-enrollment/$FQDN
service with role
HCC Enrollment Administrators
.
Indexes
- Index on
HCCSubscriptionId
for presence and equality - Index on
HCCInventoryId
for presence and equality - Index on
HCCCertSubject
for presence and equality - Uniqueness of
HCCCertSubject
attributes
Command line extension
$ ipa host-mod --help
...
--hccsubscriptionid=STR
--hccinventoryid=STR
...
$ ipa host-show host.test.example
...
organization id: 42
subscription id: 1f84492f-a824-41b8-8ccd-a4e9e1ab2f3d
inventory id: e98a6828-faf2-4917-8f0f-7af27fad3683
RHSM certificate subject: O=42,CN=1f84492f-a824-41b8-8ccd-a4e9e1ab2f3d
...
$ ipa config-mod --help
...
--hccorgid=STR organization id
--hccdomainid=STR domain id
...
Internal IPA API extension
The hccjwk
plugin adds internal APIs:
hccjwk_add
hccjwk_find
hccjwk_show
hccjwk_revoke
hccjwk_del
Roles / Privileges / Permissions
- Permission
System: Read HCC config attributes
System: Read HCC host attributes
System: Modify HCC host attributes
System: Read HCC JWKs
System: Add HCC JWK
System: Delete HCC JWK
System: Modify HCC JWK
- Privilege
HCC Host Administrators
that grants permissionsSystem: Add Hosts
(IPA permission)System: Modify HCC host attributes
(IPA permission)System: Read HCC config attributes
System: Read HCC host attributes
System: Modify HCC host attributes
- Privilege
HCC JWK Administrators
that grants permissionsSystem: Read HCC JWKs
System: Add HCC JWK
System: Delete HCC JWK
System: Modify HCC JWK
- Role
HCC Enrollment Administrators
with privilegesHCC Host Administrators
HCC JWK Administrators
Schema / server updater
The update file 85-hcc.update
for ipa-server-upgrade
creates:
- host group
hcc-enrollment
- automember rule for host group
- certmap rule
rhsm-cert
- additional role and privileges
- new indexes and unique constraint
- runs
update_hcc
update plugin
The update_hcc
update plugin:
- modifies KRB5 KDC config file to trust the RHSM certificate chain and restarts the service if necessary.
- checks HCCOrgId setting in IPA's global configuration. If the
option is not set, then it sets the value based on the subject org
name of server's RHSM certificate (
/etc/pki/consumer/cert.pem
). - set/update HCCSubscriptionId of the server's host entry based on the subject CN of the server's RHSM certificate.
The update file 86-hcc-enrollment-service.update
runs the
update_hcc_enrollment_service
plugin, whoch
- creates service account
hcc-enrollment/$FQDN@$REALM
- adds the service to the
HCC Enrollment Administrators
role - creates or validates the keytab for
hcc-enrollment/$FQDN@$REALM
service account
Server test setup
- Prepare host
$ hostnamectl set-hostname ipaserver.ipahcc.test
$ vi /etc/hosts
# add public IPv4 address to /etc/hosts
$ dnf install ipa-server ipa-server-dns
- Install an IPA server with DNS
$ ipa-server-install -n ipahcc.test -r IPAHCC.TEST -p DMSecret123 -a Secret123 \
--setup-dns --auto-forwarders --no-dnssec-validation -U
- Configure
trusted_network
ACL in/etc/named/*.conf
andsystemctl restart named.service
, e.g.
# /etc/named/ipa-ext.conf
acl "trusted_network" {
localnets;
localhost;
10.0.0.0/8;
};
# /etc/named/ipa-options-ext.conf
allow-recursion { trusted_network; };
allow-query-cache { trusted_network; };
listen-on-v6 { any; };
dnssec-validation no;
- Add client hostname to DNS
$ kinit admin
$ ipa dnsrecord-add ipahcc.test ipaclient1 --a-rec=...
- Create a Red Hat API refresh
token and save it in
/etc/ipa/hcc/refresh_token
.
cat > /etc/ipa/hcc/refresh_token
...
EOF
chown ipahcc:root /etc/ipa/hcc/refresh_token
chmod 640 /etc/ipa/hcc/refresh_token
WARNING the token has the same privileges as your user account.
- Install plugin and other services
dnf install 'dnf-command(copr)'
dnf copr enable @podengo/ipa-hcc
dnf install --refresh ipa-hcc-server
NOTE It is possible to install a server/replica with ipa-hcc-server
package pre-installed. Both variants are supported and yield the same result.
The token and /etc/ipa/hcc.conf
must be set before the server is installed.
Client test setup
- Install packages
RHEL 8.8+ or RHEL 9.2+
dnf install 'dnf-command(copr)'
dnf copr enable @podengo/ipa-hcc
dnf install --refresh ipa-client ipa-hcc-client
-
Configure DNS and hostname. The client must be able to discover its IPA domain and IPA servers with DNS SRV discovery.
-
Enable the auto-enrollment service
systemctl enable ipa-hcc-auto-enrollment.service
- Register system with RHSM and Insights
RHEL >= 8:
rhc connect
RHEL 7:
subscription-manager register ...
insights-client --register
rhc connect
The ipa-hcc-auto-enrollment.service
triggers after rhc
starts the
rhcd
service. The enrollment service runs the script
ipa-hcc-auto-enrollment.py
, which uses DNS SRV discovery to locate
IPA servers, connects to /hcc
WSGI app to self-register the
host and finally runs ipa-client-install
.
Client test setup (step by step)
-
Copy
/var/lib/ipa-client/pki/kdc-ca-bundle.pem
from server to client. -
Register system with RHSM and Insights
rhc connect
Older RHEL versions may require manual registration with insights
insights-client --register
- Self-register host with IdM
curl \
--cacert /root/kdc-ca-bundle.pem \
--cert /etc/pki/consumer/cert.pem \
--key /etc/pki/consumer/key.pem \
https://ipaserver.hmsidm.test/hcc
- Enroll host with IdM
ipa-client-install \
--pkinit-identity=FILE:/etc/pki/consumer/cert.pem,/etc/pki/consumer/key.pem \
--pkinit-anchor=FILE:/root/kdc-ca-bundle.pem \
--server ipaserver.hmsidm.test --domain hmsidm.test -U -N
Notes
- IPA's KDC plugin caches certmap rules for 5 minutes. For rapid testing
restart the KDC with
systemctl restart krb5kdc.service
. Seeipa_kdc_certauth.c
:DEFAULT_CERTMAP_LIFETIME
. ipa certmap-match
is only implemented for users. It cannot be used to test cert mappings for hosts.
Workarounds
IdM does not implement #9272 "Install CA certificates only for PKINIT or TLS client auth", yet.
- Apache HTTPd is configured to load extra CA certs for client cert
authentication from CA path
/usr/share/ipa-hcc/cacerts/
. - Kerberos KDC loads extra PKINIT trust anchors from
DIR:/usr/share/ipa-hcc/cacerts
.
Known issues
Global authentication types affect host auth
- Affects: RHEL 8.9, 9.3, and earlier
- Ticket: https://pagure.io/freeipa/issue/9485
IPA's KDC KDB plugin has a known issue related to global user auth
configuration. If an admin sets a global policy for user auth types and does
not include pkinit
, then the KDC refuses cert authentication for hosts.
$ ipa config-mod --user-auth-type=password --user-auth-type=otp
$ ipa config-show
...
Default user authentication types: password, otp
ipa-client-install
fails with:
kinit: KDC policy rejects request while getting initial credentials
and /var/log/krb5kdc.log
contains:
PKINIT pre-authentication not allowed for this user.: host/host.ipa.example@IPA.EXAMPLE for krbtgt/IPA.EXAMPLE@IPA.EXAMPLE, KDC policy rejects request
Workaround: also enable pkinit
:
ipa config-mod --user-auth-type=password --user-auth-type=otp --user-auth-type=pkinit
Development and Testing
See CONTRIBUTING.md
for how to contribute to this repository.
See DEVELOPMENT.md
for instructions how to set up local development
environment and how to utilize idm-ci
for testing.
License
See file 'COPYING' for use and warranty information
This program is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation, either version 3 of the License, or (at your option) any later version.
This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.
You should have received a copy of the GNU General Public License along with this program. If not, see http://www.gnu.org/licenses/.
Project details
Release history Release notifications | RSS feed
Download files
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.
Source Distribution
Built Distribution
Hashes for ipahcc-0.17-py2.py3-none-any.whl
Algorithm | Hash digest | |
---|---|---|
SHA256 | 3022e148844f4348ef5b485517d096707eecb6606072de8e0c0854aeb603e61c |
|
MD5 | 7d6aa6d317d3ab379ce7dedc7901232d |
|
BLAKE2b-256 | 4708ec01a42760ad2f9eaba1353d2573c46bd943f7d7f9ba88acfae02dd8b206 |