Implement Somfy multi-account (Ginaite/BOB) authentication flow #2087

Summary

The new-generation Somfy TaHoma app (com.somfy.homeapp) no longer authenticates directly against the Overkiz enduserAPI. It now sits on a multi-tier Somfy identity/account stack (Keycloak "Ginaite" -> BOB back-office -> regional Overkiz cloud). To keep supporting current Somfy accounts, the client needs to implement this flow and exchange a Somfy JWT for an Overkiz session.

Notably, the new multi-account setup is also multi-region: a single Somfy login can span homes across different Overkiz regional clusters (EMEA/APAC/SNABA), with the correct server selected per site. This is new, since previously a Somfy account mapped to a single server.

Flow (prod URLs, in order)

1. Login (OIDC + PKCE), obtain JWT

https://ginaite-prod.ovkube.net/realms/somfy-tahoma/protocol/openid-connect/auth
https://ginaite-prod.ovkube.net/realms/somfy-tahoma/protocol/openid-connect/token

• client_id=somfy-client
• kc_idp_hint=somfy-customer
• redirect_uri=com.somfy.homeapp
• scope=openid, response_type=code, code_challenge_method=S256

2. List accounts/homes (BOB back-office), Authorization: Bearer <JWT> + X-Api-Key: 184638B3FBE874ACD24C14FBD657B

GET https://backoffice-service.ovkube.net/site-api/public/v1/sites?withGateways=true
GET https://backoffice-service.ovkube.net/site-api/public/v1/sites/current
GET https://backoffice-service.ovkube.net/site-api/public/v1/sites/{siteOid}

Hierarchy: Site (siteOid) -> subSites -> gateways (gatewayId = TaHoma box PIN). This is what enables multiple homes per account and account sharing/roles.

3. Pick the regional Overkiz server per site (region = BusinessArea, derived from the site owner's country):

4. Exchange the JWT for an Overkiz session, Authorization: Bearer <JWT>

POST https://ha101-1.overkiz.com/enduser-mobile-web/enduserAPI/enduser/jwt/createToken

5. Normal Overkiz enduserAPI usage (existing client logic, session from step 4):

https://ha101-1.overkiz.com/enduser-mobile-web/enduserAPI/setup
.../enduserAPI/events/register
.../enduserAPI/exec/apply

Optional, energy data: https://energy-management.ovkube.net (same Bearer JWT + X-Api-Key).