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
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
Kunde an OAuth 2.0 Autorisierungsseite weiterleiten
Leiten Sie Ihre Kunden zu folgender URL weiter:
- 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
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:
Sie sollten hier auf jeden Fall überprüfen, ob
state
den von Ihnen im zweiten Schritt erstellten Wert entspricht, um CSRF zu vermeiden. - 4
Zugriffstoken abfragen
Rufen Sie über unsere OAuth 2.0 API den Zugriffstoken und den Refreshtoken ab.
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"
}
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:
Geltungsbereich | Bedeutung |
---|---|
analytics | Abfrage von Statistiken |
balance | Guthaben abfragen |
contacts | Kontakte abfragen und bearbeiten |
hooks | Erlaubt das Ändern und Einsehen von Webhooks |
journal | Ihr Logbuch abfragen |
lookup | Anfragen per Lookup (HLR, MNP etc.) durchführen |
pricing | Preise des Accounts abfragen |
sms | Versand von SMS Nachrichten |
status | Statusbericht von SMS abfragen |
subaccounts | Subaccounts bearbeiten und einsehen |
validate_for_voice | Rufnummern als Absender für Voice verifizieren |
voice | Voice 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);
}