Example SSO Implementation

In this example, SSO is implemented by exposing three endpoints with Uyuni, and using Keycloak 26.5.3 or later as the identity service provider (IdP).

To set up Single Sign-On (SSO) with Uyuni and Keycloak, you first configure the Keycloak identity provider, obtain its public SAML certificate, and set up the client and users. After that, you configure the Uyuni Server to trust Keycloak.

This example is provided for illustrative purposes only. SUSE does not recommend or support third-party identity service providers, and is not affiliated with Keycloak. For Keycloak support, see https://www.keycloak.org/.

You can install Keycloak directly on your machine, or run it in a container. In this example, we run Keycloak in a Podman container. For more information about installing Keycloak, see the Keycloak documentation at https://www.keycloak.org/guides#getting-started.

1. Setting up the identity service provider (Keycloak)

First, run Keycloak, create a realm, obtain the SAML public certificate, and configure the client.

Procedure: Setting up Keycloak

Install Keycloak in a Podman container, according to the Keycloak documentation.
Run the container using the -td argument to ensure the process remains running:
podman run -td --name keycloak -p 8080:8080 -e KEYCLOAK_ADMIN=admin -e KEYCLOAK_ADMIN_PASSWORD=admin quay.io/keycloak/keycloak:26.1.1 start-dev
Sign in to the Keycloak Admin Console as the admin user.

Create an authentication realm:

In the top-left corner, click the realm selector dropdown (showing master) and select Manage realms.

On the Manage realms page, click the Create realm button in the top-right corner.

In the Realm name field, enter a name (for example, MLM).

Click Create.

Obtain the SAML public certificate:

From the left navigation menu, click Realm settings.

Click the Keys tab.

Find the active RSA key (with provider rsa-generated) in the active keys table.

Click the Certificate button in that row.

Copy the entire Base64-encoded certificate from the modal that opens. Keep this certificate handy for the server configuration.

Add Uyuni as a Client:

From the left navigation menu, click Clients.

Click Create client.

In the Client type field, select SAML.

In the Client ID field, enter the Uyuni Metadata endpoint. For example: https://<FQDN_MLM>/rhn/manager/sso/metadata

Click Next.

In the Valid redirect URIs field, enter the Uyuni Assertion Consumer Service (ACS) endpoint. For example: https://<FQDN_MLM>/rhn/manager/sso/acs

Click Save.

Fine-tune client settings:

Under the Settings tab, scroll down to the SAML capabilities section:

Toggle Sign assertions to On.

In the Signature algorithm field, select RSA_SHA1.

In the SAML Signature Key Name field, select Key ID.

Click Save.

Under the Keys tab:

Toggle Client signature required to Off.

Under the Advanced tab, scroll down to the Fine Grain SAML Endpoint Configuration section:

In both the Assertion Consumer Service POST Binding URL and Assertion Consumer Service Redirect Binding URL fields, enter the Uyuni ACS endpoint. For example: https://<FQDN_MLM>/rhn/manager/sso/acs

In the Logout Service POST Binding URL field, enter the Uyuni SLS endpoint. For example: https://<FQDN_MLM>/rhn/manager/sso/sls

In the Logout Service Redirect Binding URL field, enter the root URL of your Uyuni instance. For example: https://<FQDN_MLM>/

Click Save.

Configure Client Scope and Mappers:

From the left navigation menu, click Client scopes.

Click role_list in the list.

Click the Mappers tab, and then click the role list mapper.

Toggle Single Role Attribute to On, and click Save.

