Neues Modul 50_VolvoConnect unter Verwendung der neuen OAUTH2 Methode von Volvo

[stefan.apetz]

Magst du Screenshots schicken, bitte.

[StefanStrobel]

Hallo Stefan,

ich hatte im Sommer mal HTTPMOD erweitert, um die Daten für meinen Volvo eleganter auslesen zu können, hab es dann aber bleiben lassen, weil die Tokens auch bei Erneuerung per refresh_token nach einer Woche nicht mehr gültig waren und man sich somit jede Woche neu anmelden musste. Hat sich das geändert oder hast Du dafür eine Lösung gefunden?

Gruß
  Stefan

[stefan.apetz]

Moin Stefan,

der Token bleibt erhalten, auch wenn man fhem oder das ganze Linux darunter neu startet. Bei mir auch schon länger als eine Woche ohne Neu-Abfrage.

Hier eine detaillierte Beschreibung der Umsetzung:


Token-Verwaltung im VolvoConnect-Modul

Bei der Erstanmeldung wird über set <Name> reauth ein Volvo-Login gestartet. Nach der Anmeldung wird der Wert des URL-Parameters code mit set <Name> authCode <code> an FHEM übergeben. Dieser Autorisierungscode ist kurzlebig und nur einmal verwendbar.

Das Modul tauscht den Code gegen ein Access- und ein Refresh-Token. Beide werden zusammen mit dem internen Gültigkeitszeitpunkt im FHEM-Key-Value-Store gespeichert. Die Tokenwerte selbst werden nicht als Readings angezeigt.

Automatische Token-Erneuerung

Das Access-Token wird beim nächsten Authentifizierungs- beziehungsweise Abruflauf erneuert, sobald der interne Gültigkeitszeitpunkt erreicht ist. Das Modul plant dafür keinen separaten Timer zum exakten Ablaufzeitpunkt ein. Die Prüfung erfolgt beim Start und anschließend im konfigurierten Abrufrhythmus.

Für den Refresh berücksichtigt das Modul einen Sicherheitsabstand zum vom Server gemeldeten Ablauf: Bei längerer Laufzeit wird der Refresh-Zeitpunkt bis zu zehn Minuten vorverlegt, bei kurzen Laufzeiten um zehn Prozent. Ist ein Token für einen Fahrzeugbefehl bereits abgelaufen, wird vor dem Befehl ebenfalls ein Refresh versucht. Antwortet die Befehls-API mit HTTP 401, erneuert das Modul das Token und wiederholt den Befehl einmal.

Wann ist eine neue Anmeldung erforderlich?

Eine erneute Anmeldung ist nötig, wenn kein Refresh-Token vorhanden ist oder Volvo den Refresh ablehnt, zum Beispiel weil das Token ungültig geworden oder die Berechtigung widerrufen wurde. Dann set <Name> reauth ausführen und nach dem Volvo-Login einen neuen Autorisierungscode übergeben.

Ein fehlgeschlagener Refresh startet keine automatische Browser-Anmeldung. Der Fehler wird im Status und im Reading lastError angezeigt. Nach Änderungen an Client-ID, Client-Secret, VCC API Key oder Scopes sollte ebenfalls reauth ausgeführt werden. Eine Änderung der Scopes löscht die gespeicherten Tokens automatisch.

Technischer Hintergrund

Das Modul verwendet den OAuth2 Authorization-Code-Ablauf mit PKCE (S256). Es berechnet aus einem Code-Verifier eine SHA-256-Challenge für die Volvo-Login-URL. Nach dem Login wird der Autorisierungscode zusammen mit Redirect-URI und Verifier am Volvo-Token-Endpunkt eingelöst; Client-ID und Client-Secret dienen der Client-Authentifizierung.

Token-Austausch und Refresh erfolgen nicht-blockierend über FHEMs HttpUtils_NonblockingGet. So blockieren die Netzwerkzugriffe den FHEM-Hauptprozess nicht. get <Name> tokenInfo zeigt, ob Tokens vorhanden sind und wie lange das Access-Token noch gültig ist – nicht aber die Tokenwerte selbst.


