Example SSO Implementation

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

Start by setting up the SUSE Manager Server, and the Keycloak IdP. Then you can add the endpoints as 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/.

Procedure: Setting Up the SUSE Manager Server

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

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

In the configuration file, determine the three endpoints to expose:

java.sso.onelogin.saml2.idp.entityid
java.sso.onelogin.saml2.idp.single_sign_on_service.url
java.sso.onelogin.saml2.idp.single_logout_service.url

In the IdP metadata, locate the public x509 certificate. It uses this format: <IdP_Address>/auth/realms/<Your_Realm>/protocol/saml/descriptor. In the configuration file, specify the public x509 certificate of the IdP:
```
java.sso.onelogin.saml2.idp.x509cert
```

When you have prepared the SUSE Manager Server, you can install Keycloak. You can install Keycloak directly on your machine, or run it in a container. In this example, we run Keycloak in a Docker container. For more information about installing Keycloak, see the Keycloak documentation at https://www.keycloak.org/getting-started/getting-started-docker.

Procedure: Setting Up the Identity Service Provider

Install Keycloak in a Docker container, according to the Keycloak documentation.

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

docker run -td --name=idp -p 8080:8080 -e KEYCLOAK_USER=<user> -e KEYCLOAK_PASSWORD=<password> quay.io/keycloak/keycloak:9.0.2

Sign in the Keycloak Web UI as a privileged user, and create a realm using these details:
- In the Name field, enter a name for the realm. For example, SUMA.
- Toggle the Enabled switch to On.
- In the Endpoints field, type SAML 2.0 Identity Provider Metadata. This endpoint is <IdP_Address>/auth/realms/<Realm_Name>/protocol/saml/descriptor which describes the endpoints and certificate in the SUSE Manager configuration file.

When you have Keycloak running and set up, you can add the endpoints. Keycloak refers to endpoints as clients.

Procedure: Adding Endpoints as Clients

In the Keycloak Web UI, create a new client using these details:
- 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>/rhn/manager/sso/metadata.
- In the Client Protocol field, select SAML.
- Toggle the Include AuthnStatement switch to On.
- 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.
- In the Canonicalization Method field, select Exclusive.
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>/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>/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

In the Keycloak Web UI, navigate to the Clients Client Scopes tab and assign role_list as the default client scope.
Navigate to the Clients Mappers tab and add a user attribute Uid mapper, using the default values. This SAML attribute is expected by SUSE Manager.
Navigate to the Users Admin section and create an administrative user. This user does not need to match the SUSE Manager administrative user.
Navigate to the Users Role Mappings tab, add a uid attribute with a value that matches the username of the SUSE Manager administrative user.
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 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.