Documentation survey

Example SSO Implementation

In this example, SSO is implemented by exposing three endpoints with SUSE Multi-Linux Manager, and using Keycloak 21.0.1 or later as the identity service provider (IdP).

Start by installing the Keycloak IdP, then setting up the SUSE Multi-Linux Manager Server. Then you can add the endpoints as Keycloak clients, and create users.

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.

Procedure: Setting Up the Identity Service Provider

  1. Install Keycloak in a Podman container, according to the Keycloak documentation.

  2. Run the container using the -td argument to ensure the process remains running:

    podman run -td --name keycloak -p 8080:8080 -e KEYCLOAK_USER=admin -e KEYCLOAK_PASSWORD=admin quay.io/keycloak/keycloak:21.0.1

  3. Sign in the Keycloak Web UI as the admin user, and create an authentication realm using these details:

    • In the Name field, enter a name for the realm. For example, MLM.

    • In the Endpoints field, click the SAML 2.0 Identity Provider Metadata link. This will lead you to a page where you will see the endpoints and certificate to copy into the SUSE Multi-Linux Manager configuration file.

When you have installed Keycloak and created the realm, you can prepare the SUSE Multi-Linux Manager Server.

Procedure: Setting Up the SUSE Multi-Linux Manager Server

  1. On the SUSE Multi-Linux Manager Server, open the /etc/rhn/rhn.conf configuration file and edit these parameters. Replace <FQDN_MLM> with the fully qualified domain name of your SUSE Multi-Linux Manager installation:

    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

  2. In the configuration file, replace <FQDN_IDP> with the fully qualified domain name of your Keycloak server. Replace <REALM> with your authentication realm, for example MLM:

    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

  3. In the IdP metadata, locate the public x509 certificate. It uses this format: http://<FQDN_IDP>:8080/realms/<REALM>/protocol/saml/descriptor. In the configuration file, specify the public x509 certificate of the IdP:

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

Here is an example of rhn.conf on SUSE Multi-Linux Manager after enabling SSO:

java.sso = true


# This is the configuration file for Single Sign-On (SSO) via SAMLv2 protocol
# To enable SSO, set java.sso = true in /etc/rhn/rhn.conf
#
# Mandatory changes: search this file for:
# - YOUR-PRODUCT
# - YOUR-IDP-ENTITY
#
# See product documentation and the comments inline in this file for more
# information about every parameter.
#
#
#
#
# If 'strict' is True, then the Java Toolkit will reject unsigned
# or unencrypted messages if it expects them signed or encrypted
# Also will reject the messages if not strictly follow the SAML
#
# WARNING: In production, this parameter setting parameter MUST be set as "true".
# Otherwise your environment is not secure and will be exposed to attacks.
# Enable debug mode (to print errors)
# Identifier of the SP entity (must be a URI)
java.sso.onelogin.saml2.sp.entityid = https://MLMserver.example.org/rhn/manager/sso/metadata

# Specifies info about where and how the <AuthnResponse> message MUST be
# returned to the requester, in this case our SP.
# URL Location where the <Response> from the IdP will be returned
java.sso.onelogin.saml2.sp.assertion_consumer_service.url = https://MLMserver.example.org/rhn/manager/sso/acs

# Specifies info about where and how the <Logout Response> message MUST be
# returned to the requester, in this case our SP.
java.sso.onelogin.saml2.sp.single_logout_service.url = https://MLMserver.example.org/rhn/manager/sso/sls

# Identifier of the IdP entity (must be a URI)
java.sso.onelogin.saml2.idp.entityid = http://idp.example.org:8080/realms/MLM

# SSO endpoint info of the IdP. (Authentication Request protocol)
# URL Target of the IdP where the SP will send the Authentication Request Message
java.sso.onelogin.saml2.idp.single_sign_on_service.url = http://idp.example.org:8080/realms/MLM/protocol/saml

# SLO endpoint info of the IdP.
# URL Location of the IdP where the SP will send the SLO Request
java.sso.onelogin.saml2.idp.single_logout_service.url = http://idp.example.org:8080/realms/MLM/protocol/saml

