Podpora Azure IoT Client SDK pro servery tokenů třetích stran

Přístup k řízení IoT Hub ukazuje, jak může být služba tokenů třetí strany integrovaná s IoT Hub. Tento článek popisuje podporu ověřování tokenu sdíleného přístupového podpisu (SAS) v každé klientské sady SDK Azure IoT. Obsahuje také informace o tom, co je třeba implementovat v aplikaci zařízení pomocí příslušné sady SDK pro jednotlivé jazyky, a jak používat tokeny v oboru zařízení nebo moduly v rámci zásad sdíleného přístupu DeviceConnect nebo ModuleConnect.

Kontext a problém

Aktuální dokumentace ke službě Azure IoT Hub Security popisuje vzor tokenu a serveru třetí strany pro ověřování SAS pomocí IoT Hub zařízeními IoT pomocí sad SDK klienta Azure IoT. Nesprávné předpoklady, které zákazník vytvořil během poslední podnikové zapojení, ale naznačují, že bez dalšího objasnění můžete vyvíjet zavádějící dojem o úrovni podpory, která je ve výchozím nastavení implementovaná v sadách SDK klienta Azure IoT.

Tento článek popisuje učení z této zapojení a vysvětluje, co je potřeba udělat v každé sadě SDK pro zařízení, aby se zajistilo ověřování pomocí tokenu serveru třetí strany. Tento článek by taky měl bránit v vytváření podobných nesprávných předpokladů o podpoře vzorového serveru tokenu třetí strany v sadě SDK Azure IoT Client.

Řešení

Sady SDK klienta Azure IoT poskytují různé úrovně podpory pro ověřování tokenů SAS. Každá z nich vyžaduje pro dokončení funkce ověřování a správy tokenů nějaký vlastní kód.

Frekvence hodnocení tokenů závisí na zvoleném transportním protokolu – MQTT, AMQP nebo HTTPS. Variace závisí na schopnosti protokolu pro podporu proaktivní obnovy tokenů a časových limitů relací. Pouze AMQP implementuje podporu proaktivní obnovy. To znamená, že ostatní přenosy zavřou připojení k chybě ověřování tokenu SAS a pak bude potřeba provést novou operaci připojení. Toto je potenciálně náročná operace připojení pro klienta.

Pokud se ověřování SAS nepovede, vyvolá se chyba v rámci přenosové implementace, kterou je možné zpracovat v aplikaci zařízení pomocí obslužné rutiny události "stav připojení". Při implementaci takové obslužné rutiny se obvykle zobrazí, že se aplikace zařízení zastaví z důvodu chyby. V případě správné implementace obslužné rutiny události a funkce obnovení tokenu se přenos může znovu pokusit o připojení.

Následující obrázek znázorňuje vzor tokenu a serveru třetí strany:

Následující obrázek znázorňuje podporu implementace v sadě SDK klienta Azure IoT s integrací mobilního operátoru NET:

Ukázkové implementace jsou součástí úložiště ukázek Azure na GitHub.

Problémy a důležité informace

Při rozhodování, zda tento model implementovat, vezměte v úvahu následující body:

• Sady SDK klienta azure IoT Hub Device Provisioning Service (Azure DPS) nepodporují ověřování tokenů SAS. Azure DPS REST API podporuje ověřování tokenů SAS. Proto pokud chcete použít Azure DPS s tokenovou službou třetí strany pro ověřování SAS, musí aplikace zařízení implementovat proces DPS v zařízení pomocí REST API Azure DPS.

• To se skládá z operace prvotní žádosti o registraci a následně s dotazem na rozhraní API provozního stavu, dokud se proces DPS nepodaří nebo selže. Po úspěšném dokončení můžete získat podrobnosti o zřizování zařízení, a to vyžádáním z registrace Azure DPS REST API runtime.

Odkazy

• Rozhraní API pro žádost o počáteční registraci

• Rozhraní API operací cyklického dotazování

• Požádat o rozhraní API s podrobnostmi o zřízeném zařízení

Kdy se má tento model použít

Tento model byste měli použít, kdykoli budete chtít provést ověření v Azure IoT Hub ze zařízení IoT pomocí různých sad SDK pro Azure IoT. Místo použití klientských sad SDK pro ověřování tokenů SAS použijte REST API Azure DPS, abyste zajistili podporu proaktivní obnovy pro všechny mechanismy přenosu.

