Gerätecredentials

Ein Credential ist das, womit sich ein Gerät anmeldet. Jedes Gerät hat höchstens ein aktives Credential. Geheimnisse werden nur einmal angezeigt, wenn sie ausgestellt werden, und Hermetry speichert nur einen Hash. Diese Seite erklärt die drei Credential-Typen und wie sie ausgestellt, rotiert, ersetzt und widerrufen werden.

Zum Verwalten von Credentials wird die Berechtigung Gerätecredentials verwalten benötigt (standardmäßig Administratoren). LoRaWAN-Sensoren, Gateway-Kindgeräte und abgefragte Geräte haben kein eigenes Credential.

Die drei Typen

Typ	Angezeigt als	Wie sich das Gerät anmeldet	Geheimnis
Access-Token	Access-Token	MQTT-Benutzername = das Token, leeres Passwort, beliebige Client-ID. HTTP: `Authorization: Bearer <token>`.	32 zufällige Zeichen, von Hermetry erzeugt.
MQTT-Basic	MQTT-Basic (Benutzername und Passwort)	Ein Benutzername und ein Passwort, optional mit fixierter Client-ID. Eine Client-ID allein meldet nie an.	Ein generiertes 32-stelliges Passwort oder eines, das Sie wählen.
X.509-Zertifikat	X.509-Zertifikat	Ein Client-Zertifikat (gegenseitiges TLS); Client-ID = Seriennummer = Zertifikat-CN.	Nichts gespeichert: „Der private Schlüssel verbleibt auf dem Gerät; nur der Zertifikat-Fingerprint wird gespeichert.“

Das Profil des Geräts muss den Typ erlauben (Erlaubte Authentifizierung auf dem Reiter Transport & Auth des Profils). Eine Anmeldung mit einem Typ, den das Profil nicht erlaubt, wird mit CONNACK 5 abgelehnt.

Regeln für MQTT-Basic

Element	Regel
Benutzername	1 bis 128 druckbare Zeichen ohne Leerzeichen. Auf der gesamten Plattform eindeutig. `provision` ist reserviert.
Client-ID (optional)	1 bis 64 Zeichen aus `A–Z a–z 0–9 . _ : -`. Wenn fixiert, muss das Gerät sie verwenden.
Generiertes Passwort	32 Zeichen. Lassen Sie das Passwort weg, um eines zu erhalten.
Gewähltes Passwort	Mindestens 16 Zeichen (Ihre Organisation kann mehr verlangen, bis zu 128: Mindestlänge eines gewählten MQTT-Passworts unter Geräte > ⋯ > Einstellungen), mindestens 8 verschiedene Zeichen, kein wiederholtes oder tastaturbasiertes Muster, kein gängiges Passwort (auch nicht mit angehängten Ziffern oder Symbolen) und kein Bestandteil des Benutzernamens oder der Client-ID.

Ein abgelehntes Passwort nennt den Grund (too_short, too_few_distinct, pattern, common, contains_identifier), niemals das Passwort selbst.

Regeln für X.509

Das Zertifikat muss von der Hermetry-Geräte-Zertifizierungsstelle ausgestellt, aktiv sein, zu Ihrer Organisation gehören und die Seriennummer des Geräts als CN tragen. Lizenzierte Geräte erhalten es, wenn Sie sie beanspruchen. Das Hochladen von Zertifikaten aus einer eigenen CA ist nicht verfügbar. Siehe Gerätezertifikate.

Wann ein Credential ausgestellt wird

Situation	Was das Gerät erhält
Neues Gerät mit eingeschaltetem Access-Token für neue Geräte ausstellen (Standard)	Ein Access-Token, im Drawer einmal angezeigt.
Neues Gerät mit ausgeschalteter Einstellung	Kein Credential. Über die API festlegen.
Massenimport	Ein Access-Token oder MQTT-Basic pro Zeile; die Passwörter und Tokens liegen in einer Credential-Datei, die Sie innerhalb von 15 Minuten einmal herunterladen können. Siehe Geräte im Massenimport importieren.
Selbstprovisionierung	Das Credential in der Provisionierungsantwort.
Beanspruchen eines lizenzierten Geräts	Sein X.509-Zertifikat.

Der Reiter Credentials

