Migration guide: SimpleSAMLPHP to Keycloak

Download PDF

Services using SAML

4.1. Services using SAML#

The following examples demonstrate the migration of services that use SAML for authentication and SimpleSAMLphp as IdP to Keycloak as IdP.

4.1.1. UCS Portal#

You can configure the UCS Portal to use SAML for authentication. For a detailed description of how to configure the UCS Portal to use Keycloak as a SAML IDP, refer to Use Keycloak for login to Univention Portal in the Univention Keycloak app documentation [1].

4.1.2. Nextcloud#

This section is about migrating the Nextcloud app to use Keycloak as SAML IDP for the SAML authentication. It assumes that your environment meets the following requirements:

  • The configuration of the app Nextcloud is complete and done.

  • The SAML sign-in for Nextcloud works with SimpleSAMLphp as SAML IDP.

  • The UCS domain has the latest version of the app Keycloak installed.

To setup Nextcloud for SAML with Keycloak, use the following steps:

  1. To create a SAML client for Nextcloud, run the following commands on the UCS system that has the Keycloak app installed. Replace NEXTCLOUD_FQDN with the FQDN of the UCS system that has Nextcloud installed.

    Listing 4.1 Create SAML client for Nextcloud in Keycloak#
    $ NEXTCLOUD_FQDN="REPLACE with NEXTCLOUD_FQDN"
$ univention-keycloak saml/sp create \
  --metadata-url="https://$NEXTCLOUD_FQDN/nextcloud/apps/user_saml/saml/metadata" \
  --role-mapping-single-value

  2. To obtain the Keycloak base URL and certificate, run the following commands on the UCS system that has Keycloak installed:

    Listing 4.2 Retrieve public certificate of Keycloak#
    $ univention-keycloak saml/idp/cert get \
   --as-pem \
   --output "/tmp/keycloak.cert"

    The output of the command in Listing 4.2 saves the certificate in the file /tmp/keycloak.cert. Copy this file to the UCS system that has the Nextcloud app installed.

    Listing 4.3 Retrieve public certificate and Keycloak base URL#
    $ univention-keycloak get-keycloak-base-url

    The command in Listing 4.3 outputs the base URL of your Keycloak server. Replace SSO_URL in the following instruction with this value.

  3. To change the IdP settings for Nextcloud, run the following commands on the UCS system that has it installed. Copy the certificate file /tmp/keycloak.cert from Listing 4.2 to the UCS system with Nextcloud installed and replace SSO_URL.

    Listing 4.4 Configure the Nextcloud app to use Keycloak as IdP#
    $ SSO_URL="REPLACE WITH SSO_URL"
$ univention-app shell nextcloud sudo -u www-data /var/www/html/occ saml:config:set \
  --idp-x509cert="$(cat /tmp/keycloak.cert)" \
  --general-uid_mapping="uid" \
  --idp-singleLogoutService.url="$SSO_URL/realms/ucs/protocol/saml" \
  --idp-singleSignOnService.url="$SSO_URL/realms/ucs/protocol/saml" \
  --idp-entityId="$SSO_URL/realms/ucs" 1

To validate the setup, visit the sign-in page of your Nextcloud app and initiate a single sign-on. Nextcloud redirects you to Keycloak for authentication. You can use Nextcloud after authentication.

See also

Nextcloud

in Univention App Catalog

4.1.3. Google Workspace Connector#

This section provides a step-by-step guide for migrating the Google Connector app to use Keycloak as SAML IDP. The migration assumes that your environment meets the following requirements:

  • The configuration of the app Google Workspace Connector is complete and done.

  • The SAML login for your Google Workspace works with SimpleSAMLphp.

  • You have the administrator credentials for your Google Workspace Admin Console for the SAML service configuration.

  • The UCS domain has the latest version of the app Keycloak installed.

To setup Google Workspace Connector for SAML with Keycloak use the following steps:

  1. Create a SAML SP, the client, for Google Workspace Connector in Keycloak. Run the following commands on the UCS system that has Keycloak installed:

    Listing 4.5 Create SAML client for Google Workspace Connector in Keycloak#
    $ google_domain="REPLACE_WITH_NAME_OF_YOUR_GOOGLE_DOMAIN"
