Red Hat Training

A Red Hat training course is available for Red Hat OpenStack Platform

Chapter 1. Introduction


Red Hat does not support federation at this time. This feature should only be used for testing, and should not be deployed in a production environment.

To configure federation in a high availability Red Hat OpenStack Platform director environment, you must configure the following:

  • Red Hat Identity Management
  • Red Hat single sign-on (RH-SSO)
  • The Red Hat OpenStack Platform overcloud

1.1. Overview

Federated authentication is a method of providing authentication across disparate services. This authentication solution relies on an identity provider (IdP), a service provider (SP), and is based on the Security Assertion Markup Language (SAML).

When OpenStack is the service provider in a federated authentication solution, members of the Red Hat Identity Management (IdM) group openstack-users are mapped into OpenStack Keystone group federated_users with the Member role for project access. Consequently, you are able to grant users access to OpenStack by adding those users to the IdM group openstack-users.

1.2. Prerequisites

You will need the following completed before deploying federated authentication:

  • You have deployed Red Hat OpenStack Platform director and the overcloud with the following properties:

    • You can use SSH to connect to both Red Hat OpenStack Platform director, and each of the overcloud nodes.
    • All nodes have a fully qualified domain name (FQDN).
    • TLS encryption is used for all external communications.
    • HAProxy terminates TLS front-end connections, and servers running behind HAProxy do not use TLS.
  • An RH-SSO server is present, and you either have administrative privileges on the server, or the RH-SSO administrator has created a realm for you and given you administrative privileges on that realm. Because federated IdPs are external by definition, the RH-SSO server is assumed to be external to the Red Hat OpenStack Platform director overcloud. For more information, see Installing and configuring RH-SSO and Creating a realm and user.
  • An IdM server is present, and also external to the Red Hat OpenStack Platform director overcloud where users and groups are managed. RH-SSO uses IdM as its User Federation backing store.
  • You follow the examples described in the Keystone Federation Configuration Guide.
  • On the undercloud-0 node, you install the helper files into the home directory of the stack user, and work in the stack user home directory.
  • On the controller-0 node, you install the helper files into the home directory of the heat-admin user, and work in the heat-admin user home directory.
  • If mod_auth_mellon was previously installed on your controller nodes, you must reinstall it as the Puppet Apache class will remove any Apache configuration files not under Puppet’s control.

Only the Red Hat OpenStack overcloud has federation enabled. The director is not federated.

1.3. Accessing the Red Hat OpenStack Platform nodes

By default, you must login to Red Hat OpenStack Platform director to access the overcloud nodes.

  1. Use SSH to connect to Red Hat OpenStack director:

    # ssh undercloud-0
  2. Become the stack user:

    $ su - stack
  3. Source the stackrc configuration to enable the required OpenStack environment variables:

    $ source stackrc
  4. After you source stackrc, you can issue commands using the openstack command line tool, which operates against Red Hat OpenStack Platform director. To directly access one of the overcloud nodes, retrieve the ip address by using openstack server list and then using SSH to connect:

    (undercloud) [stack@director ~]$ openstack server list -c Name -c Networks
    | Name                 | Networks              |
    | rhosp-controller-0   | ctlplane= |
    | rhosp-controller-1   | ctlplane= |
    | rhosp-controller-2   | ctlplane= |
    | rhosp-hypervisor-0   | ctlplane= |
    | rhosp-hypervisor-1   | ctlplane= |
    $ ssh heat-admin@

1.4. Overview of technologies

The following technologies are a part of Red Hat OpenStack Platform.

1.4.1. High availability

Red Hat OpenStack Platform director distributes redundant copies of various OpenStack services across the overcloud deployment. These redundant services are deployed on the overcloud controller nodes, with director naming these nodes controller-0, controller-1, controller-2, and so on, depending on how many controller nodes Red Hat OpenStack Platform director has configured.

The IP addresses of the Controller nodes are not externally visible because the services running on the Controller nodes are HAProxy back-end servers. There is one publicly visible IP address for the set of controller nodes; this is HAProxy’s front end. When a request arrives for a service on the public IP address, HAProxy selects a back-end server to service the request.

The overcloud is organized as a high availability cluster. Pacemaker manages the cluster, performs health checks, and can failover to another cluster resource if the resource stops functioning. You use Pacemaker to start and stop these resources.

For more information about high availability, see the {defaultURL}-single/high_availability_deployment_and_usage/[High Availability Deployment and Usage] guide. Managing Pacemaker Services

Do not use the systemctl command on a Controller node to manage services that Pacemaker manages. Use the Pacemaker pcs command:

sudo pcs resource restart haproxy-clone

To determine the resource name, use the Pacemaker status command:

sudo pcs status

Clone Set: haproxy-clone [haproxy]
Started: [controller-1]
Stopped: [controller-0]

1.4.2. HAProxy Overview

HAProxy serves a similar role to Pacemaker. It performs health checks on the back-end servers and forwards requests to functioning back-end servers. There is a cop of HAProxy running on all Controller nodes.

Although there are N copies of HAProxy running, only one is actually fielding requests at any given time; this active HAProxy instance is managed by Pacemaker. This approach prevents conflicts from occurring, and allows multiple copies of HAProxy to coordinate the distribution of requests across multiple back-ends. If Pacemaker detects that HAProxy has failed, it reassigns the front-end IP address to a different HAProxy instance. This HAProxy instance then becomes the controlling HAProxy instance.

1.5. Using a conifguration script

To configure federated authentication, you will need to run long and complex commands. To make that task easier and to allow for repeatability, the commands are saved to a shell script called configure-federation. You can execute a specific step if you pass the name of the step to configure-federation. To view the list of possible commands, use the help option (-h or --help).


For more information on the contents of the script, see Chapter 6, The configure-federation file.

To view the commands that are executed after variable substitution, use the following options:

This option provides a dry-run mode that writes its operations to stdout without making changes on the system.
This option provides a verbose mode that writes its operations to stdout before executing. This is useful for logging.

1.6. Using a proxy or SSL terminator

Consider the following key features for environments behind a proxy.

  • A back-end server might have a different hostname, listen on different port, or use a different protocol than what a client sees on the front side of the proxy.

    Problems can occur when a server generates a self-referential URL, for example if the server redirects the client to a different URL on the same server. The URL that the server generates must match the public address and port as seen by the client.

  • Authentication protocols such as HTTP and HTTPS are sensitive to the host, port, and protocol, because they often need to ensure a request was targeted for a specific server, port and on a secure transport. Proxies can interfere with this information.

    • A proxy transforms a request received on its public front-end before dispatching it to a non-public server in the back-end.
    • Responses from the non-public back-end server sometimes need adjustment so that it appears as if the response came from the public front-end of the proxy.

      There are various approaches to solving this problem. Because SAML is sensitive to host, port, and protocol information, and because you are configuring SAML behind a high availability proxy (HAProxy), you must deal with these issues or your configuration will likely fail.