Příklady

Následující části obsahují příklady, které můžete použít pro různé programovací jazyky, jako jsou například Embedded C, .NET, Java a Python.

Sada SDK pro zařízení Azure IoT Hub pro jazyk C a Azure IoT Hub SDK pro Embedded C

Následující přístup se dá využít v aplikacích zařízení vytvořených pomocí sady Azure IoT C SDK nebo sady Azure IoT Embedded C SDK. Žádná sada SDK neposkytuje správu životnosti tokenů SAS, proto budete muset implementovat schopnost správce životnosti tokenů SAS.

Tokeny SAS lze použít prostřednictvím struktury _ _ Konfigurace klienta IOTHUB nastavením člena DeviceSasToken na token a nastavením deviceKey na hodnotu null. Jiné nepoužívané hodnoty, například protocolGatewayHostName, musí být také nastavené na hodnotu null.

CONFIG = (IOTHUB\_CLIENT\_CONFIG\*)MALLOC(SIZEOF (IOTHUB\_CLIENT\_CONFIG));

CONFIG-\>PROTOCOL = PROTOCOL;

CONFIG-\>DEVICEID = DEVICEID;

CONFIG-\>IOTHUBNAME = IOTHUBNAME;

CONFIG-\>IOTHUBSUFFIX = IOTHUBSUFFIX;

CONFIG-\>DEVICEKEY = 0;

CONFIG-\>DEVICESASTOKEN = TOKEN;

CONFIG-\>PROTOCOLGATEWAYHOSTNAME = 0;

Vytvořenou _ konfiguraci klienta IOTHUB je _ pak možné poskytnout _ funkci IoTHubDeviceClient Create k vytvoření instance DeviceClient.

IF ((IOTHUBCLIENTHANDLE = IOTHUBDEVICECLIENT\_CREATE(CONFIG)) == NULL)

{

(VOID)PRINTF("ERROR: IOTHUBCLIENTHANDLE IS NULL!\\R\\N");

}

Pro zachycení selhání ověřování pomocí tokenu SAS je nutné implementovat obslužnou rutinu pro IoTHubDeviceClient _ SetConnectionStatusCallback.

(VOID)IOTHUBDEVICECLIENT\_SETCONNECTIONSTATUSCALLBACK(IOTHUBCLIENTHANDLE,
CONNECTION\_STATUS\_CALLBACK, NULL);

_ _ Zpětné volání stavu připojení může zachytit _ _ Důvod stavu připojení klienta _ IOTHUB _ _ _ _ token SAS, který vypršel, _ _ aby aktivoval obnovení tokenu SAS prostřednictvím služby tokenu třetí strany. To je nutné pro všechny přenosy, které zachytí problémy s připojením, ale jsou výslovně vyžadovány přenosy, které nepodporují proaktivní obnovení tokenu SAS. Proaktivní Správa životnosti tokenů SAS se dá implementovat jako funkce opakovaně spouštěné během úvodní smyčky aplikací zařízení. Zajištění, že se životnost tokenu často vyhodnocuje, a obnovení tokenu se dá v případě potřeby aktivně spustit.

Souhrn implementace ověřování tokenů SAS pro sady C SDK:

1. Implementujte obslužnou rutinu ConnectionStatusCallback pro _ zachycení _ _ události tokenu SAS vypršení platnosti připojení klientů IOTHUB _ _ a obnovení aktivačního tokenu.

2. Pomocí _ Konfigurace klienta IOTHUB _ Zadejte token SAS zařízení, který IoTHubDeviceClient _ vytvořit.

3. Implementujte proaktivní správu životnosti tokenů SAS jako součást smyčky operací aplikace zařízení.

Odkazy

• _Reference k vytvoření IoTHubDeviceClient ()

• Reference k IoTHubDeviceClient _ SetConnectionStatusCallback ()

Sada SDK pro zařízení Azure IoT Hub pro .NET

