Instance enrollment workflow for domain join in RHEL

In our previous article, How to register IdM deployment with RHEL domain join, we explored the registration workflow for the domain join feature in Red Hat Enterprise Linux (RHEL). In this third and final installment, we will dive into the join workflow to explain how an instance successfully becomes part of the domain. 

Additionally, we will discuss an essential prerequisite step, building an image using the Red Hat Hybrid Cloud Console (HCC) and Red Hat Lightspeed image builder, ensuring the instance has the necessary configuration before deployment. If you haven't already, check out our first article in this series, Introducing IdM in RHEL Domain Join feature - Enroll your machines on boot.

Create blueprints with Red Hat Lightspeed image builder

Before an instance can join the domain, it needs to be properly configured with the steps for image preparation. Follow these steps to create blueprints with Hybrid Cloud Console and image builder, a tool bundled within Red Hat Lightspeed:

1. Access the images service via Hybrid Cloud Console.
2. Create a new image blueprint that defines the workload image. The image configuration is up to you, but there are a couple of requirements for the domain join feature to work:
   • In the Register step, select Automatically register and enable advanced capabilities.
   • In the Additional packages step, include the ipa-hcc-client package in the image. This package is currently in the Extra Packages in Enterprise Linux (EPEL) repository, but we plan to release it in RHEL.
3. Build and export the image for deployment across cloud or on-premise environments.

For a step-by-step demonstration of blueprint creation and image build, you can watch this recorded demo.

With this step complete, instances launched from this image will be preconfigured for domain join.

The join workflow

Figure 1 illustrates the domain join registration and join workflows.

The domain join workflow steps

1. Obtain an enrollment token.
   • The instance requests an enrollment token from the Hybrid Cloud Console backend service.
2. Create enrollment token.
   • The backend service verifies the request and generates a secure enrollment token.
3. Token retrieval response.
   • The instance receives the enrollment token, along with information about the domain to join.
4. Request domain join.
   • The instance initiates a join request to the ipa-hcc-server on the IdM server.
   • The request is authorized using the enrollment token.
5. Register the host in IdM.
   • The ipa-hcc-server registers the instance as a host in the IdM system.
   • The IdM API (ipa host-add) is called to create the entry in the directory.
6. Invoking client enrollment.
   • The instance executes the ipa-client-install command to complete the domain join process.
7. Complete the join process.
   • The ipa-client-install command retrieves necessary authentication credentials (keytabs, policies, etc.). The instance's subscription manager certificate is used to authenticate the operation.
   • It is now a fully enrolled client in the IdM system.

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

Troubleshooting common issues

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

• Failed authorization during join request
  • Automatic domain join only works when the clients and servers belong to the same organization, and the IdM deployment is registered with the Directory and Domain Services service.
  • Currently, we support only one (active) IdM domain per organization. If there are multiple active registrations, enrollment token retrieval fails. There is a proposal to implement this in our backlog (Domain Join - IDM: support for multiple domains).
  • Check that the IdM server has the ipa-hcc-server package installed and is reachable from the environment where the client was launched.
• Client installation issues
  • Run ipa-client-install --force to retry enrollment.
  • Ensure the ipa-hcc-client package is installed.

Conclusion

This concludes our three-part series, a comprehensive guide to the RHEL domain join feature. The join workflow ensures that instances successfully integrate into an organization's identity domain. By preparing images with the Red Hat Lightspeed image builder tool, automating token-based authentication, and leveraging ipa-hcc-client, organizations can achieve secure, scalable, and policy-enforced domain management in RHEL.

By following this guide, administrators can streamline the domain join process, reducing manual effort and enhancing security across cloud and on-premise deployments. Stay tuned for further insights into optimizing identity management in RHEL.