OAuth

smart-me unterstützt das Autorisierungsframework OAuth 2.0. Externe Anwendungen können den Zugriff auf ein Konto beantragen, ohne die Anmeldedaten zu kennen.

Detaillierte Informationen zu Rollen, Protokollfluss, Autorisierung, Endpunkten und Token finden Sie unter https://tools.ietf.org/html/rfc6749. Um die OAuth-Schnittstelle zu nutzen, sind eine Client-ID und ein Client-Secret erforderlich. Wenn Sie weder eine Client-ID noch ein Client-Secret haben, kontaktieren Sie uns bitte.

Berechtigungen

smart-me unterstützt zwei Arten von Berechtigungserteilungen:

  • Der implizite Berechtigungsfluss (empfohlen, wenn Sie eine Webapp oder Microapp erstellen)

  • Der Berechtigungscode-Fluss (empfohlen für langfristigen API-Zugang)

Implizite Berechtigung

Implizierte Berechtigungen sind zu verwenden, wenn der OAuth-Client in einem Browser mit einer Skriptsprache wie JavaScript implementiert wird. Wählen Sie dies, wenn Sie eine Webapp oder eine Microapp erstellen. Da ungültige oder abgelaufene Zugriffstoken nicht mit dem impliziten Gewährungstyp aktualisiert werden können, sollte dies nur für Widgets verwendet werden, die nur für eine begrenzte Zeit angezeigt werden, z. B. bei einmaliger Verwendung.

1. Autorisierung

Wenn der Benutzer die Anwendung eines Drittanbieters (z. B. ein Widget) verwenden möchte, muss er zunächst zum Autorisierungsendpunkt umgeleitet werden:

https://api.smart-me.com/api/oauth/authorize

client_id Wird von smart-me bereitgestellt. (Beispiel: myapp)

response_type Token

