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. Das erledigen Sie selbst im Dashboard unter Entwickler > OAuth-Apps. Dort hinterlegen Sie Name, Umleitungs-URL (redirect_uri) und die gewünschten Geltungsbereiche und erhalten client_id und client_secret als Ihre Zugangsdaten zu unserer OAuth 2.0 API.

Das client_secret wird Ihnen nur einmal direkt nach dem Anlegen angezeigt und bei uns ausschließlich als Hash gespeichert. Bewahren Sie es sicher auf. Geht es verloren, können Sie im Dashboard ein neues erzeugen – das alte wird dabei ungültig.

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

Zugriffstoken abrufen

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

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

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

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

Zugriffstoken aktualisieren

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

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

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

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

Token widerrufen

Um ein Zugriffstoken oder Aktualisierungstoken zu widerrufen, rufen Sie die OAuth 2.0 API wie folgt auf:

curl -u testclient:testsecret https://oauth.seven.io/revoke \
  -d "token=b1a9391d0469cafe30258893ab6025d4ad94ecec"

Sie erhalten im Erfolgsfall eine Antwort im JSON-Format wie folgt:

{
  "revoked": true
}

Im Fehlerfall antwortet der Server mit HTTP-Statuscode 400:

{
  "error": "invalid_client",
  "error_description": "The client credentials are invalid"
}

Hinweis: Aus Sicherheitsgründen antwortet der Server auch mit 200 OK, wenn das Token bereits ungültig war oder einem anderen Client gehört.

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:

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

{
    "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:

Mehrere Geltungsbereiche können dabei durch ein URL-kodiertes Leerzeichen angegeben werden. Sofern der Geltungsbereich nicht angegeben wird bzw. leer ist, gelten die Geltungsbereiche, die Sie beim Anlegen der App hinterlegt haben. Sie können beim Autorisierungsaufruf nur Geltungsbereiche anfordern, die für Ihre App hinterlegt sind – alles andere wird mit invalid_scope abgelehnt.

Geprüfte und ungeprüfte Apps

Selbst angelegte Apps sind zunächst ungeprüft. Sie sind sofort voll funktionsfähig, unterliegen aber zwei Einschränkungen:

• Fremde Konten sehen auf der Autorisierungsseite einen Hinweis, dass die App nicht von seven geprüft wurde.
• Die App kann sich mit maximal 25 fremden Konten verbinden. Ist das Limit erreicht, schlägt die Autorisierung weiterer Konten fehl. Ihr eigenes Konto und Ihre Subaccounts zählen nicht mit, Sie können also uneingeschränkt selbst testen.

Zusätzlich kann jedes Konto höchstens 10 ungeprüfte Apps besitzen. Geprüfte Apps zählen nicht mit.

Sobald Ihre App produktiv mit fremden Konten arbeiten soll, fordern Sie im Dashboard eine Prüfung an. Voraussetzung ist eine hinterlegte Website. Wir sehen uns Name, Logo, Website und die angeforderten Geltungsbereiche an und entfernen nach erfolgreicher Prüfung sowohl den Hinweis als auch das Limit.

PHP Code Beispiel

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

<?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:

<?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);
}