$ univention-keycloak saml/sp create \
    --client-id google.com \
    --assertion-consumer-url-post "https://www.google.com/a/$google_domain/acs" \
    --single-logout-service-url-post "https://www.google.com/a/$google_domain/acs" \
    --idp-initiated-sso-url-name google.com \
    --name-id-format email \
    --frontchannel-logout-off
$ univention-keycloak user-attribute-ldap-mapper \
  create univentionGoogleAppsPrimaryEmail
$ univention-keycloak saml-client-nameid-mapper create \
  google.com \
  univentionGoogleAppsPrimaryEmail \
  --user-attribute univentionGoogleAppsPrimaryEmail \
  --mapper-nameid-format urn:oasis:names:tc:SAML:1.1:nameid-format:emailAddress

  2. For the configuration of the SAML settings of your Google Workspace you need the public certificate and the base URL of the Keycloak server. Run the following commands on the UCS system that has Keycloak installed:

    Listing 4.6 Retrieve public certificate and Keycloak base URL#
    $ univention-keycloak saml/idp/cert get --as-pem --output /tmp/keycloak.cert

    The output of the command in Listing 4.6 is the certificate. Copy the file /tmp/keycloak.cert to your local client computer.

    Listing 4.7 Retrieve public certificate and Keycloak base URL#
    $ univention-keycloak get-keycloak-base-url

    The command in Listing 4.7 outputs the base URL of your Keycloak server. Replace SSO_URL in the following instruction with this value.

  3. Change the Third-party SSO profile for your organisation settings in the Google Workspace Admin console of your google domain.

    1. Open the URL https://admin.google.com and login with your administrator account.

    2. Go to Security ‣ Authentication ‣ SSO with third-party IdP.

    3. Open Third-party SSO profile for your organisation.

    4. Change Sign-in page URL to SSO_URL/realms/ucs/protocol/saml.

    5. Change Sign-out page URL to SSO_URL/realms/ucs/protocol/openid-connect/logout.

    6. To upload the Keycloak certificate in /tmp/kc.cert from Listing 4.6, click REPLACE CERTIFICATE.

    7. To activate the settings, click Save.

  4. Change the link in the UCS portal entry Google Workspace login for the IdP initiated single sign-on. On your UCS Primary Directory Node run the following commands:

    Listing 4.8 Change portal entry for Google Workspace login to IdP initiated single sign-on#
    $ google_domain="REPLACE WITH NAME_OF_YOUR_GOOGLE_DOMAIN"
$ SSO_URL="REPLACE WITH SSO_URL"
$ udm portals/entry modify \
  --dn "cn=SP,cn=entry,cn=portals,cn=univention,$(ucr get ldap/base)" \
  --set link='"en_US" "'"$SSO_URL"'/realms/ucs/protocol/saml/clients/google.com?RelayState=https://www.google.com/a/'"$google_domain"'/ServiceLogin"'

To validate the setup, visit https://google.com and sign in with one of the UCS user accounts enabled for Google Workspace. Also, verify the UCS portal entry Google Workspace login for the IdP initiated single sign-on.

Warning

The automatic redirect after the single sign-out doesn’t work with Keycloak.

See also

Google Workspace Connector

in Univention App Catalog

4.1.4. Microsoft 365 Connector#

The example illustrates how to migrate the app Microsoft 365 Connector to use Keycloak as SAML IDP. It assumes that your environment meets the following requirements:

  • The configuration of the app Microsoft 365 Connector is complete and done.

  • The SAML login for your Azure Active Directory domain works with SimpleSAMLphp.

  • You have a client computer with Microsoft Windows installed on it and a working internet connection on the client computer to configure SAML in Azure Active Directory.

  • You have the Administrator credentials for your Azure Active Directory domain for the SAML service configuration.

  • The UCS domain has the latest version of the app Keycloak installed.