redirect_uri Die URL der App (z. B. https://www.example.com)

scope Gibt den Umfang des Zugriffs an (z. B. device.read)

state Wert, der vom Client verwendet wird, um den Zustand zwischen Request und Callback zu erhalten (z. B. ein URL-encodiertes JSON-Objekt)

Beispiel

https://api.smart-me.com/api/oauth/authorize?client_id=myapp&response_type=token&redirect_uri=https%3A%2F%2Fwww.example.com&scope=device.read&state=mystate

Wenn der Benutzer nicht bereits bei der App angemeldet ist, wird er zu einem Anmeldeformular weitergeleitet (Siehe rechts).

Nachdem der Benutzer authentifiziert wurde, fordert smart-me ihn auf, Ihrem Widget den Zugriff auf seine Daten zu gestatten. Der Nutzer kann Ihre App akzeptieren oder ablehnen und auch den Umfang des Datenzugriffs für Ihr Widget festlegen.


Wenn die Autorisierung erfolgreich war, wird der Benutzer zum redirect_uri mit dem Zugriffstoken als URI-Fragment umgeleitet: https://example.com#access_token=aaaaaa&expires_in=3600&token_type=bearer&state=mystate


2. API-Calls machen

Ihre App kann dann das access_token verwenden, um Calls an die API zu autorisieren, indem sie es als Autorisierungs-HTTP-Header sendet:

Authorization: Bearer <access_token>

Abgelaufenes Zugangs-Token:
Wenn das access_token abläuft, muss das gesamte Widget neu geladen werden, um den Autorisierungsfluss neu zu starten.

Berechtigungscode

Wird verwendet, wenn ein Server als OAuth2-Client fungiert und der Client einen langfristigen API-Zugang im Namen des Benutzers haben soll. Ungültige oder abgelaufene Zugangstokens können aktualisiert werden.

Ablauf

Sie müssen die folgenden fünf Schritte ausführen, um eine API request zu erstellen:

  1. Autorisierung anfordern

  2. smart-me leitet den Benutzer auf die Autorisierungsseite um

  3. Anforderung eines Zugangstokens

  4. Zugangstoken erhalten

  5. API-Calls machen

1. Autorisierung

Wenn der Benutzer die Anwendung eines Drittanbieters (d. h. eine benutzerdefinierte App) verwenden möchte, wird er zunächst an den Autorisierungsendpunkt weitergeleitet:

https://api.smart-me.com/api/oauth/authorize

client_id Wird von smart-me bereitgestellt (Beispiel: myapp)

response_type Code

redirect_uri Die URL der App (z. B. https://www.example.com)

scope Gibt den Umfang des Zugriffs an (z. B. device.read)

state Wert, der vom Client verwendet wird, um den Zustand zwischen Request und Callback zu erhalten (z. B. ein URL-encodiertes JSON-Objekt)

Beispiel:

https://api.smart-me.com/api/oauth/authorize?client_id=myapp&client_secret=mysecret&response_type=code&redirect_uri=https%3A%2F%2Fwww.example.com&scope=device.read&state=mystate

Nach der Authentifizierung des Benutzers fordert smart-me den Benutzer auf, Ihre App für den Zugriff auf seine Daten zu autorisieren.

Der Nutzer kann Ihre App annehmen oder ablehnen und auch den Umfang des Datenzugriffs für Ihre App festlegen.

2. Authentifizierungscode austauschen

Wenn die Autorisierung erfolgreich war, wird der Benutzer zur redirect_uri umgeleitet, wobei ein Autorisierungscode als Abfrageparameter angehängt wird:

https://www.example.com/?code=mycode&state=mystate

Ihre Anwendung muss den Auth-Code verwenden, um ein access_token anzufordern, indem sie eine POST-Anfrage an den Token-Endpunkt sendet:

https://api.smart-me.com/api/token/

client_id Wird von smart-me bereitgestellt (Beispiel: myapp)

client_secret Wird von smart-me bereitgestellt (Beispiel: mysecret)

response_type authorization_code

code Der Autorisierungscode (Beispiel: mycode)

redirect_uri Die URL der App (z. B. https://www.example.com)

POST https://api.smart-me.com/api/oauth/token client_id=myclient&client_secret=mysecret&grant_type=authorization_code&code=mycode&redirect_uri=https%3A%2F%2Fwww.example.com

Die Formulardatenfelder müssen als Inhaltstyp application/x-www-form-urlencoded kodiert sein.

Die Antwort enthält ein access_token und ein refresh_token. Das access_token kann dann für Api-Aufrufe im Namen des Benutzers verwendet werden, während das refresh_token zum Abrufen eines neuen access_token verwendet werden kann.

Antwort

{

"access_token": "mytoken",

"expires_in": 3600,

"token_type": "bearer",

"scope": "device.read",

"refresh_token": "myrefreshtoken"

}

3. API-Calls machen

Ihre App kann dann das access_token verwenden, um Aufrufe an die API zu autorisieren, indem sie es als Authorization HTTP-Header sendet:

Authorization: Bearer <access_token>

4. Abgelaufenes Zugangstoken auffrischen

Wenn das access_token abgelaufen ist (die Lebensdauer beträgt 3600 Sekunden) oder ungültig wird, müssen Sie das refresh_token verwenden, um ein neues access_token anzufordern, indem Sie eine POST-Anfrage an den Token-Endpunkt senden:

https://api.smart-me.com/api/token/

Die erforderlichen Formulardaten zur Aktualisierung des access_token:

client_id Wird von smart-me bereitgestellt (Beispiel: myapp)

client_secret Wird von smart-me bereitgestellt (Beispiel: mysecret)

response_type refresh_token

refresh_token Der refresh_token (Beispiel: myrefreshtoken)

POST https://api.smart-me.com/api/oauth/token client_id=myclient&client_secret=mysecret&grant_type=refresh_token&refresh_token=myrefreshtoken

Die Antwort enthält ein access_token und ein refresh_token. Das access_token kann dann für Api-Aufrufe im Namen des Benutzers verwendet werden, während das refresh_token zum Abrufen eines neuen access_token verwendet werden kann.

Antwort

{

"access_token": "mytoken",

"expires_in": 3600,

"token_type": "bearer",

"scope": "device.read",

"refresh_token": "myrefreshtoken"

}

Scopes

oauth_device_scopes