OAuth 2.0

Die seven.io API kann unter Verwendung des OAuth 2.0 Protokolls zur Authentifizierung und Autorisierung genutzt werden, um Nutzern Ihrer Software eine leichte und direkte Integration unseres Services zu ermöglichen.

Grundlagen

Durch OAuth 2.0 kann Ihre Applikation Zugriffsrechte auf Accounts von Kunden erlangen, um API Anfragen direkt in deren Namen an uns zusenden.

Hierzu müssen Sie vorab Ihre Applikation bei uns registrieren. Diese erhalten Sie derzeit nur von unserem Support. Bitte geben Sie Ihre Umleitungs URL (redirect_uri) an. Sie erhalten client_id und client_secret als Ihre Zugangsdaten zu unserer OAuth 2.0 API.

Alle Anwendungen laufen nun nach folgendem Muster beim Zugriff auf unsere API mit OAuth 2.0 ab:

  • Zunächst müssen Sie vom Kunden die Autorisierung einholen. Hierzu leiten Sie diesen auf eine spezielle Seite bei uns um, auf welcher der Kunde sich einloggen und Ihrer Anwendung den Zugriff gestatten muss.
  • Nach Bestätigung oder Ablehnung der Autorisierungsanfrage wird der Kunde wieder zu Ihrer Applikation zurückgeschickt. Sofern der Kunde die Genehmigung erteilt, erhält Ihre Applikation einen Autorisierungscode.
  • Mit diesem Autorisierungscode kann Ihre Anwendung über unsere OAuth 2.0 API das Zugriffstoken abrufen, mit welchem der direkte Zugriff auf unsere APIs möglich ist.

Zugriffstoken haben eine begrenzte Lebensdauer von standardmäßig einer Stunde. Wenn Ihre Anwendung über die Lebensdauer eines einzelnen Zugriffstokens hinaus Zugriff auf unsere APIs benötigt, kann diese mittels des Aktualisierungstokens neue Zugriffstoken abrufen.

Ablauf

  1. 1

    Applikation einrichten

    Sie erhalten von uns als Zugangsdaten zur OAuth 2.0 API folgende Zugangsdaten:

    • Name
      client_id
      Type
      string
      Description

      Ihre Zugangs-ID - in aller Regel setzen wir hier den Namen Ihrer App. Im Beispiel hier ist dieser testclient.

    • Name
      client_secret
      Type
      string
      Description

      Zugangspasswort zur OAuth2.0 API. Im Beispiel hier lautet dieses testsecret.

    Zusätzlich müssen Sie uns eine redirect_uri zur Verfügung stellen, auf welche wir nach Autorisierung weiterleiten. In unserem Beispiel hier lautet die URL https://acme.inc/oauth_redirect

  2. 2

    Kunde an OAuth 2.0 Autorisierungsseite weiterleiten

    Leiten Sie Ihre Kunden zu folgender URL weiter:

    https://oauth.seven.io/authorize?response_type=code&client_id=testclient&state=xyz&scope=sms%20analytics

    • Name
      state
      Type
      string
      Description

      Ein zufällig generierter String und zur Verhinderung von CSRF Angriffen. Bitte nutzen Sie hierzu einen kryptographisch sicheren String.

    • Name
      scope
      Type
      string
      Description

      Der angeforderte Geltungsbereich, auf welchen Sie Zugriff vom Kunden haben möchten – in diesem Fall der Versand von SMS und die Abfrage von Statistiken. Mehrere Geltungsbereiche können durch Leerzeichen getrennt übergeben werden.

  3. 3

    Kunde wird zu Ihrer Applikation zurückgeschickt

    Nachdem der Kunde die Autorisierung erteilt (oder verweigert) hat, leiten wir diesen automatisch zu Ihrer redirect_uri mit einigen zusätzlichen GET Parameter um.

    Im Erfolgsfall:

    https://acme.inc/oauth_redirect?code=9ccb478a7cbe043c1df211f1d52a6437f8756cf8&state=xyz

    Im Fehlerfall:

    https://acme.inc/oauth_redirect?error=access_denied&error_description=The+user+denied+access+to+your+application&state=xyz

    Sie sollten hier auf jeden Fall überprüfen, ob state den von Ihnen im zweiten Schritt erstellten Wert entspricht, um CSRF zu vermeiden.

  4. 4

    Zugriffstoken abfragen

    Rufen Sie über unsere OAuth 2.0 API den Zugriffstoken und den Refreshtoken ab.

POST/token

Zugriffstoken abrufen

Hat alles bis hierhin geklappt, können Sie nun mit dem GET Parameter code aus Schritt 3. ein Zugriffstoken wie folgt abrufen:

Anfrage

curl -u testclient:testsecret https://oauth.seven.io/token \
  -d 'grant_type=authorization_code&code=9ccb478a7cbe043c1df211f1d52a6437f8756cf8'

Sie erhalten im im Erfolgsfall Daten im JSON-Format wie folgt zurück:

Antwort