Die tatsächliche Gültigkeitsdauer des Access-Tokens kommt in der Volvo-Antwort im Feld expires_in; sie kann also variieren. Wenn dieses Feld fehlt, nimmt das Modul 3600 Sekunden (eine Stunde) an.

Das Modul erneuert das Token vorsorglich vor dem tatsächlichen Ablauf: bei Laufzeiten über zehn Minuten bis zu zehn Minuten vorher, bei kürzeren Laufzeiten um zehn Prozent. Der Refresh läuft dann beim nächsten Abruf oder Fahrzeugbefehl. Die Berechnung steht in VolvoConnect_TokenCallback.

Die Gültigkeitsdauer des Refresh-Tokens wird vom Modul nicht selbst festgelegt; es verwendet es, bis Volvo es nicht mehr akzeptiert.

[stefan.apetz]

# VolvoConnect v1.1.0 - Keycloak OAuth2 Migration

## 🚀 Wichtige Mitteilung zur Volvo-Authentifizierung

Volvo beendet den **Legacy Volvo ID Service** zum **31. Januar 2027** und migriert vollständig zur neuen **Keycloak-basierten OAuth2 IAM**.

Mit der neuen Version **1.1.0** des VolvoConnect-Moduls unterstützen wir bereits beide Authentifizierungsmethoden und ermöglichen einen reibungslosen Übergang.

---

## 📋 Was ändert sich?

### OAuth2 Client ID – Erkennungsmerkmal

Volvo stellt ab sofort **nur noch neue OAuth2-Clients mit Keycloak bereit**. Die Client IDs unterscheiden sich deutlich:

| Authentifizierung | Client ID Prefix | Beispiel |
|---|---|---|
| **Legacy Volvo ID** | `dc-` | `dc-9n90l...` |
| **Keycloak IAM** (neu) | `vid-dcr-` | `vid-dcr-ke9pd4...` |

**Wichtig:** Wer ab jetzt bei Volvo eine neue App im Developer Portal erstellt, erhält automatisch eine `vid-dcr-*` Client ID – es gibt keine Legacy-Option mehr.

### OAuth2 Authorization Code

Der Authorization Code in der Redirect-URL hat sich ebenfalls verändert:
- **Legacy:** Kürzere Code-Struktur
- **Keycloak:** Längerer Code mit UUID-Format (z.B. `60a14da9-9bcd-b1c2-a6c4-83bb05b91b33.xyz.81bd9932...`)

---

## ⚙️ Umstellung auf Keycloak

### Schritt 1: Neue Volvo Developer Portal App

