setupSSO.sh/README.md

setupSSO.sh

Small script to setup SAML SSO for Univention UCS. If you don't have Univention UCS server, this script is useless.

Introduction

Univention UCS is a Identity and Access Management (IAM) solution, based on OpenLDAP. It provides also a SAML SSO solution. You can learn more about UCS at the Univention website at https://www.univention.de/

Basically the script follows the guide at https://help.univention.com/t/reconfigure-ucs-single-sign-on/16161 and Scenario 1, Portal and Single Sign On at different FQDNs. Additionally it also incorporates the part SAML SSO of https://help.univention.com/t/renewing-the-ssl-certificates/37

The script will ask you, if your UCS servers shares a common root password or not. In case it does, it will store the password and re-use it when connecting to all the servers. It will also asks you for the Domain Administrator password. This will also be used within the script.

In fact, both passwords are stored in /tmp with a random filename generated by mktemp. The Domain Administrator password will be transferred to each UCS server to be invoked with the join scripts. After the join scripts ran successfully the password file will be deleted again. Nonetheless, please verify that all temp files in /tmp on all servers are deleted immediatedly after running the setupSSO.sh script.

Requirements

To be able to run this script, you need to fulfill the following requirements:

• a UCS environment that qualifies for Scenrio 1: SSO and Portal on differen domains.
• being able to SSH from Primary Domain Node to all other UCS nodes. Maybe you need to generate SSH keys by running ssh-keygen
• know your passwords for root and the Domain Administrator, usually Administrator - you will be prompted several times. If you have SSH PubkeyAuthentication set to yes, prompting for root passwords shouldn't happen, but depending on your thread model PubkeyAuthentication might not be desireable.
• working DNS resolution for your SSO and Portal hosts.
• LetsEncrypt SSL cert for your SSO host for the Apache2 webserver (see ucr search letsencrypt/domains)

Usage

Basically just invoke the script the its name. No additional parameters needed, just edit the script and set the domains for SSO_FQDN and PORTAL_FQDN before running the script. Anyway, use at your own risk. 🙂

Example

root@ucs:~# /root/bin/setupSSO.sh

✅ We are running on Primary Domain Node. Very good!

setupSSO.sh supports two scenarios:
1) SSO and portal on different domains
2) SSO and portal on the same domain

Which scenario is applicable for your setup? (1/2) 1
Please enter SSO domain (default: ucs-sso.windfluechter.net): sso.windfluechter.net
Please enter portal domain (default: portal.windfluechter.net):

Do all UCS hosts share the same root password (y/n) y

Please enter your common root password:
Please enter Domain Administrator password:
Checking sso.windfluechter.net & portal.windfluechter.net target(s):

For the Apache2 webserver certificates of the SSO domain sso.windfluechter.net
the following LetsEncrypt certifcate will be used. A self-signed SSL
certificate will be used internally to sign the metadata of SSO.

ucs.windfluechter.net   ✅ sso.windfluechter.net        <-- your SSO domain
ucs.windfluechter.net   ❌ ucs-sso.windfluechter.net
ucs.windfluechter.net   ❌ ucs.windfluechter.net
ucs2.windfluechter.net  ✅ portal.windfluechter.net     <-- your portal domain
ucs2.windfluechter.net  ❌ ucs2.windfluechter.net

✅ Your SSO domain is included in your LetsEncrypt SSL certificate on ucs.windfluechter.net.
✅ Your portal domain is included in your LetsEncrypt SSL certificate on ucs2.windfluechter.net.


Checking the self-signed SSL certificate of Identity Provider (IdP) for metadata signing

When there is no existing SSL cert for the IdP for sso.windfluechter.net a new cert will be created.
If a cert does exist it will be checked of a validity >1 year and you will be prompted to
create a new certficate or continue with the current SSL certificate.
If the cert will expire within a year, the SSL certificate will be renewed. The reason
for this is the metadata signing: Each time you create a new certificate you need to
update the metadata on every Service Provider (SP) that uses the SSO IdP.

See below for more information about your certificate:
Certificate "sso.windfluechter.net" with serial number 0F is invalid (revoked)
Certificate "sso.windfluechter.net" with serial number 10 is invalid (revoked)
[...]
⚠️  Your SSL cert already exists and will expire on Jun 24 21:16:45 2027 GMT
Delete the existing SSL cert for sso.windfluechter.net and create a new one (y) or continue (c) with current cert? c
=====================================================================================================
[...]
=====================================================================================================
✅  Deploying SSO was successful as there were no errors.


Do you want to dump the SSL cert of the SSO Identity Provider (IdP)? (y/n) y
-----BEGIN CERTIFICATE-----
MIIFezCCBGOgAwIBAgIBRzANBgkqhkiG9w0BAQsFADCB0DELMAkGA1UEBhMCREUx
[...]
jdbilZlvDOR7PFEFhk0v
-----END CERTIFICATE-----

ToDo

• Implement Scenario 2, Portal and Single Sign On at the same FQDN
• Implement setting up a UCS Policy for new hosts

Disclaimer

Although I do work for Univention, I wrote the script in my spare time to reliably setup SAML SSO for my UCS environment, because I perceived the existing guide at help.univention.de as a little error-prone.