Sada SDK klienta Azure IoT pro .NET implementuje podporu správy životnosti tokenů SAS prostřednictvím abstraktní třídy DeviceAuthenticationWithTokenRefresh. Konkrétní implementace této třídy, přidání funkce pro obnovení tokenu, může být poskytnuta jako metoda ověřování pro metodu DeviceClient. Create. Implementace přenosu v případě potřeby automaticky obnoví token prostřednictvím metody ověřování. K zachycení změn připojení a zabránění vygenerování výjimek z přenosů se vyžaduje ConnectionStatusChangesHandler.

Příklad implementace na základě třídy DeviceAuthenticationWithTokenRefreash

INTERNAL CLASS STSDEVICEAUTHENTICATIONWITHTOKENREFRESH :
DEVICEAUTHENTICATIONWITHTOKENREFRESH

{

PRIVATE READONLY STRING \_STSCONNECTURL =
"HTTP://LOCALHOST:8080/STS/AZURE/TOKEN/OPERATIONS?SR={0}/DEVICES/{1}";

PRIVATE CONST INT DEFAULTTIMETOLIVESECONDS = 1 \* 60 \* 60;

PRIVATE CONST INT DEFAULTBUFFERPERCENTAGE = 15;

PUBLIC STSDEVICEAUTHENTICATIONWITHTOKENREFRESH(STRING DEVICEID, INT
SUGGESTEDTIMETOLIVESECONDS, INT TIMEBUFFERPERCENTAGE) : BASE(DEVICEID,
SUGGESTEDTIMETOLIVESECONDS, TIMEBUFFERPERCENTAGE)

{

IF (STRING.ISNULLORWHITESPACE(DEVICEID))

{

THROW NEW ARGUMENTNULLEXCEPTION(NAMEOF(DEVICEID));

}

}

PROTECTED OVERRIDE TASK\<STRING\> SAFECREATENEWTOKEN(STRING IOTHUB, INT
SUGGESTEDTIMETOLIVE)

{

STRING RESULT;

STRING URL = STRING.FORMAT(\_STSCONNECTURL, IOTHUB, DEVICEID);

HTTPCLIENTHANDLER HANDLER = NEW HTTPCLIENTHANDLER();

HTTPCLIENT = NEW HTTPCLIENT(HANDLER);

TRY

{

VAR APIRESPONSE = HTTPCLIENT.GETASYNC(URL).RESULT;

IF (APIRESPONSE.ISSUCCESSSTATUSCODE)

{

RESULT = APIRESPONSE.CONTENT.READASSTRINGASYNC().RESULT;

}

ELSE

{

THROW NEW HTTPREQUESTEXCEPTION();

}

}

CATCH (HTTPREQUESTEXCEPTION)

{

RESULT = NULL;

}

RETURN TASK.FROMRESULT(RESULT);

}

}

Shrnutí implementace ověřování tokenů SAS pro sadu Azure IoT Hub SDK pro zařízení pro .NET:

1. Implementujte konkrétní třídu na základě abstraktní třídy DeviceAuthenticationWithTokenRefresh, která implementuje funkce obnovení tokenu.

2. Implementujte ConnectionStatusChangesHandler a zachyťte stav připojení přenosu a vyhněte se výjimkám vyvolaným implementací přenosu.

Odkazy

• DeviceAuthenticationWithTokenRefresh – třída

• DeviceClient. Create – metoda

Sada SDK pro Azure IoT Hub zařízení pro Java

Sada SDK klienta Azure IoT pro jazyk Java implementuje podporu správy životnosti tokenů SAS prostřednictvím rozhraní SasTokenProvider. Třída, která implementuje toto rozhraní s funkcí obnovení tokenu SAS, se dá použít jako SecurityProvider v konstruktoru DeviceClient. Implementace přenosu automaticky obnoví token přes poskytovatele zabezpečení podle potřeby. Aby bylo možné zachytit změny připojení a zabránit tomu, aby byly výjimky vyvolány v rámci přenosů, musí být ConnectionStatusChangeCallback zaregistrovaný.

Příklad implementace zprostředkovatele zabezpečení implementující rozhraní SasTokenProvider:

IMPORT JAVA.IO.IOEXCEPTION;

IMPORT JAVA.NET.URI;

IMPORT JAVA.NET.HTTP.HTTPCLIENT;

IMPORT JAVA.NET.HTTP.HTTPREQUEST;

IMPORT JAVA.NET.HTTP.HTTPRESPONSE;

IMPORT JAVA.TIME.DURATION;

