Migration guide: SimpleSAMLPHP to Keycloak

Download PDF

Migration of services using SAML for authentication

3.3. Migration of services using SAML for authentication#

This section gives a general idea about the migration of services that use SimpleSAMLphp for the authentication to Keycloak as a SAML client.

The general approach for the migration includes the following:

  • Install the latest version of the Keycloak app in the UCS domain.

  • Get an overview of all the services that use SimpleSAMLphp and their settings.

  • Check and create attribute mappers for LDAP. Selected LDAP attributes become available to Keycloak.

  • Create a SAML SP, the client, and necessary attribute mappers in Keycloak for every service that uses SimpleSAMLphp as SAML IDP.

  • Change the SAML settings in the services to use Keycloak as a SAML IDP and validate the setup.

The following sections explain each step of the migration in detail.

3.3.1. Create LDAP attribute mappers#

Some services require specific LDAP attributes, for example, the service requires the user’s email address, which the SAML IDP can pass to the service during authentication. Create appropriate LDAP attribute mappers based on your needs.

The user object in Keycloak doesn’t have every attribute available in the LDAP directory. You can find a list of attributes mapped to Keycloak in Import of user attributes from UCS to Keycloak of Univention Keycloak app documentation [1].

To check, if the attribute mapping is sufficient for your services, compare the list with the attributes that SimpleSAMLphp reads from the LDAP directory. To get a complete list of LDAP attributes available to SimpleSAMLphp, run the following command:

Listing 3.5 List IDP LDAP attributes#
$ udm saml/idpconfig list | sed -n 's/LdapGetAttributes: //p'

If you find attributes, that don’t map to Keycloak, you can create an LDAP mapper object through the tool univention-keycloak or directly in the Keycloak Admin Console. To create a mapping on the command line, run the following command:

Listing 3.6 Create LDAP attribute mapping#
$ univention-keycloak user-attribute-ldap-mapper create $LDAP_ATTRIBUTE_NAME

3.3.2. Create a SAML client in Keycloak#

Each SAML SP, or client, that you have configured for SimpleSAMLphp, requires a corresponding SAML SP created in Keycloak with the appropriate settings. Depending on the specific settings of your SAML SP, there are several ways to create a SAML client:

To inspect the SimpleSAMLphp configuration on the command line, run:

Listing 3.7 List SimpleSAMLphp Provider configuration#
$ udm saml/serviceprovider list

Through the UMC module SAML Identity Provider. For a description of each LDAP attribute in this object, see Adding a new external service provider in UCS 5.0 Manual [2].

Use one of the following approaches that best suits your needs:

  1. If your application provides a metadata XML file for the SAML client settings, you can create a client in Keycloak with the command line tool univention-keycloak by using either the URL to that XML file or the file itself.

    Listing 3.8 Create basic Keycloak client#
    # with URL
$ univention-keycloak saml/sp create --metadata-url="$URL"

