Hub XMLRPC API Authentication Modes

Table of Contents

The Hub XMLRPC API supports three different authentication modes:

  • Manual mode (default): API credentials must be explicitly provided for each server.

  • Relay mode: the credentials used to authenticate with the Hub are also used to authenticate to each server. You must provide a list of servers to connect to.

  • Auto-connect mode: credentials are reused for each server, and any peripheral server you have access to is automatically connected.

1. Authentication Examples

This section provides examples of each authentication method.

Example: Manual Authentication

In manual mode, credentials have to be explicitly provided for each peripheral server before you can connect to it.

A typical workflow for manual authentication is:

  1. Credentials for the Hub are passed to the login method, and a session key for the Hub is returned (hubSessionKey).

  2. Using the session key from the previous step, Uyuni Server IDs are obtained for all the peripheral servers attached to the Hub via the hub.listServerIds method.

  3. Credentials for each peripheral server are provided to the attachToServers method. This performs authentication against each server’s XMLRPC API endpoint.

  4. A multicast call is performed on a set of servers. This is defined by serverIds, which contains the IDs of the servers to target. In the background, system.list_system is called on each server’s XMLRPC API

  5. Hub aggregates the results and returns the response in the form of a map. The map has two entries:

    • Successful: list of responses for those peripheral servers where the call succeeded.

    • Failed: list of responses for those peripheral servers where the call failed.

If you want to call a method on just one Uyuni Server, then Hub API also provides a unicast namespace. In this case, the response will be a single value and not a map, in the same way as if you called that Uyuni server’s API directly.
Listing 1. Example Python Script for Manual Authentication:
#!/usr/bin/python3
import xmlrpc.client

HUB_XMLRPC_API_URL = "<HUB_XMLRPC_API_URL>"
HUB_USERNAME = "<USERNAME>"
HUB_PASSWORD = "<PASSWORD>"

client = xmlrpc.client.ServerProxy(HUB_XMLRPC_API_URL, verbose=0)

hubSessionKey = client.hub.login(HUB_USERNAME, HUB_PASSWORD)

# Get the server IDs
serverIds = client.hub.listServerIds(hubSessionKey)

# For simplicity, this example assumes you are using the same username and password here, as on the hub server.
# However, in most cases, every server has its own individual credentials.
usernames = [HUB_USERNAME for s in serverIds]
passwords = [HUB_PASSWORD for s in serverIds]

# Each server uses the credentials set above, client.hub.attachToServers needs
# them passed as lists with as many elements as there are servers.
client.hub.attachToServers(hubSessionKey, serverIds, usernames, passwords)

# Perform the operation
systemsPerServer = client.multicast.system.list_systems(hubSessionKey, serverIds)
successfulResponses = systemsPerServer["Successful"]["Responses"]
failedResponses = systemsPerServer["Failed"]["Responses"]

for system in successfulResponses:
  print(system)

# Log out
client.hub.logout(hubSessionKey)
Example: Relay Authentication

In relay authentication mode, the credentials used to sign in to the Hub API are also used to sign in into the APIs of the peripheral servers the user wants to work with. In this authentication mode, it is assumed that the same credentials are valid for every server, and that they correspond to a user with appropriate permissions.

After signing in, you must call the attachToServers method. This method defines the servers to target in all subsequent calls.

A typical workflow for relay authentication is:

  1. Credentials for the Hub are passed to the loginWithAuthRelayMode method, and a session key for the Hub is returned (hubSessionKey).

  2. Using the session key from the previous step, Uyuni Server IDs are obtained for all the peripheral servers attached to the Hub via the hub.listServerIds method

  3. A call to attachToServers is made, and the same credentials used to sign in to the Hub are passed to each server. This performs authentication against each server’s XMLRPC API endpoint.

  4. A multicast call is performed on a set of servers. This is defined by serverIds, which contains the IDs of the servers to target. In the background, system.list_system is called on each server’s XMLRPC API.

  5. Hub aggregates the results and returns the response in the form of a map. The map has two entries:

    • Successful: list of responses for those peripheral servers where the call succeeded.

    • Failed: list of responses for those peripheral servers the call failed.

Listing 2. Example Python Script for Relay Authentication:
#!/usr/bin/python3
import xmlrpc.client

HUB_XMLRPC_API_URL = "<HUB_XMLRPC_API_URL>"
HUB_USERNAME = "<USERNAME>"
HUB_PASSWORD = "<PASSWORD>"

client = xmlrpc.client.ServerProxy(HUB_XMLRPC_API_URL, verbose=0)

hubSessionKey = client.hub.loginWithAuthRelayMode(HUB_USERNAME, HUB_PASSWORD)

# Get the server IDs
serverIds = client.hub.listServerIds(hubSessionKey)

# Authenticate those servers(same credentials will be used as of hub to authenticate)
client.hub.attachToServers(hubSessionKey, serverIds)

# Perform the needed operation
systemsPerServer = client.multicast.system.list_systems(hubSessionKey, serverIds)
successfulResponses = systemsPerServer["Successful"]["Responses"]
failedResponses = systemsPerServer["Failed"]["Responses"]

for system in successfulResponses:
  print(system)

# Log out
client.hub.logout(hubSessionKey)
Example: Auto-Connect Authentication

Auto-connect mode is similar to relay mode, it uses the Hub credentials to sign in in to all peripheral servers. However, there is no need to use the attachToServers method, as auto-connect mode connects to all available peripheral servers. This occurs at the same time as you sign in to the Hub.

A typical workflow for auto-connect authentication is:

  1. Credentials for the Hub are passed to the loginWithAutoconnectMode method, and a session key for the Hub is returned (hubSessionKey).

  2. A multicast call is performed on a set of servers. This is defined by serverIds, which contains the IDs of the servers to target. In the background, system.list_system is called on each server’s XMLRPC API.

  3. Hub aggregates the results and returns the response in the form of a map. The map has two entries:

    • Successful: list of responses for those peripheral servers where the call succeeded.

    • Failed: list of responses for those peripheral servers where the call failed.

Listing 3. Example Python Script for Auto-Connect Authentication:
#!/usr/bin/python3
import xmlrpc.client

HUB_XMLRPC_API_URL = "<HUB_XMLRPC_API_URL>"
HUB_USERNAME = "<USERNAME>"
HUB_PASSWORD = "<PASSWORD>"

client = xmlrpc.client.ServerProxy(HUB_XMLRPC_API_URL, verbose=0)

loginResponse = client.hub.loginWithAutoconnectMode(HUB_USERNAME, HUB_PASSWORD)
hubSessionKey = loginResponse["SessionKey"]

# Get the server IDs
serverIds = client.hub.listServerIds(hubSessionKey)

# Perform the needed operation
systemsPerServer = client.multicast.system.list_systems(hubSessionKey, serverIds)
successfulResponses = systemsPerServer["Successful"]["Responses"]
failedResponses = systemsPerServer["Failed"]["Responses"]

for system in successfulResponses:
  print(system)

# Log out
client.hub.logout(hubSessionKey)