PUBLIC CLASS STSSECURITYPROVIDER IMPLEMENTS SASTOKENPROVIDER {

PRIVATE FINAL STRING HOSTNAME;

PRIVATE FINAL STRING DEVICEID;

PRIVATE INT RENEWALBUFFERSECONDS;

PRIVATE LONG EXPIRYTIMESECONDS;

PRIVATE CHAR[] SASTOKEN;

PUBLIC STSSECURITYPROVIDER(STRING HOSTNAME, STRING DEVICEID)

{

THIS.HOSTNAME = HOSTNAME;

THIS.DEVICEID = DEVICEID;

THIS.RENEWALBUFFERSECONDS = 120;

THIS.EXPIRYTIMESECONDS = (SYSTEM.CURRENTTIMEMILLIS() / 1000);

}

\@OVERRIDE

PUBLIC CHAR[] GETSASTOKEN() {

LONG CURRENTTIMESECONDS = (SYSTEM.CURRENTTIMEMILLIS() / 1000);

TRY {

IF (THIS.SASTOKEN == NULL \|\| THIS.EXPIRYTIMESECONDS +
THIS.RENEWALBUFFERSECONDS \>= CURRENTTIMESECONDS) {

THIS.SASTOKEN = STSGETTOKEN();

ASSERT THIS.SASTOKEN != NULL;

STRING T = STRING.COPYVALUEOF(THIS.SASTOKEN);

STRING[] BITS = T.SPLIT("SE=");

LONG L = LONG.PARSELONG(BITS[1]);

THIS.EXPIRYTIMESECONDS = L; // THE SE= NUMBER

THIS.RENEWALBUFFERSECONDS = (INT) (L \* 0.15); // RENEW WITHIN 15% OF EXPIRY

}

} CATCH (INTERRUPTEDEXCEPTION \| IOEXCEPTION E) {

E.PRINTSTACKTRACE();

}

RETURN THIS.SASTOKEN;

}

PRIVATE CHAR[] STSGETTOKEN() THROWS IOEXCEPTION, INTERRUPTEDEXCEPTION {

STRING STSURL =
STRING.FORMAT("HTTP://LOCALHOST:8080/STS/AZURE/TOKEN/OPERATIONS?SR=%S/DEVICES/%S",
THIS.HOSTNAME, THIS.DEVICEID);

HTTPREQUEST REQUEST = HTTPREQUEST.NEWBUILDER()

.URI(URI.CREATE(STSURL))

.TIMEOUT(DURATION.OFMINUTES(2))

.HEADER("CONTENT-TYPE", "APPLICATION/JSON")

.BUILD();

HTTPCLIENT CLIENT = HTTPCLIENT.NEWBUILDER()

.VERSION(HTTPCLIENT.VERSION.HTTP\_1\_1)

.CONNECTTIMEOUT(DURATION.OFSECONDS(20))

.BUILD();

HTTPRESPONSE\<STRING\> RESPONSE = CLIENT.SEND(REQUEST,
HTTPRESPONSE.BODYHANDLERS.OFSTRING());

IF(RESPONSE.STATUSCODE() \<200 \|\| RESPONSE.STATUSCODE()\>=300) {

RETURN NULL;

}

IF(RESPONSE.BODY().ISEMPTY()) {

RETURN NULL;

}

RETURN RESPONSE.BODY().TOCHARARRAY();

}

}

Shrnutí implementace ověřování tokenů SAS pro sadu Azure IoT Hub Device SDK pro jazyk Java:

1. Implementujte rozhraní SasTokenProvider pro třídu a zahrňte funkci obnovení tokenu.

2. Implementujte obslužnou rutinu ConnectionStatusChangeCallback pro zachycení změn stavu připojení přenosu a vyhněte se výjimkám vyvolaným implementací přenosu.

Odkazy

• Rozhraní SasTokenProvider

• DeviceClient. registerConnectionStateCallback (IotHubConnectionStateCallback callback, Object callbackContext) – metoda

• Ukázka vlastního zprostředkovatele tokenů SAS – Ukázka sady SDK

Sada SDK pro zařízení Azure IoT Hub pro Python