Go back to Clients, click your Uyuni client ID (https://<FQDN_MLM>/rhn/manager/sso/metadata), and click the Client scopes tab.

Click the dedicated scope (for example, https://<FQDN_MLM>/rhn/manager/sso/metadata-dedicated).

Click Configure a new mapper.

Select User Attribute from the list, and configure the mapper with these details:

In the Name field, enter uid.

In the Property field, select username.

In the SAML Attribute Name field, enter uid.

Click Save.

Create Users:

From the left navigation menu, click Users.

Click Add user.

In the Username field, enter a username that matches an existing Uyuni user (for example, the administrative user).

Click Create.

Click the Credentials tab, click Set password, set a password for the user, and toggle Temporary to Off, click Save and confirm by clicking Save password.

2. Setting up the Uyuni server

After Keycloak is ready, configure the Uyuni Server to use single sign-on.

Ensure that the users whom you intend to authenticate using SSO already exist in Uyuni. You can create users manually in the Uyuni Web UI, or use the command-line interface or API (using PAM-enabled or passwordless authentication).

Procedure: Setting up the Uyuni server

On the Uyuni Server, open the /etc/rhn/rhn.conf configuration file.

Add the following parameters. Replace <FQDN_MLM> with the fully qualified domain name of your Uyuni installation, <FQDN_IDP> with the FQDN of your Keycloak server, <REALM> with your realm name (for example, MLM), and <CERTIFICATE> with the SAML public certificate Base64-encoded string obtained from Keycloak in the previous steps:

java.sso = true

java.sso.onelogin.saml2.debug = true

java.sso.onelogin.saml2.sp.entityid                       = https://<FQDN_MLM>/rhn/manager/sso/metadata
java.sso.onelogin.saml2.sp.assertion_consumer_service.url = https://<FQDN_MLM>/rhn/manager/sso/acs
java.sso.onelogin.saml2.sp.single_logout_service.url      = https://<FQDN_MLM>/rhn/manager/sso/sls

java.sso.onelogin.saml2.idp.entityid                   = http://<FQDN_IDP>:8080/realms/<REALM>
java.sso.onelogin.saml2.idp.single_sign_on_service.url = http://<FQDN_IDP>:8080/realms/<REALM>/protocol/saml
java.sso.onelogin.saml2.idp.single_logout_service.url  = http://<FQDN_IDP>:8080/realms/<REALM>/protocol/saml

java.sso.onelogin.saml2.idp.x509cert = -----BEGIN CERTIFICATE----- <CERTIFICATE> -----END CERTIFICATE-----

# Organization Metadata (Optional)
java.sso.onelogin.saml2.organization.name = SUSE Multi-Linux Manager
java.sso.onelogin.saml2.organization.displayname = SUSE Multi-Linux Manager
java.sso.onelogin.saml2.organization.url = https://<FQDN_MLM>
java.sso.onelogin.saml2.organization.lang =

# Contacts (Optional)
java.sso.onelogin.saml2.contacts.technical.given_name = SUSE Multi-Linux Manager Admin
java.sso.onelogin.saml2.contacts.technical.email_address = admin@example.com
java.sso.onelogin.saml2.contacts.support.given_name = SUSE Multi-Linux Manager Admin
java.sso.onelogin.saml2.contacts.support.email_address = admin@example.com

Save your changes and restart the spacewalk service to apply them:
```
mgradm restart
```
Navigate to the Uyuni Web UI. You should be redirected to the Keycloak login screen, and successfully log in back to Uyuni upon authentication.

3. Troubleshooting

If you encounter issues when authenticating with single sign-on, use these steps to diagnose:

Verify Logs: Look for SSO errors in /var/log/rhn/rhn_web_ui.log. Detailed logging is enabled when java.sso.onelogin.saml2.debug = true is set in /etc/rhn/rhn.conf.
User Not Found: If you see "User not found" or redirection fails after Keycloak authentication, ensure the username in Keycloak matches the username in Uyuni exactly. Users must be pre-created in Uyuni.
Signature and certificate errors: If you see "Signature verification failed", verify that the certificate in java.sso.onelogin.saml2.idp.x509cert matches the active RSA certificate displayed under the Keys tab in Keycloak Realm Settings, and ensure that Sign assertions is toggled to On in the client settings.
Invalid Redirect URI: If Keycloak displays "Invalid parameter: redirect_uri" on redirection, verify that Valid redirect URIs in client settings in Keycloak is set to https://<FQDN_MLM>/rhn/manager/sso/acs.