[TOC]
This repository contains the components of the Keycloak App for the UCS Appcenter.
The app uses Keycloak to provide a SAML and OpenID Connect provider.
The docker image used in the app is keycloak, provided by RedHat.
- Keycloak comes with a Realm
master
by default. - Additionally the UCS Keycloak App creates a realm
UCS
.
- This Keycloak App is configured to use "User Federation" in the Keycloak Realm named "UCS".
- The "User Federation" configured in the
UCS
usesuid=sys-idp-user,cn=users,$ldap_base
to bind to OpenLDAP. - The "User Federation" is configured to not sync user accounts from LDAP to Keycloak.
- Keycloak automatically acts as SAML IdP. For each SP (SAML or OIDC) a "Client" configuration needs to be created
in Keycloak.
- In its initial version, the Keycloak App creates a "Client" for the UMC on the FQDN of the host which it is installed on.
- Keycloak can be configured to federate out to other IdPs. If several authentication sources are possible,
e.g. a "User federation" and two external IdPs then Keycloak will show a login page to the user, where the user
needs to select the method. There are ways to preselect (either hardcode in Keycloak config or pass
&kc_idp_hint=foo
with the login URL). Keycloak will not iterate over possible authentication sources. Names may need to get mapped to ensure uniqueness. See Keycloak docs for details.
TODO: Anything special to explain here?
The app can be configured with app settings.
To integrate other services, they often require URIs for the identity provider endpoints, they are available at https://ucs-sso-ng.$(hostname -d)/.well-known/openid-configuration
TODO: Update the following statement, probably outdated with the change from keycloak.$(hostname -f)
to ucs-sso-ng.$(hostname -d)
:
The apache2 reverse proxy config is at /var/lib/univention-appcenter/apps/keycloak/config/vhost.conf
and there are some UCR variables apache2/vhosts/.*
set autoamtically during join via the joinscript /usr/lib/univention-install/50keycloak.inst
installed on the host (uploaded to the provider-portal as app/inst ).
All tests with browsers should happen in a new private browser window. This ensures that no cookies or old sessions are present.
All tests have to happen using actual hostnames with correct and verfifyable certificates. The involved services rely on and test for signed and trusted certificates.
All tests have to pass before releasing a new version of the keycloak app.
An app specific test can be added here as app/test. This test is executed in our "normal" keycloak tests and during the app install and upgrade tests.
https://jenkins2022.knut.univention.de/job/UCS-5.0/job/Apps/job/keycloak/
We have unit test for the univention-ldap-mapper. These are executed during the image build.
The core of the product test should be done in ucs-test-keycloak and our jenkins jobs. We should try to automate as much as possible. Currently we have jobs for (https://jenkins2022.knut.univention.de/job/UCS-5.0/job/UCS-5.0-3/view/Keycloak/)
- Login Performance
- Product Tests
- Maria DB setup
- Setup with two backup's
- UPdate scenario
- add here what we have to test manually
- move the tests from the app specific test to ucs-test-keycloak
See app/ for app center integration files and https://docs.software-univention.de/app-center/5.0/en/configurations.html#installation-scripts
Builds the keycloak image and pushes it in our local gitlabe registry.
The name of the image if gitregistry.knut.univention.de/univention/components/keycloak-app:$NAME_OF_BRANCH
or gitregistry.knut.univention.de/univention/components/keycloak-app:latest
for the main
branch.
The idea is that every MR has its own image and QA can use this to setup an environemt for testing.
The app in the test appcenter always uses the image from the main
branch.
Before releasing a new version the image has to be transfered to our external
registry (see docker-job). In this process the image of the app is changed to
e.g. docker.software-univention.de/keycloak-keycloak:19.0.2-ucs1
.
The latest version on the test appcenter will always point to the "main" branch image. If you want to setup keycloak with an image of your MergeRequest, do:
univention-app update
- change the image name in the latest compose file in the local cache, e.g.
/var/cache/univention-appcenter/appcenter-test.software-univention.de/5.0/keycloak_20230201094428.compose
- install the app
- if the app is already installed, run
univention-app configure keycloak
Konfigure keycloak:
# activate SSO login portal tile
udm portals/entry modify --dn "cn=login-saml,cn=entry,cn=portals,cn=univention,$(ucr get ldap/base)" --set activated=TRUE
# set umc idp server to keycloak (default is still simplesamlphp)
ucr set umc/saml/idp-server="https://ucs-sso-ng.$(ucr get domainname)/realms/ucs/protocol/saml/descriptor"
service slapd restart
Or use the https://jenkins2022.knut.univention.de/job/UCS-5.0/job/UCS-5.0-3/view/Keycloak/job/UcsKeycloakEnvironment/ Jenkins job
to create a test environment (primary + keycloak and backup + keycloak). The docker image for the keycloak app can be changed via
the KEYCLOAK_IMAGE
parameter.
To find out the IPs of your two systems, you have to consult the console output of the Jenkins job and find lines like
10:01:12 [primary] Requesting IPv4 address..
10:01:12 [primary] Requesting IPv4 address: done (MAC=52:54:00:5d:8a:29 IPv4=10.207.183.251)
[...]
10:01:15 [backup1] Requesting IPv4 address..
10:01:16 [backup1] Requesting IPv4 address: done (MAC=52:54:00:cb:d4:2b IPv4=10.207.183.252)
Then add the following to your /etc/hosts
:
10.207.63.20 master.ucs.test
10.207.63.21 backup.ucs.test
10.207.63.20 ucs-sso-ng.ucs.test
# 10.207.63.21 ucs-sso-ng.ucs.test # if we want to test keycloak on the backup
- The "univention-authenticator" Keycloak SPI is an extension written in Java.
- It is shipped as part of the UCS Keycloak App, but not configured by default.
- If configured properly (TODO: details pending) it allows creating a "shadow user account" in UDM after successful authentication against an external IdP (see page 13 of the Summit presentation.
The script update-appcenter-test.sh can be used to build and upload the files from the repository for the latest test app center app version
Copy this block to the release issue and do all of them:
- update changelog
- run update-appcenter-test.sh
- update docker image names (appcenter test)
- run keycloak product tests (errata_update and release_update == public)
- release the documentation:
- Update the
DOC_TARGET_VERSION
variable in .gitlab-ci.yml to the new app version. The variable makes sure that the new app version has a dedicated documentation. - Add an appropriate changelog entry to docs/changelog.rst and follow the recommendation at https://keepachangelog.com/en/1.0.0/.
- If documentation for a new feature or for a change is part of the regular text in the documentation, highlight it with the versionadded, versionchanged or deprecated directive.
- After running the production job for the documentation in the pipeline, update the symlink
latest
the new version in the keycloak-app directory of the docs.univention.de repository.
- Update the
- release the app:
- go to omar
- run TODO
- check released app (currenty manual testing)
- Write mail to [email protected]
After the release we need to create a new "test" version in the appcenter for our tests.
- create another app version in the test appcenter
- update
Version
inapp/ini
- run
update-appcenter-test.sh
For local documentation builds, see Build Sphinx documents locally.