Preparing for the SONIA development environment

In the SONIA development environment of the Ostfalia computing centre, Keycloak runs locally on your own machine. It is reachable through the SONIA environment’s proxy on port 443 at https://id.dev.sonia.de. During backend login, TYPO3 redirects the browser there. For this to work, every development machine needs two preparations:

1. Hosts entry: 127.0.0.1 id.dev.sonia.de must be in the hosts file. There is no public DNS record, and the name is supposed to point to your own machine.
2. Root certificate: the certificate of id.dev.sonia.de is issued by the Ostfalia RZ Root CA. Its root certificate ofca.crt must be trusted in the operating system’s certificate store (keychain); otherwise the browser reports an insecure connection.

Both are needed only once per machine and require administrator rights. The certificate is in the project at config/certs/ofca.crt. The containers need none of this: the certificate is already part of the image, and docker-compose.override.yml redirects the name inside the container to the machine.

Check the fingerprint before trusting the certificate. It must read exactly:

# Linux and macOS
openssl x509 -in config/certs/ofca.crt -noout -subject -fingerprint -sha256

# Windows (PowerShell)
$c = [Security.Cryptography.X509Certificates.X509Certificate2]::new((Resolve-Path .\config\certs\ofca.crt).Path)
[BitConverter]::ToString([Security.Cryptography.SHA256]::Create().ComputeHash($c.RawData))   # with - instead of :

On Linux (Debian, Ubuntu) and macOS, the hosts file is /etc/hosts. Only add the entry if it is still missing:

grep -q 'id\.dev\.sonia\.de' /etc/hosts || echo '127.0.0.1 id.dev.sonia.de' | sudo tee -a /etc/hosts

macOS caches name lookups, so flush the cache afterwards:

sudo dscacheutil -flushcache; sudo killall -HUP mDNSResponder

On Linux, the entry takes effect immediately. Check that the name points to 127.0.0.1:

getent hosts id.dev.sonia.de      # Linux
dscacheutil -q host -a name id.dev.sonia.de   # macOS

The hosts file is C:\Windows\System32\drivers\etc\hosts. It can only be changed with administrator rights. The easiest way is a PowerShell run as administrator:

$hosts = "$env:SystemRoot\System32\drivers\etc\hosts"
if (-not (Select-String -Path $hosts -Pattern 'id\.dev\.sonia\.de' -Quiet)) {
    Add-Content -Path $hosts -Value "`r`n127.0.0.1 id.dev.sonia.de"
}
ipconfig /flushdns

Alternatively, start Notepad with “Run as administrator”, open the file and append the line 127.0.0.1 id.dev.sonia.de. Some virus scanners block changes to the hosts file; in that case, allow the change there.

Check (the answer must come from 127.0.0.1):

Resolve-DnsName id.dev.sonia.de

The certificate goes into the System keychain and is marked there as a trusted root CA. In the terminal (in the project directory):

sudo security add-trusted-cert -d -r trustRoot \
    -k /Library/Keychains/System.keychain config/certs/ofca.crt

With the user interface: double-click ofca.crt and choose the “System” keychain. Then open the certificate “Ostfalia RZ Root CA” under “System” in the Keychain Access app and set Trust → When using this certificate to “Always Trust”.

Safari, Chrome and Edge use the keychain directly. Firefox picks it up as well, as long as security.enterprise_roots.enabled is true in about:config (the default). Restart the browser afterwards.

Described for Debian and Ubuntu. The certificate is in PEM format and must be placed in /usr/local/share/ca-certificates/ with the extension .crt:

sudo cp config/certs/ofca.crt /usr/local/share/ca-certificates/ofca.crt
sudo update-ca-certificates

This makes curl, wget and other programs trust the certificate. On Linux, browsers partly have their own stores:

• Chrome/Chromium: current versions use the system store. Otherwise import it under Settings → Privacy and security → Security → Manage certificates, or add it to the NSS database on the command line (package libnss3-tools):

certutil -d sql:$HOME/.pki/nssdb -A -t "C,," -n "Ostfalia RZ Root CA" -i config/certs/ofca.crt

• Firefox: Settings → Privacy & Security → View Certificates → Authorities → Import, then tick “Trust this CA to identify websites”. On Ubuntu, Firefox is a Snap package and does not see the system store, so always import it this way there.

Restart the browser afterwards.

The certificate goes into the local computer’s “Trusted Root Certification Authorities” store. In a PowerShell run as administrator (in the project directory):

Import-Certificate -FilePath .\config\certs\ofca.crt -CertStoreLocation Cert:\LocalMachine\Root

# or with a command prompt run as administrator:
certutil -addstore -f Root config\certs\ofca.crt

With the user interface: double-click ofca.crt → Install Certificate → Local Machine → Place all certificates in the following store → Trusted Root Certification Authorities → Finish. Confirm the security warning with “Yes” after checking the fingerprint.

Edge and Chrome use the Windows store directly. Firefox picks it up as long as security.enterprise_roots.enabled is true in about:config (the default). Restart the browser afterwards.

With the SONIA environment and Keycloak running, the realm configuration must be retrievable without certificate errors:

# Linux and macOS
curl -sS https://id.dev.sonia.de/realms/sonia/.well-known/openid-configuration | head -c 200

# Windows (PowerShell)
(Invoke-WebRequest https://id.dev.sonia.de/realms/sonia/.well-known/openid-configuration -UseBasicParsing).StatusCode

In the browser, https://id.dev.sonia.de/realms/sonia shows the padlock without a warning. After that, the backend login at http://typo3-v14.localhost:8088/typo3/ leads straight to the Keycloak sign-in.