Q&A: How does the SAML workflow look like

scheinig · April 23, 2019, 1:13pm

Question:

How does the saml workflow looks like, and which certificates are used.

Answer:

We want to have a look into the service provider initiated login. This can be separated in 3 steps
The SP (servcie provider) is the UMC in this case.

Memory hook:
SP is the one, where you can do much more then login

Step 1.

The SP (e.g. UMC) contacts the IdP (simpleSAMLphp) with a SAML message: “Please login in this $user for me” This message is signed with

http://$SP_FQDN/univention/saml/metadata

You can check the used metadata with

curl https://$(hostname -f)/univention/saml/metadata

Debug:
The used certificate should be the actual server certificate (/etc/univention/ssl/hostname.domain/cert.pem).
If the certificate is not the server certificate, you should try to restart the univention-management-console-web-server

Step 2.

The contacted IdP checks the signature of the SP with the SP-metadata saved in the local LDAP

Memory hook:
IdP is the one for login ONLY

udm saml/serviceprovider list
or
univention-ldapsearch -LLL "(&(serviceProviderMetadata=*)(univentionObjectType=saml/serviceprovider)(SAMLServiceProviderIdentifier=https://$(hostname -f)/univention/saml/metadata))" serviceProviderMetadata | ldapsearch-wrapper | ldapsearch-decode64

Debug: The certificate of /etc/univention/ssl/hostname.domain/cert.pem should be found here.

The ucr variable

ucr info umc/saml/sp-server
umc/saml/sp-server: <empty>
 Defines the SAML 2.0 service provider fqdn. If the variable is unset, the fqdn of the UCS system and all IP addresses are used.

is used for SP adjustments.
After adjustments
/usr/share/univention-management-console/saml/update_metadata
can be used to update the saml/serviceprovider entry.

If the certificates are okay and if the user entered valid credentials, than the IdP signs its SAML message to the SP: “OK, the $user has authenticated successful” with

https://ucs-sso.$domäne/simplesamlphp/saml2/idp/metadata.php

Debug: here the ucs-sso certificate should be used: /etc/univention/ssl/ucs-sso.$domain/cert.pem
If there is nothing available (404) make sure the univention-saml package is still installed.

Step 3.

The SP checks the answers signature with

/usr/share/univention-management-console/saml/idp/ucs-sso.$domain.xml

Debug:
This file is created via setting the corresponding UCR variable:

ucr set umc/saml/idp-server=https://${ucs_server_sso_fqdn}/simplesamlphp/saml2/idp/metadata.php

If ucs-sso.$domain.xml is not there and setting the UCR fails,make sure the univention-saml package is (still) installed.

Sometimes a picture says more than thousand words, so here is a diagram:

saml-flow2

Additional Information:

How are these files are created:

The Joinscript:

view /usr/lib/univention-install/92univention-management-console-web-server.inst

“Tell the UMC which IdP you can trust” → umc/saml/idp-server
The joinscript includes:

creating the service provider via udm
writes the metadata to the LDAP with:

/usr/share/univention-management-console/saml/update_metadata

→ tell the IdP about the new SP

writes the IdP metadata to

/usr/share/univention-management-console/saml/idp/ucs-sso.$domain.xml

via

ucr set umc/saml/idp-server="https://ucs-sso.$domain/simplesamlphp/saml2/idp/metadata.php"

→ all in one with:

univention-run-join-scripts --force --run-scripts 92univention-management-console-web-server.inst

The listener

univention-saml-simplesamlphp-configuration.py writes the metadata from the LDAP to:

/etc/simplesamlphp/metadata.d/https\:__$(hostname -f)_univention_saml_metadata.php

Addition stunnel:

Stunnel transfers simplesamlphp sessions.
Currently the stunnel config uses saml/idp/certificate/certificate and saml/idp/certificate/privatekey to establish the stunnel connections between the SAML IdPs.
This is nice to know, if the UCS is directly exposed to the internet and must serve different HTTPS certificates.
E.g. scenarios where one needs to change the SSO FQDN from ucs-sso.domain.name to sso.internet.domain
Reconfigure UCS Single Sign On
In this case the stunnel connections will fail, because:

stunnel uses saml/idp/certificate which matches ucs-sso.domain.name - stunnel will do a checkHost against ucs/server/sso/fqdn which we changed to sso.internet.domain and the certificate verification will fail. This leads to a non-working stunnel connection:

journalctl -fu stunnel4 or syslog

Dec 18 10:32:13 srv-ucsm01 univention-saml-stunnel: LOG4[12]: CERT: No matching host name found Dec 18 10:32:13 srv-ucsm01 univention-saml-stunnel: LOG4[12]: Rejected by CERT at depth=0: C=DE, ST=DE, L=DE, O=Musterstadt, OU=Univention Corporate Server, CN=ucs-sso.musterstadt.de, emailAddress=ssl@musterstadt.de Dec 18 10:32:13 srv-ucsm01 univention-saml-stunnel: LOG3[12]: SSL_connect: 1416F086: error:1416F086:SSL routines:tls_process_server_certificate:certificate verify failed Dec 18 10:32:13 srv-ucsm01 simplesamlphp[23839]: 3 [cb60e63e1d] SimpleSAML_Error_Exception: Error 8 - MemcachePool::get(): Server unix:///var/run/univention-saml/srv-ucsb01.musterstadt.de.socket (tcp 0, udp 0) failed with: Read failed (socket was unexpectedly closed) (0)

Impact: Stunnel does not work properly and logins are flaky