Documentation survey

Example SSO Implementation

In this example, SSO is implemented by exposing three endpoints with SUSE 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 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, SUMA.

    • 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 Manager configuration file.

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

Procedure: Setting Up the SUSE Manager Server

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

    java.sso.onelogin.saml2.sp.entityid                       = https://<FQDN_SUMA>/rhn/manager/sso/metadata
java.sso.onelogin.saml2.sp.assertion_consumer_service.url = https://<FQDN_SUMA>/rhn/manager/sso/acs
java.sso.onelogin.saml2.sp.single_logout_service.url      = https://<FQDN_SUMA>/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 SUMA:

    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 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://sumaserver.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://sumaserver.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://sumaserver.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/SUMA

# 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/SUMA/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/SUMA/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://sumaserver.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 = suma@example.org
java.sso.onelogin.saml2.contacts.support.given_name = SUSE Manager admin
java.sso.onelogin.saml2.contacts.support.email_address = suma@example.org

You can add the SUSE 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_SUMA>/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_SUMA>/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_SUMA>/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 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 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 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 Manager administrative user.

  6. Navigate to the Users  Credentials tab, and set the same password as used by the SUSE 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 Manager Server to pick up your changes, and navigate to the SUSE Manager Web UI. If your installation is working correctly, you are redirected to the Keycloak SSO page, where you can authenticate successfully.