{
  "access_token":"b1a9391d0469cafe30258893ab6025d4ad94ecec",
  "expires_in":3600,
  "token_type":"Bearer",
  "scope":"sms",
  "refresh_token":"ffd8e622aa5dccc2905f2ac6a0999c785a803157"
}
POST/token

Zugriffstoken aktualisieren

Um den Zugriffstoken zu aktualisieren, rufen Sie die OAuth 2.0 API wie folgt auf:

Anfrage

curl -u testclient:testsecret https://oauth.seven.io/token \
  -d 'grant_type=refresh_token&refresh_token=ffd8e622aa5dccc2905f2ac6a0999c785a803157'

Sie erhalten im im Erfolgsfall Daten neue Token im JSON-Format wie folgt zurück:

Antwort

{
  "access_token":"worw5xlrl0sjwqkvmstibwn4pw0mdvpddljzkfi8",
  "expires_in":3600,
  "token_type":"Bearer",
  "scope":"sms",
  "refresh_token":"n94c2kyej8ycsjutmviuk8i6zebgsda0uzg2gbpn"
}

Zugriff auf unsere APIs

Rufen Sie unsere APIs entsprechend der jeweiligen Dokumentation auf und senden Sie den Zugriffstoken im Authorization Header ohne weitere Kodierung (kein base64 o.ä.).

curl https://gateway.seven.io/api/sms -H 'Authorization: Bearer ACCESS_TOKEN'

Weiterhin können Sie die Erfolgreiche Anbindung per OAuth 2.0 über folgenden Aufruf testen:

Anfrage

curl https://oauth.seven.io/me -H 'Authorization: Bearer ACCESS_TOKEN'

Antwort

{
    "success": true,
    "user_id": 12345,
    "email": "john.doe@acme.inc",
    "company": "Acme Inc.",
    "alias": "acme_inc",
    "balance": "627.3615"
}

Geltungsbereiche

Die folgenden Geltungsbereiche können Sie vom Kunden anfordern lassen:

GeltungsbereichBedeutung
analyticsAbfrage von Statistiken
balanceGuthaben abfragen
contactsKontakte abfragen und bearbeiten
hooksErlaubt das Ändern und Einsehen von Webhooks
journalIhr Logbuch abfragen
lookupAnfragen per Lookup (HLR, MNP etc.) durchführen
pricingPreise des Accounts abfragen
smsVersand von SMS Nachrichten
statusStatusbericht von SMS abfragen
subaccountsSubaccounts bearbeiten und einsehen
validate_for_voiceRufnummern als Absender für Voice verifizieren
voiceVoice Nachrichten versenden

Mehrere Geltungsbereiche können dabei durch ein urlkodiertes Leerzeichen angegeben werden. Sofern der Geltungsbereich nicht angegeben wird bzw. leer ist, wird der Standardgeltungsbereich angewendet.

PHP Code Beispiel

Hier ein einfach gehaltenes Beispiel in PHP. Im ersten Code wird die OAuth URL generiert und der Kunde an diese weitergeleitet:

Kunden zur OAuth2.0 Seite weiterleiten

<?php

// Application credentials
$client_id = 'testclient';
$client_secret = 'testsecret';

session_start();

// Request authorization for sms, analytics and lookup endpoints. // Leave empty to allow all scopes
$requested_scopes = [
  'sms',
  'analytics',
  'lookup'
];

// Generate random string for state
$state = bin2hex(openssl_random_pseudo_bytes(10));

// Store state in session
$_SESSION['state'] = $state;

// Build authorization URI
$auth_uri = 'https://oauth.seven.io/authorize?' .
  http_build_query([
    'response_type' => 'code',
    'client_id' => $client_id,
    'state' => $state,
    'scope' => implode(' ', $requested_scopes),
  ]);

// Redirect User to OAuth authorization site
header('Location: ' . $auth_uri);

Beim zweiten Code handelt es sich um die Seite, die unter Ihrer redirect_uri läuft. Hier wird die Autorisierung überprüft und die Tokens werden abgerufen:

Überprüfung der Autorisierung und Abruf von Tokens

<?php

// Application credentials $client_id = 'testclient'; 
$client_secret = 'testsecret'; 

session_start(); 

// CSRF check failed
if($_GET['state'] != $_SESSION['state']) {
  die('CSRF check failed');
}

// An error occured during authorization
elseif(isset($_GET['error'])) {
  die('Error: ' . $_GET['error']);
}

// We got a code, send it to OAuth 2.0 API to get the tokens...
elseif(isset($_GET['code'])) {
  $post_vars = http_build_query([
    'grant_type' => 'authorization_code',
    'code' => $_GET['code'],
  ]);

  $ch = curl_init();
  curl_setopt($ch, CURLOPT_USERPWD, $client_id . ":" . $client_secret);

  curl_setopt($ch, CURLOPT_URL, 'https://oauth.seven.io/token');
  curl_setopt($ch, CURLOPT_POST, 1);
  curl_setopt($ch, CURLOPT_POSTFIELDS, $post_vars);
  curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);

  $response = curl_exec($ch);

  curl_close ($ch);

  $token = json_decode($response);

  // You should store the tokens here in order to make API calls
  die("Access Token: " . $token->access_token);
}