To setup Microsoft 365 Connector for SAML with Keycloak, use the following steps:

  1. Create a SAML SP, the client, for Microsoft 365 Connector in Keycloak. Run the following commands on the UCS system that has Keycloak installed:

    Listing 4.9 Create SAML client for Microsoft 365 Connector in Keycloak#
    # get the saml client metadata xml from microsoft
$ curl https://nexus.microsoftonline-p.com/federationmetadata/saml20/federationmetadata.xml > /tmp/ms.xml

# create the client in keycloak
$ univention-keycloak saml/sp create \
  --metadata-file /tmp/ms.xml \
  --metadata-url urn:federation:MicrosoftOnline \
  --idp-initiated-sso-url-name MicrosoftOnline \
  --single-logout-service-url-redirect https://login.microsoftonline.com/login.srf \
  --name-id-format persistent

# create a SAML nameid mapper
$ univention-keycloak saml-client-nameid-mapper create \
  urn:federation:MicrosoftOnline \
  entryUUID \
  --mapper-nameid-format "urn:oasis:names:tc:SAML:2.0:nameid-format:persistent" \
  --user-attribute entryUUID \
  --base64

  2. For the configuration of the SAML settings of your Azure Active Directory domain you need the public certificate and the base URL of the Keycloak server. Run the following commands on the UCS system that has Keycloak installed:

    Listing 4.10 Retrieve public certificate and Keycloak base URL#
    $ univention-keycloak saml/idp/cert get --output /tmp/keycloak.cert
$ cat /tmp/keycloak.cert

    The output of the command in Listing 4.10 is the certificate. Replace KEYCLOAK_CERTIFICATE in the following steps with this value.

    Listing 4.11 Retrieve public certificate and Keycloak base URL#
    $ univention-keycloak get-keycloak-base-url

    The command in Listing 4.11 outputs the base URL of your Keycloak server. Replace SSO_URL in the following steps with this value.

  3. To configure the SAML settings for the Azure Active Directory domain, copy the following code block to your Microsoft Windows client computer. Replace the values for SSO_URL, KEYCLOAK_CERTIFICATE, the Azure Active Directory domain name and credentials and run the script in the Microsoft Windows PowerShell.

    Listing 4.12 Change Azure Active Directory domain authentication to use Keycloak#
    # CHANGE this according to your setup/environemt
$sso_url = "replace with SSO_URL"
$signing_cert = "replace with KEYCLOAK_CERTIFICATE"
$domain = "YOUR AZURE DOMAIN NAME"
$username = "YOUR AZURE DOMAIN ADMIN"
$password = "PASSWORD OF YOUR AZURE DOMAIN ADMIN"
$realm = "REALM OF CHOICE (usually ucs)"
# CHANGE end

$issuer_uri = "$sso_url/realms/$realm"
$logon_uri = "$sso_url/realms/$realm/protocol/saml"
$passive_logon_uri = "$sso_url/realms/$realm/protocol/saml"
$logoff_uri = "$sso_url/realms/$realm/protocol/saml"
$pass = ConvertTo-SecureString -String "$password" -AsPlainText -Force
$credential = New-Object -TypeName System.Management.Automation.PSCredential -ArgumentList $username, $pass
$o365cred = Get-Credential $credential

Install-Module MSOnline
Import-Module MSOnline
Connect-MsolService -Credential $o365cred

