How to register IdM deployment with RHEL domain join

Our first blog post, Introducing IdM in RHEL Domain Join feature - Enroll your machines on boot, discussed the benefits and implementation of automated machine enrollment in Red Hat Enterprise Linux (RHEL).

In this article, we will dive deeper into the registration workflow of the domain join feature. The registration workflow is a prerequisite to enabling the domain join feature in recently launched instances. It follows a structured process to securely join new instances into an organization's Identity Management (IdM) system. We will explore the technical steps, key considerations, and common troubleshooting scenarios to ensure a smooth registration process.

The registration process

The key objectives of the end-to-end registration workflow:

• Establish a secure connection between the instance, Red Hat Hybrid Cloud Console, and the IdM server.
• Automate the domain join process to minimize manual intervention.
• Ensure secure authentication and policy enforcement upon successful enrollment.

The steps of the registration process follow:

1. Registration wizard
   • Through the registration wizard and the ipa-hcc register command, customers can register their preexisting IdM in RHEL (or FreeIPA) identity domain with the Directory and Domain Services feature.
2. Instance deployment
   • Deploy a new instance (virtual machine or bare metal) in a cloud or on-premises environment.
   • Preconfigure the instance with the ipa-hcc-client package.
   • This instance is registered and known by Hybrid Cloud Console. In other words, it is registered with Subscription Manager and Red Hat Lightspeed, formerly Red Hat Insights (to the same organization as the IdM server).
3. Secure communication initiation
   • The instance establishes a connection with Hybrid Cloud Console.
   • Hybrid Cloud Console validates the instance and checks for the necessary prerequisites.
4. Enrollment token retrieval
   • The instance requests an enrollment token from the Hybrid Cloud Console Directory and Domain Services API.
   • After authenticating the instance, the service generates and returns a token to the instance to be used for the enrollment.
5. Instance authentication and enrollment
   • The instance uses the token to introduce itself to the IdM server.
   • The IdM server validates the token and creates the host entry.
   • The instance completes its enrollment using its Subscription Manager client certificate to authenticate.
6. Policy enforcement and access control
   • The instance now enforces organization-wide authentication and security policies.
   • Users can securely access the instance using existing IdM credentials.
7. Ongoing synchronization and compliance
   • The instance periodically communicates with the IdM server to maintain compliance.
   • Any access revocations or policy updates are immediately applied to the instance.
   • The registered IdM deployment refreshes its data in the Hybrid Cloud Console Directory and Domain Services database daily to allow for topology changes.

Figure 1 illustrates the domain join registration process.

4 phases of the registration workflow

The registration workflow can be broken down into four phases:

1. Request registration token
   • The process begins when an administrator requests a registration token from the Directory and Domain Services user interface (called "idmsvc frontend" in the diagram).
2. User executes registration command
   • The administrator runs the command ipa-hcc register <token> on the IdM server (provided by the ipa-hcc-server package).
   • This command initiates the server’s registration with Hybrid Cloud Console.
3. Register IdM server API call
   • The ipa-hcc command calls the Directory and Domain Services API (called "idmsvc backend" in the diagram) to register the IdM server.
   • This ensures that the IdM server is recognized and ready for domain join operations.
4. Store registration in database
   • The API authorizes the registration and stores data about the IdM deployment (i.e., topology, list of servers, etc.) in its own database.
   • This step finalizes the process, ensuring the system can refer new instances to the organization's registered IdM deployment.

Registration workflow demo

For a step-by-step demonstration of the registration workflow, you can watch the following demonstration.

Troubleshooting common issues

While the registration workflow is designed to be seamless, some challenges may arise. The following are common issues and their resolutions:

• Instance fails to communicate with Hybrid Cloud Console:
  • Ensure proper network connectivity and DNS resolution.
  • Verify that required IPA ports such as HTTPS, Kerberos, and LDAP are accessible from the environment where the client instance is running.
• Authentication failure with IdM server:
  • Confirm that the ipa-hcc-server package is correctly installed on the IdM server.
  • The registration token is bound to the organization—the IdM server must be registered to the same organization as the account running the registration wizard on Hybrid Cloud Console.
  • Check server logs for potential misconfigurations.
• Cloud environment
  • DNS, routes, and firewalls can cause issues while setting up your environment and establishing connectivity.

Next steps

Now that your IdM deployment is registered with Hybrid Cloud Console, you are ready to launch machines and have them automatically enroll. Jump to our next article to learn all about that: Instance enrollment workflow for domain join in RHEL.