Sada SDK pro zařízení Azure IoT Hub pro Python implementuje podporu tokenů SAS prostřednictvím metod v objektu IoTHubDeviceClient. Tyto metody umožňují vytvoření klienta zařízení pomocí tokenu a možnost poskytnutí aktualizovaného tokenu po vytvoření klienta zařízení. Neimplementují správu životností tokenů, ale lze je implementovat snadno jako asynchronní operace.

Ukázková implementace Python 3,7 zobrazující jenom osnovu funkcí:

ASYNC DEF MAIN():

\# GET A SASTOKEN YOU GENERATED

SASTOKEN = GET\_NEW\_SASTOKEN()

\# THE CLIENT OBJECT IS USED TO INTERACT WITH YOUR AZURE IOT HUB.

DEVICE\_CLIENT = IOTHUBDEVICECLIENT.CREATE\_FROM\_SASTOKEN(SASTOKEN)

\# CONNECT THE CLIENT.

AWAIT DEVICE\_CLIENT.CONNECT()

\# DEFINE BEHAVIOR FOR PROVIDING NEW SASTOKENS TO PREVENT EXPIRY

ASYNC DEF SASTOKEN\_KEEPALIVE():

WHILE TRUE:

AWAIT ASYNCIO.SLEEP(NEW\_TOKEN\_INTERVAL)

SASTOKEN = GET\_NEW\_SASTOKEN()

AWAIT DEVICE\_CLIENT.UPDATE\_SASTOKEN(SASTOKEN)

\# ALSO RUN THE SASTOKEN KEEPALIVE IN THE EVENT LOOP

KEEPALIVE\_TASK = ASYNCIO.CREATE\_TASK(SASTOKEN\_KEEPALIVE())

\# CANCEL THE SASTOKEN UPDATE TASK

KEEPALIVE\_TASK.CANCEL()

\# FINALLY, SHUT DOWN THE CLIENT

AWAIT DEVICE\_CLIENT.SHUTDOWN()

IF \_\_NAME\_\_ == "\_\_MAIN\_\_":

ASYNCIO.RUN(MAIN())

Shrnutí sady Azure IoT Hub Device SDK pro ověřování tokenů SAS Pythonu:

1. Vytvoří funkci generování tokenů SAS.

2. Vytvořte klienta zařízení pomocí IoTHubDeviceClient. Create _ z _ sastoken.

3. Správa životnosti tokenů jako samostatné aktivity a zadání klienta zařízení s obnoveným tokenem, pokud to vyžaduje metoda IoTHubDeviceClient. Update _ sastoken.

Odkazy

• IoTHubDeviceClient

Sada SDK pro zařízení Azure IoT Hub pro Node.JS/JavaScript

Azure IoT for Node.JS/JavaScript implementuje SharedAccessSignatureAuthenticationProvider, který bude zajišťovat token SAS pro klienta zařízení a přenos pro ověřování pomocí IoT Hub. Neimplementuje žádné funkce pro obnovení tokenu. Aplikace zařízení musí spravovat životnost tokenů a obnovovat token podle potřeby.

Pomocí metod klienta zařízení fromSharedAccessSignature a updateSharedAccessSignature navázat spojení s IoT Hub a dodejte k SharedAccessSignatuteAuthenticationProvider obnovený token, který způsobí, že zprostředkovatel ověřování vygeneruje událost newTokenAvailable pro přenos.

Základní ukázka tokenu SAS je k dispozici v jednoduchém _ ukázkovém _ zařízení _ s _sas.jsm příkladem.

Shrnutí sady SDK pro zařízení Azure IoT Hub pro Node.JS/JavaScript

1. Implementujte správu životnosti tokenů SAS a obnovování.

2. K vytvoření instance klienta zařízení použijte fromSharedAccessSignature klienta zařízení.

3. K poskytnutí obnoveného tokenu použijte updateSharedAccessSignature klienta zařízení.

Odkazy

• Třída klienta

Další kroky

• Řízení přístupu IoT Hub pomocí sdílených přístupových podpisů a tokenů zabezpečení

• Komunikace se službou IoT Hub pomocí protokolu MQTT

• Komunikace se službou IoT Hub pomocí protokolu AMQP

• Sady SDK pro Azure IoT Hub

Související prostředky

• Příručka pro vývojáře Azure IoT Hub

• Volba řešení Internet věcí (IoT) v Azure

• Začínáme s řešeními Azure IoT