# Public x509 certificate of the IdP
java.sso.onelogin.saml2.idp.x509cert = -----BEGIN CERTIFICATE----- MIIClzCCAX8CBgGC+tPbVjANBgkqhkiG9w0BAQsFADAPMQ0wCwYDVQQDDARTVU1BMB4XDTIyMDkwMTIwNTEwNFoXDTMyMDkwMTIwNTI0NFowDzENMAsG
A1UEAwwEU1VNQTCCASIwDQYJKoZIhvcNAQEBBQADggEPADCCAQoCggEBAMNSWJAalB5mShTkMBO5mrsOosyheEL8/A37WvuqDPwwEfm4x0cG7gmMHvONxYXZk+LRyzoQl2sBrNFrbMuwu5dnah5ZSMxQyUu697S280m4vIiegGaFdbgH+g4FGBu
eSis1ssMzTcES+NUuI7pLkMLNmSQtncESnoL9q2SyeQSwYtr5dz1ydl6IzjwtaWeyQ9EGJNtJtLk3U4+arLPCpHAwqFAnLO9NeYcRDNUKhNBs1v5mHP+L066PZu1/DkE0mSgy/+qXaS0CgZVKqz8qB+bvHVuAq9W60g1CjqZKbwvPu72p/7+d8z
9DxXPIZ1uxdqn19q/kLEP2TYLtgQobSHECAwEAATANBgkqhkiG9w0BAQsFAAOCAQEAga+raLMJDo/P/yN1Z6SGGocK227WFqovBiE/mLYlp5Ff0+0jS1US1plSppJ94xOr8j0m7HW0Wu5xCz6oOhzXTEtnfIbeRyr1Rms3BWdxyXgQ9bWUeZMWZ
HfDkTbhgRRmjDEwSSfEXRKQNvw41CpnlB36I0++ejgGnjDvH7BbkCaoW55JF5j6DT/WYR0n7MkEl2Ova9CH0e9X7Gny8iOAg26oziy06uy3P/lx9Z9RmHnvpvN/Q34SGEq9z/HlQVuP12UPj//iT21Jc17OOZFsZQXlGFTG6bXKmO42W8FdUDJU
ONoXZgjMb3eC7U691YyeowoqTY7mJKxNPprYY/lL0w== -----END CERTIFICATE-----


# Organization
java.sso.onelogin.saml2.organization.name = SUSE Manager admin
java.sso.onelogin.saml2.organization.displayname = SUSE Manager admin
java.sso.onelogin.saml2.organization.url = https://MLMserver.example.org
java.sso.onelogin.saml2.organization.lang =

# Contacts
java.sso.onelogin.saml2.contacts.technical.given_name = SUSE Manager admin
java.sso.onelogin.saml2.contacts.technical.email_address = MLM@example.org
java.sso.onelogin.saml2.contacts.support.given_name = SUSE Manager admin
java.sso.onelogin.saml2.contacts.support.email_address = MLM@example.org

You can add the SUSE Multi-Linux Manager endpoints to Keycloak. Keycloak refers to endpoints as clients.

Procedure: Adding Endpoints as Clients

  1. In the Keycloak Web UI, create a new client using these details:

    • In the Client type field, select SAML.

    • In the Client ID field, enter the endpoint specified in the server configuration file as java.sso.onelogin.saml2.idp.entityid. For example, https://<FQDN_MLM>/rhn/manager/sso/metadata.

  2. In the Settings tab, fine-tune the client using these details:

    • Toggle the Sign assertions switch to On.

    • In the Signature algorithm field, select RSA_SHA1.

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

  3. In the Keys tab:

    • Set Client signature required to Off.

  4. In the Advanced tab, in the Fine Grain SAML Endpoint Configuration section, add the two endpoints using these details:

    • In both the Assertion Consumer Service fields, enter the endpoint specified in the server configuration file as java.sso.onelogin.saml2.sp.assertion_consumer_service.url. For example, https://<FQDN_MLM>/rhn/manager/sso/acs.

    • In both the Logout Service fields, enter the endpoint specified in the server configuration file as java.sso.onelogin.saml2.sp.single_logout_service.url. For example, https://<FQDN_MLM>/rhn/manager/sso/sls.

When you have added the endpoints as clients, you can configure the client scope, and map the users between Keycloak and SUSE Multi-Linux Manager.

Procedure: Configuring Client Scope and Mappers

  1. In the Keycloak Web UI, navigate to the Clients  Client scopes tab and assign role_list as the default client scope.

  2. Navigate to the Client_scopes  Mappers tab and add a mapper for user attribute uid, using the default values. This SAML attribute is expected by SUSE Multi-Linux Manager.

  3. Navigate to the Client_scopes  Mappers and click on role_list mapper. Set Single Role Attribute to On.

  4. Navigate to the Users  Admin section and create an administrative user. This user does not need to match the SUSE Multi-Linux Manager administrative user.

  5. Navigate to the Users  Role mappings tab, add an attribute named uid with a value that matches the username of the SUSE Multi-Linux Manager administrative user.

  6. Navigate to the Users  Credentials tab, and set the same password as used by the SUSE Multi-Linux Manager administrative user. . Save your changes.

When you have completed the configuration, you can test that the installation is working as expected. Restart the SUSE Multi-Linux Manager Server to pick up your changes, and navigate to the SUSE Multi-Linux Manager Web UI. If your installation is working correctly, you are redirected to the Keycloak SSO page, where you can authenticate successfully.