# with local XML file
$ univention-keycloak saml/sp create \
  --metadata-url="REPLACE WITH SAML CLIENT ISSUER NAME OR URL" \
  --metadata-file "/path/to/xml"

  2. You can transfer each of the SAML client settings from the saml/serviceprovider object to the Keycloak client. The tool univention-keycloak has flags and options for each of these settings.

    Table 3.1 Mapping between SimpleSAMPLphp settings and univention-keycloak saml/sp create options#

    UMC SAML Identity Provider module / UDM attribute name

    Keycloak GUI

    univention-keycloak saml/sp create option

    Service provider activation status: isActivated

    Enabled

    --not-enabled

    Service provider identifier: Identifier

    Client ID

    --client-id

    Respond to this service provider URL after login: AssertionConsumerService

    Valid redirect URI. This value is also automatically parsed from a metadata XML file.

    --valid-redirect-uris

    Format of NameID attribute: NameIDFormat

    Name ID format

    --name-id-format

    Description of this service provider: serviceproviderdescription

    Description

    --description

    URL to the service provider’s privacy policy: privacypolicyURL

    Policy URI

    --policy-url

    Respond to this service provider URL after login: AssertionConsumerService

    Assertion Consumer Service POST Binding URL

    --assertion-consumer-url-post

    Single logout URL for this service provider: singleLogoutService

    Logout Service POST Binding URL

    --single-logout-service-url-post

    Allow transition of LDAP attributes to the service provider: simplesamlAttributes

    n/a

    Not available in Keycloak, only implicitly configured if specific attributes are configured to be transitioned to the service provider.

    Name of the attribute that is used as NameID: simplesamlNameIDAttribute

    n/a

    Not available during the creation of the SAML SP client. Instead another mappings object has to be created for Keycloak, see Configure user attributes for SAML response.

    List of LDAP attributes to transmit: LDAPattributes

    n/a

    Not available during the creation of the SAML SP client. Instead another mappings object has to be created for Keycloak, see Configure user attributes for SAML response.

    Value for attribute format field: attributesNameFormat

    n/a

    Not available during the creation of the SAML SP client. Instead another mappings object has to be created for Keycloak, see Configure user attributes for SAML response.

  3. You can also use the Keycloak Admin Console to create SAML clients manually or to adjust clients created with univention-keycloak saml/sp create. You may want to consult the Keycloak documentation at Managing OpenID Connect and SAML Clients [4] about how to create clients in Keycloak.

  4. Some SAML clients may use custom configurations (e.g. with the attribute rawsimplesamlSPconfig of the saml/serviceprovider object). If you have a service configured in that way, please check the /etc/simplesamlphp/metadata.d/*.php files to get the appropriate settings for the client.

3.3.3. Configure user attributes for SAML response#

The following listing demonstrates how to create attribute mappings in Keycloak for the simplesamlNameIDAttribute and LDAPattributes settings of the saml/serviceprovider object. These mappings allow you to configure the unique identifier for the user and additional user attributes for the SAML response.

NameID attribute (simplesamlNameIDAttribute)

To map the attribute to Keycloak that uniquely identifies a user, create a so-called SAML client nameid mapper and attach it to the SAML SP. The table Table 3.2 shows which SimpleSAMLphp settings correspond to which options of the command univention-keycloak saml-client-nameid-mapper create.

Table 3.2 Mapping between SimpleSAMPLphp settings and univention-keycloak saml-client-nameid-mapper create options#

UMC SAML Identity Provider module / UDM attribute name

Keycloak GUI

univention-keycloak saml-client-nameid-mapper create option

Name of the attribute used as NameID: simplesamlNameIDAttribute

User attribute

--user-attribute

Format of NameID attribute: NameIDFormat

Mapper NameID format

--mapper-nameid-format

For example, a command might look like one of the following:

Listing 3.9 Create client nameid mapper#
$ univention-keycloak saml-client-nameid-mapper create CLIENTID MAPPERNAME \
  --user-attribute uid \
  --mapper-nameid-format urn:oasis:names:tc:SAML:1.1:nameid-format:unspecified
Additional user attributes (LDAPattributes)

Some SAML SP require additional attributes. The name of the attribute on the user object requires a mapping to the name of the attribute in the SAML assertion. The table Table 3.3 shows which SimpleSAMLphp settings correspond to which univention-keycloak saml-client-user-attribute-mapper create options.

Table 3.3 Mapping between SimpleSAMLphp settings and univention-keycloak saml-client-user-attribute-mapper create options#

UMC SAML Identity Provider module / UDM attribute name

Keycloak GUI

univention-keycloak saml-client-nameid-mapper create option

Value for attribute format field: attributesNameFormat

Name ID

--attribute-nameformat

List of LDAP attributes to transmit: LDAPattributes

User attribute, SAML attribute name

--user-attribute --attribute-name

You need to create such a mapper for each attribute listed in the SAML SP configuration. In Keycloak, you find flags to specify the name of the attribute to send:

--user-attribute:

is the attribute name present on the Keycloak user object.

--attribute-name:

is the SAML attribute utilizing the urn:oid namespace.

For example, a command might look like one of the following:

Listing 3.10 Create SAML client user attribute mapper#
$ univention-keycloak saml-client-user-attribute-mapper create CLIENTID MAPPERNAME \
  --user-attribute uid \
  --attribute-name urn:oid:0.9.2342.19200300.100.1.1

Note

To get a list of client IDs for all existing SAML SP clients Keycloak, run:

Listing 3.11 Get a list of client IDs for all existing SAML SP clients#
$ univention-keycloak saml/sp get

3.3.4. Configure SAML services to use Keycloak#

After creating SAML SP clients and mappers in Keycloak, the next step is to update the service settings to use Keycloak as IdP.

  1. Change the SAML settings in the services to use Keycloak as SAML IDP and validate the setup. The service needs some information about Keycloak as the IdP. This includes the Identity Provider Metadata URL, and the public certificate.

    The SAML Identity Provider Metadata endpoint for Keycloak is https://$sso_url/realms/ucs/protocol/saml/descriptor. You can obtain sso_url from the output of the following command:

    Listing 3.12 Lookup Keycloak base URL#
    $ sso_url="$(univention-keycloak get-keycloak-base-url)"

  2. It’s necessary to update the IdP public certificate in your SAML settings. You can obtain the Keycloak server certificate in PEM format with the following command:

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

How and where you need to configure this information in the service itself is very specific to the service, and this document can’t describe it in general terms. Consult the documentation of the service itself. To get a better idea of using SAML with Keycloak, take a look at the Services using SAML in the next section.

3.3.5. UCR variable differences#

This section describes the differences between UCR variables when using SimpleSAMLphp (SAML) and Keycloak.

3.3.5.1. Added variables#

Keycloak introduces the following UCR variables:

3.3.5.2. Renamed variables#

Keycloak uses the following variables known to be used for SAML before:

Table 3.4 UCR variable differences#

SAML

Keycloak

ucs/server/sso/fqdn

keycloak/server/sso/fqdn

ucs/server/sso/autoregistraton

keycloak/server/sso/autoregistration

ucs/server/sso/virtualhost

keycloak/server/sso/virtualhost

ucs/server/sso/password/change/server

keycloak/password/change/endpoint

saml/apache2/ssl/ca

keycloak/apache2/ssl/ca

saml/apache2/ssl/key

keycloak/apache2/ssl/key

saml/apache2/ssl/certificate

keycloak/apache2/ssl/certificate

saml/apache2/content-security-policy/.*

keycloak/csp/frame-ancestors

saml/idp/selfservice/check_email_verification

ucs/self/registration/check_email_verification

saml/idp/log/level

keycloak/log/level

saml/idp/selfservice/account-verification/error-title and saml/idp/selfservice/account-verification/error-title/.*

keycloak/login/messages/en/accountNotVerifiedMsg and keycloak/login/messages/de/accountNotVerifiedMsg

saml/idp/selfservice/account-verification/error-descr and saml/idp/selfservice/account-verification/error-descr/.*

keycloak/login/messages/en/accessDeniedMsg and keycloak/login/messages/de/accessDeniedMsg

3.3.5.3. No longer supported variables#

Keycloak doesn’t support the following UCR variables anymore:

  • saml/idp/authsource

  • saml/idp/ldap/debug

  • saml/idp/ldap/get_attribute

  • saml/idp/ldap/user

  • saml/idp/log/debug/enabled

  • saml/idp/negotiate/filter-subnets

  • saml/idp/session-duration

  • saml/idp/show-error-reporting

  • saml/idp/show-errors

  • saml/idp/technicalcontactemail

  • saml/idp/technicalcontactname

  • saml/idp/timezone

  • ucs/server/sso/certificate/download

  • ucs/server/sso/certificate/generation

Keycloak enables the following UCR variables with the LDAP federation:

  • saml/idp/ldap/enable_tls

  • saml/idp/negotiate starting with Keycloak app version 22.0.3-ucs1.

Keycloak sets the following UCR variables with the LDAP federation:

  • saml/idp/ldap/user

  • saml/idp/ldap/search_attributes

3.3.5.4. Not used anymore#

Keycloak doesn’t use the following UCR variables anymore and automatically sets a respective configuration:

  • saml/apache2/ssl/certificatechain

  • saml/idp/certificate/certificate

  • saml/idp/certificate/privatekey

  • saml/idp/https

Keycloak redirects to HTTPS automatically.

For cookies, the following UCR variables existed:

  • saml/idp/session-cookie/secure

  • saml/idp/session-cookie/samesite

  • saml/idp/language-cookie/secure

  • saml/idp/language-cookie/samesite

To set the cookie policy for Keycloak use the UCR variable keycloak/cookies/samesite. For possible values, see Univention Keycloak app documentation [1].

SAML doesn’t use the following UCR variables anymore:

  • stunnel/debuglevel

  • saml/idp/lookandfeel/theme

To set the theme in Keycloak, use the command ucr set ucs/web/theme=dark|light for ucs/web/theme.

Use univention-keycloak saml to handle the SAML integration done with the following UCR variables before:

  • saml/idp/enableSAML20-IdP

  • saml/idp/entityID

  • saml/idp/entityID/supplement/.*

On this page