Öffnen Sie das Gerät und seinen Reiter Credentials. Er wird Administratoren für Geräte angezeigt, die sich selbst anmelden. Er listet Typ, Client-ID, Benutzername, Fingerprint (SHA-256), Subject und Läuft ab, sofern zutreffend, sowie wann das Credential Erstellt und zuletzt Rotiert wurde. Darunter zeigt die Karte Verbindungsdetails, wie sich das Gerät anmeldet, mit einem Platzhalter für das Geheimnis. Hat das Gerät kein Credential, heißt es im Reiter: „Das Gerät hat kein aktives Credential.“

Geheimnis rotieren

Wählen Sie Geheimnis rotieren.
Bestätigen Sie Geheimnis rotieren?: „Das alte Geheimnis funktioniert sofort nicht mehr, und das Gerät trennt die Verbindung, bis es aktualisiert wird.“
Das Neue Geheimnis erscheint einmal, mit Anzeigen, Verbergen und Kopieren, und die Verbindungszeilen sind damit ausgefüllt. Kopieren Sie, was Sie brauchen, und wählen Sie dann Ich habe es gespeichert.

Eine Rotation stellt ein neues Geheimnis desselben Typs aus: ein neues Token oder ein neues Passwort für denselben MQTT-Benutzernamen.

Ersetzen, wechseln oder widerrufen (API)

Der Reiter bietet die Rotation an. Das Ersetzen des Credentials durch einen anderen Typ und das Widerrufen erfolgen über die API mit derselben Berechtigung:

Aufruf	Wirkung
`GET /tenant/{tenantId}/api/iot/devices/{deviceId}/credentials`	Das aktive Credential: Typ und Kennungen, niemals ein Geheimnis. `null` nach dem Widerruf.
`POST …/credentials/rotate`	Ein neues Geheimnis desselben Typs, einmal zurückgegeben.
`PUT …/credentials`	Ersetzt das Credential durch das im Body. Ein generiertes Token oder Passwort wird einmal zurückgegeben (`secret`).
`DELETE …/credentials`	Widerruft das Credential. Das Gerät kann sich nicht mehr anmelden.

Body für PUT:

{"type": "ACCESS_TOKEN"}

{"type": "MQTT_BASIC", "username": "pump-07", "clientId": "pump-07", "password": null}

{"type": "X509_CERTIFICATE", "certificateId": "6f1c…"}

Ein password mit dem Wert null (oder weggelassen) erhält ein generiertes. Antworten tragen Cache-Control: no-store.

Was bei jeder Änderung passiert

Rotation, Ersetzen und Widerruf beenden das alte Credential sofort. Es gibt keine Übergangsfrist.
Jede offene Sitzung des Geräts endet sofort, auf jedem Broker-Knoten.
Die Änderung wird im Audit-Log und im Reiter Log des Geräts vermerkt (Credential rotiert, Credential ersetzt, Credential widerrufen).
Das Webhook-Ereignis device.credentials_rotated wird mit change gesendet: rotated, replaced, renewed oder revoked. Es enthält nur IDs und unbedenkliche Felder, niemals ein Credential.

Planen Sie Rotationen: Aktualisieren Sie das Gerät zuerst, wenn es ein neues Geheimnis aus der Ferne annehmen kann (etwa über einen Konfigurationskanal, den Sie kontrollieren), oder seien Sie bereit, es von Hand zu aktualisieren.

Bewährte Praktiken

Ein Credential pro Gerät. Kopieren Sie nie ein Token von einem Gerät auf ein anderes; die zweite Anmeldung übernimmt die Sitzung des ersten Geräts.
Bevorzugen Sie generierte Geheimnisse. Wählen Sie ein Passwort nur, wenn die Firmware ein festes tragen muss.
Rotieren Sie Geheimnisse, die in Tickets, Chats oder Skripte eingefügt wurden.
Widerrufen Sie das Credential eines Geräts, das Sie außer Betrieb nehmen, oder löschen Sie das Gerät.
Halten Sie Tokens aus URLs heraus. Verwenden Sie Token in der URL nur für Geräte, die keine Header senden können.
Achten Sie auf die Hinweise „neues Netzwerk“: Meldet sich ein Gerät aus einem unerwarteten Netzwerk an, kann ein Credential abgeflossen sein.