Falls noch nicht geschehen, erstelle eine neue App im [Volvo Developer Portal](https://developer.volvocars.com):

1. **Neue App anlegen** (alte Apps können nicht editiert werden)
2. **Scopes aktivieren** für die benötigten Fahrzeugdaten:
  - `conve:battery_charge_level` (Batterie-Ladung)
  - `conve:fuel_status` (nur für Hybrid/Verbrenner)
  - `conve:odometer_status` (Kilometerstand)
  - `conve:trip_statistics` (Fahrtstatistiken)
  - Weitere `conve:*` Scopes je nach Bedarf
3. **Redirect URI** auf `https://fhem.fritz.box/redirect` einstellen (oder eure FHEM-Instanz)

Die neue App gibt euch einen **Client ID mit Prefix `vid-dcr-*`** und ein entsprechendes Secret.

### Schritt 2: FHEM-Konfiguration

```
attr <VolvoDevice> keycloakService 1
attr <VolvoDevice> client_id vid-dcr-...
attr <VolvoDevice> client_secret <euer-secret>
```

### Schritt 3: Authentifizierung durchführen

```
set <VolvoDevice> reauth
```

1. Volvo fragt jetzt, welche Daten das Modul zugreifen darf (z.B. "Standortverlauf erlauben?")
2. Nach der Freigabe werdet ihr zu `https://fhem.fritz.box/redirect` weitergeleitet
3. Die URL enthält nun einen **längeren Authorization Code**
4. Kopiert den Code und führt aus:
  ```
  set <VolvoDevice> authCode 60a14da9-9bcd-b1c2-a6c4-83bb05b91b33.mstR4R8j...
  ```
5. Das Modul tauscht den Code gegen einen Token aus

**Das war's!** Die grüne LED sollte bald erscheinen. 🟢

---

## 🔄 Weiterhin unterstützt: Legacy Volvo ID

Wer noch mit der alten Authentifizierung arbeitet:

```
attr <VolvoDevice> keycloakService 0
```

Die Legacy-Methode funktioniert weiterhin bis zum **31. Januar 2027**. Dies ermöglicht einen schrittweisen Übergang.

---

## ⚡ Was ist neu in der Fahrzeugerkennung?

Mit der neuen Version erkennt das Modul automatisch, welche Fahrzeugtypen und Datenquellen verfügbar sind:

Code Auswählen Erweitern

| Datentyp.         | Legacy | Keycloak | Anmerkung                                     |
|-------------------|--------|----------|-----------------------------------------------|
| Battery / Energie | ✅     | ✅        | Batterieladung, Reichweite, Ladezeit          |
| Odometer          | ✅     | ✅        | Kilometerstand                                |
| Statistics        | ✅     | ✅        | Durchschnittsverbrauch, Fahrtstatistiken      |
| Locations         | ✅     | ✅        | Fahrzeugstandort, Adresse, Reverse-Geocoding  |
| Doors / Windows   | ✅     | ✅        | Tür- und Fenster-Status                       |
| Warnings          | ✅     | ✅        | Fahrzeugwarnungen (Bremsflüssigkeit, etc.).   |
| Vehicle Info      | ✅     | ✅        | Bilder, Typ, Farbe, VIN                       |
| Capabilities      | ✅     | ⚠️        | Abhängig von Volvo-Freigabe                   |
**Hinweis Hybrid/E-Auto:** Reine E-Autos haben keine Fuel-API. Das ist normal und kein Fehler.

---

## 🔐 Sicherheit & Datenschutz

- Client Secrets werden **nicht im FHEM-Log** angezeigt (gekürzt)
- OAuth2-Tokens werden verschlüsselt gespeichert
- PKCE (RFC 7636) wird für beide Services verwendet
- Scopes sind granular – eure App fragt nur ab, was ihr erlaubt habt

---

## 🎯 Auswirkungen bei Volvo-Abkündigung

Ab dem 31. Januar 2027 werden Legacy-Clients (`dc-*`) nicht mehr funktionieren. **Wer bis dahin nicht migriert:**
- ❌ Authentifizierung schlägt fehl
- ❌ Keine Vehicle Data abrufbar
- ⚠️ Das Modul schlägt auf Keycloak-Only-Mode zurück

**Empfehlung:** Migriert jetzt, solange beide Systeme parallel laufen. So könnt ihr euren Setup testen.

---

## 📝 Für Entwickler & Module-Integratoren

Das VolvoConnect-Modul unterstützt jetzt duales OAuth2:

```perl
# Automatische Service-Erkennung
my $useKeycloak = VolvoConnect_IsKeycloakService($hash);

# Unterschiedliche Endpoints
if ($useKeycloak) {
    # auth.volvocars.com/realms/volvocars
    # Neue conve:* Scopes
} else {
    # volvoid.eu.volvocars.com (Legacy)
    # energy:state:read + conve:* Scopes
}
```

Bei Servicewechsel werden Caches automatisch invalidiert – ihr müsst nur das Attribut ändern.

---

## ❓ Häufige Fragen

**F: Muss ich sofort migieren?** 
A: Nein, Legacy funktioniert noch bis 31. Jan 2027. Aber: **Neue Apps sind nur noch mit Keycloak möglich**, also migriert am besten jetzt.

**F: Was wenn meine alte App noch funktioniert?** 
A: Sie können sie weiterverwenden (`keycloakService 0`). Ab dem 31. Jan 2027 wird sie jedoch deaktiviert.

**F: Warum bekomme ich 403 Forbidden bei manchen Daten?** 
A: Typischerweise:
- Scope nicht in der App aktiviert (Volvo Developer Portal checken)
- Fahrzeugdaten nicht für diese API verfügbar (z.B. `fuel_status` bei E-Autos)
- Scope nicht korrekt bei der OAuth-Anmeldung genehmigt

**F: Der Authorization Code funktioniert nicht ("Code not valid")?** 
A: OAuth2-Codes verfallen nach ca. 10 Minuten. Nach der Volvo-Anmeldung schnell den Code eingeben!

**F: Welche Scopes brauche ich wirklich?** 
A: Nur die, die euer Fahrzeug-Modell unterstützt:
- Battery/Energie: `conve:battery_charge_level`, `energy:capability:read`
- Standort: `location:read`
- Türen/Fenster: `conve:doors_status`, `conve:windows_status`
- Warnungen: `conve:warnings`

---

## 📦 Update durchführen

```
update all https://raw.githubusercontent.com/stapetz/fhem-modules/main/controls_volvo.txt
reload 50_VolvoConnect
```

Dann mit der neuen Keycloak-Config neu anmelden.

---

## 🙏 Feedback & Fragen

Falls ihr Probleme habt oder Fragen zur Migration:
- Postet hier im Thread
- Überprüft die Logs: `loglevel <Device> 4` für Debug-Output
- Zeigt die READINGS des Devices (bei Problemen)

Viel Erfolg beim Upgrade! 🚗🔋

[al_ro]

Hallo Stefan,

vielen Dank für dein Modul!
Ich nutze es seit gestern und habe seitdem alle 5 Minuten die Meldung "2026.11.08 08:53:10 3: Please define del first" im Log.
Mit Verbose 5 gibt es diese zusätzlichen Zeilen:
2026.11.08 08:53:10 4: https://auth.volvocars.com/realms/volvocars/protocol/openid-connect/token: HTTP response code 200
2026.11.08 08:53:10 5: HttpUtils https://auth.volvocars.com/realms/volvocars/protocol/openid-connect/token: Got data, length: 3365
2026.11.08 08:53:10 5: HttpUtils response header:
HTTP/1.0 200 OK
Content-Type: application/json
Pragma: no-cache
referrer-policy: no-referrer
x-content-type-options: nosniff
x-frame-options: SAMEORIGIN
x-robots-tag: none
Vary: Accept-Encoding
Content-Encoding: gzip
Cache-Control: no-store
Expires: Sun, 08 Nov 2026 07:53:10 GMT
Date: Sun, 08 Nov 2026 07:53:10 GMT
Content-Length: 1856
Connection: close
Strict-Transport-Security: max-age=15768000
2026.11.08 08:53:10 4: VolvoConnect (Volvo_XC90) - Token response received.
2026.11.08 08:53:10 4: VolvoConnect (Volvo_XC90) - Token data stored successfully (refresh token: yes).
2026.11.08 08:53:10 3: Please define del first
2026.11.08 08:53:10 5: Starting notify loop for Volvo_XC90, 2 event(s), first is authStatus: authenticated

Könntest du bitte mal nachschauen?

Danke dir, Alex.

[stefan.apetz]

Moin Alex,

erstmal danke, dass du das Modul nutzt.

Der Bug ist nur ein Schönheitsfehler. Das Modul sollte trotzdem laufen.

Ich habe den Bug schnell identifizieren können. Ich hoffe, das funktioniert in deinem Fall jetzt auch richtig.

Mache bitte in fhem ein update all, dann Shutdown restart und teste noch einmal. sollte jetzt laufen.

Liebe Grüße,
Stefan

[stefan.apetz]

Neue Version verfügbar

Das VolvoConnect-Modul hat einen deutlich verbesserten OAuth-Authentifizierungsprozess erhalten. Statt manuelles Kopieren und Einfügen von Authorization-Codes ist ab sofort ein interaktiver OAuth-Handler mit automatischer Device-Erkennung und One-Click-Code-Übergabe verfügbar. Funktioniert mit fhem über SSL super, geht mit Workaround aber auch mit fhem ohne SSL.

✨ Neue Features
1. Integrierter OAuth-Handler mit Device-Selector
Die neue index.html unter /fhem/volvoconnect/ zeigt nach erfolgreichem Volvo-Login automatisch:

✅ Alle verfügbaren VolvoConnect-Devices aufgelistet
✅ Auth-Status mit visuellen Badges:
🟢 authenticated (aktiv)
🔴 requires_auth (Authentifizierung erforderlich)
❓ unknown (Status unbekannt)
✅ "Set authCode" Button für jedes Device
✅ Automatische Bestätigung nach erfolgreichem Setzen
2. Neue empfohlene Redirect-URI
Diese URL sollte ab sofort im Volvo Cars Developer Portal eingetragen werden. Sie ersetzt die bisherige manuelle Methode.

3. Einfacher Workflow für Nutzer
Neuer Prozess:

Login-Link in FHEM anklicken
Bei Volvo authentifizieren
Automatisch auf /fhem/volvoconnect/ weitergeleitet
Device auswählen und "Set authCode" klicken
Fertig – Code ist gesetzt und Tokens werden automatisch ausgetauscht
Alter Prozess (optional noch unterstützt):

Code manuell aus URL kopieren
set Device authCode <code> eingeben
🔧 Einrichtung
Für neue Installationen:
Im Volvo Developer Portal:
Redirect URI: https://your-fhem-host/fhem/volvoconnect/index.html

your-fhem-host durch den eigenen FHEM-Hostnamen ersetzen
Wichtig: Mit index.html
Muss exakt mit dem FHEM-Attribut übereinstimmen
ℹ️ Hinweise für spezielle Setups
🔒 Für HTTPS-Nutzer:
Kein Problem – alles funktioniert out-of-the-box mit der neuen Redirect-URI.

🌐 Für HTTP-only Setups (kein SSL/TLS):
Volvo leitet trotzdem mit https://... weiter. Lösung:

In der Browser-Adressleiste einfach https:// zu http:// ändern
Die Handler-Seite funktioniert über beide Protokolle
Der Code wird dann korrekt an FHEM übermittelt
🛡� Mit Reverse-Proxy:
Funktioniert auch mit nginx, Apache etc. Die Redirect-URI muss nur die externe URL sein, die Volvo sieht.

📚 Dokumentation
Die komplette Dokumentation wurde aktualisiert:

✅ Neue OAuth-Workflow-Beschreibung
✅ Empfohlene Redirect-URI prominent gekennzeichnet
✅ Schritt-für-Schritt Anleitung für Developer Portal
✅ Hinweise für verschiedene Netzwerk-Setups
✅ Deutsche und englische Dokumentation
🚀 Update-Befehl
📝 Technische Details
Was wurde geändert:
index.html (www/volvoconnect/index.html)

Erweitert von einfacher Code-Anzeige zur interaktiven Device-Liste
Lädt alle VolvoConnect-Devices via FHEM-API
Zeigt Auth-Status mit Farbkennzeichnung
Sendet den Code automatisch an FHEM
Dokumentation (FHEM/50_VolvoConnect.pm)

OAuth-Workflow neu dokumentiert
Neue Redirect-URI als Standard markiert
Hinweise für verschiedene Setups
Beispiele aktualisiert


Backward-Kompatibilität:
✅ Alte Methode (manuelles Kopieren) funktioniert weiterhin
✅ Bestehende Installationen laufen ohne Änderungen weiter
✅ Nur die neue Seite bietet die erweiterte Funktionalität