Set-MsolDomainAuthentication -DomainName "$domain" -Authentication Managed
Set-MsolDomainAuthentication `
    -DomainName "$domain" `
    -FederationBrandName "UCS" `
    -Authentication Federated `
    -ActiveLogOnUri "$logon_uri" `
    -PassiveLogOnUri "$passive_logon_uri" `
    -SigningCertificate "$signing_cert" `
    -IssuerUri "$issuer_uri" `
    -LogOffUri "$logoff_uri" `
    -PreferredAuthenticationProtocol SAMLP

Get-MsolDomain
Pause

  4. To change the link in the UCS portal entry Microsoft 365 Login for the IdP initiated single sign-on, run the following commands on your UCS Primary Directory Node:

    Listing 4.13 Change portal entry for Microsoft 365 Login to IdP initiated single sign-on#
    $ SSO_URL="REPLACE WITH SSO_URL"
$ realm="ucs"
$ udm portals/entry modify \
  --dn "cn=office365,cn=entry,cn=portals,cn=univention,$(ucr get ldap/base)" \
  --set link='"en_US" "'"$SSO_URL"'/realms/"'"$realm"'"/protocol/saml/clients/MicrosoftOnline"'

To validate the setup, visit https://www.microsoft365.com/ and sign in with one of the UCS user accounts enabled for Microsoft 365. Also, verify the UCS portal entry Microsoft 365 Login for the IdP initiated single sign-on.

Warning

The automatic redirect after the single sign-out doesn’t work with Keycloak.

4.1.4.1. Migration of additional logical Identity Provider instances#

It is possible to configure additional logical Identity Provider instances e.g. for single-sign on using the Microsoft 365 Connector wizard with multiple Entra ID (Azure AD) connections.

If multiple logical Identity Provider instances were configured according to Extended Configuration, each connection needs to be migrated individually to Keycloak. Since e.g. Entra ID (Azure AD) explicitly needs different entity IDs for each connection, this entails the creation of a new IdP for each Entra ID (Azure AD) connection. In Keycloak this is represented by a new realm with it’s own set of endpoints.

To create a new logical IdP in Keycloak, run the following commands on your UCS Keycloak host.

Listing 4.14 Create a new logical IdP in Keycloak#
$ ADDITIONAL_LOGICAL_IDP="REPLACE WITH MICROSOFT 365 AD CONNECTION NAME"
$ univention-keycloak proxy-realms create "$ADDITIONAL_LOGICAL_IDP"

Please note that this automatically creates a SAML SP client for Microsoft 365 Connector in the new Keycloak realm.

Use the following call to get the certificate of your newly created IdP

Listing 4.15 Get the certificate of the newly created Realm#
$ univention-keycloak saml/idp/cert get \
   --realm-id="$ADDITIONAL_LOGICAL_IDP" \
   --output "/tmp/keycloak-"$ADDITIONAL_LOGICAL_IDP".cert"
 cat /tmp/keycloak-"$ADDITIONAL_LOGICAL_IDP".cert

Using this certificate as $signing_cert and the ADDITIONAL_LOGICAL_IDP as $realm, follow the steps from Change Azure Active Directory domain authentication to use Keycloak onward to update the SAML settings for the Entra ID Azure Active Directory domain.

Repeat these steps for each additional configured Entra ID (Azure AD) connection.

For the portal tile (Change portal entry for Microsoft 365 Login to IdP initiated single sign-on) you may want to slightly deviate: If you need one tile per Entra ID (Azure AD) connection, you would create a new one instead of modifying the original:

Listing 4.16 Change portal entry for Microsoft 365 Login to IdP initiated single sign-on#
$ SSO_URL="REPLACE WITH SSO_URL"
$ realm="REPLACE WITH REALM"
$ udm portals/entry create \
  --position "cn=entry,cn=portals,cn=univention,$(ucr get ldap/base)" \
  --set name="office365-$realm" \
  --set displayName='"en_US" "Microsoft 365 Login ('"$realm"')"' \
  --set description='"en_US" "Single Sign-On Microsoft 365 ('"$realm"')"' \
  --set icon="$(base64 /var/www/office365.png)" \
  --set linkTarget=newwindow \
  --set link='"en_US" "'"$SSO_URL"'/realms/"'"$realm"'"/protocol/saml/clients/MicrosoftOnline"'
$ udm portals/category modify \
  --dn "cn=domain-service,cn=category,cn=portals,cn=univention,$(ucr get ldap/base)" \
  --append entries="cn=office365-$realm,cn=entry,cn=portals,cn=univention,$(ucr get ldap/base)"

This would make the tile visible for all users, though. You may want to limit visibility to certain groups, although this would in turn require users to be logged in before seeing the tile. See UCS portal page in UCS 5.0 Manual [2].

See also

Microsoft 365 Connector

in Univention App Catalog

On this page