Authentifizierung bei den Vonage Business Communications APIs

Sobald Sie Ihre Bewerbung erstelltund die Provisioning API abonniert hat sind Sie bereit, ein Zugriffstoken zu erstellen. Vonage Business Communications APIs verwenden OAuth zur Authentifizierung.

Erstellen von Authentifizierungsschlüsseln

Melden Sie sich bei der Entwicklerportal für Unternehmenskommunikation mit Ihren Entwickleranmeldedaten.
Wählen Sie Applications im oberen Navigationsmenü.
Auf der Applikation Seite, suchen Sie Ihre Anwendung in der Tabelle und klicken Sie auf die Anwendung Name Link.
Wählen Sie die Schlüssel für die Produktion im linken Navigationsmenü:

Hinweis: Die Standardförderungsart ist Password. Die Zuschussart ist die Methode, die OAuth verwendet, um ein Zugriffstoken zu erzeugen. Wenn Sie eine Produktionsanwendung erstellen, werden Sie in der Regel die Methode Code Methode zur Authentifizierung von Anfragen. Die Refresh Token wird ein neues Token erstellt, wenn das aktuelle abläuft.
Wenn Code ausgewählt, in der Rückruf-URL geben Sie eine gültige Rückruf-URL ein, über die Ihre Anwendung den generierten Code erhalten soll. Wenn Sie Ihre Anwendung noch nicht erstellt haben, geben Sie http://localhost und denken Sie daran, die richtige URL einzugeben, wenn Sie bereit sind, sie zu testen.

Hinweis: Wenn Sie für Ihre Anwendung den Typ "Password Grant" verwenden möchten, brauchen Sie keine Callback-URL zu verwenden, um das Token abzurufen, wie Sie es bei der Verwendung des Autorisierungscode-Flows tun würden. Bei der Verwendung von Password Grant können Sie die URL leer lassen.
Klicken Sie auf die Schlüssel generieren Schaltfläche. Dadurch wird die Verbraucherschlüssel und Verbrauchergeheimnis die Ihre Anwendung zum Anfordern eines Tokens verwenden wird.

Unterstützte Zuschussarten

Vonage Business Communications unterstützt die folgenden Gewährungstypen für die Erstellung von Zugriffstoken.

Berechtigungscode - Der Grant-Typ Autorisierungscode wird von vertraulichen und öffentlichen Clients verwendet, um einen Autorisierungscode gegen ein Zugriffstoken auszutauschen. Nachdem der Benutzer über die Umleitungs-URL zum Client zurückgekehrt ist, erhält die Anwendung den Autorisierungscode von der URL und verwendet ihn, um ein Zugriffstoken anzufordern.
Passwort Gewährung - Der Gewährungstyp Passwort ist eine Möglichkeit, die Anmeldedaten eines Benutzers gegen ein Zugriffstoken auszutauschen.

Wann sollte man die Kennwortgewährungsart verwenden?

Der Grant-Typ Passwort erfordert, dass die Anwendung das Passwort des Benutzers erfasst. Es wird empfohlen, den Grant-Typ Passwort nur für Server-zu-Server-Applikationen zu verwenden, bei denen die Erfassung von Benutzerdaten nicht erforderlich ist.

Sehen Sie sich die Beispiele für Endpunkte und Erzeugen von Zugangstokens Proben, um zu erfahren, wie man den Authentifizierungscode anfordert und ihn gegen ein Zugangs-Token austauscht:

In der Produktion sollten Sie die autorisierungs_code Bewilligungsart (Code) und dies ist die einzige Option, die auf der Registerkarte Meine Applications unter apimanager.uc.vonage.com. Die Code Grant-Typ erfordert, dass Ihre Anwendung eine gültige Callback-URL implementiert, um den Autorisierungscode von den Vonage-Servern abzurufen und ihn gegen ein Token auszutauschen. In den Endpunktbeispielen auf der Registerkarte Meine Applications erfahren Sie, wie Sie die Autorisierungs- und Token-Anforderungen erstellen.

Authentifizierung mit Autorisierungscode Gewährung

Warnung: SSO wird zur Zeit nicht unterstützt

Das folgende Beispiel zeigt, wie man einen authorization_code über den authorize-Endpunkt erhält.

https://api.vonage.com/authorize?scope=openid&response_type=code&redirect_uri=$REDIRECT_URI&client_id=$CONSUMER_KEY

REDIRECT_URI - Die URL, an die der Benutzer nach der Authentifizierung weitergeleitet wird.
CONSUMER_KEY - Der Verbraucherschlüssel, den Sie in Schritt 5 oben erzeugt haben

Das folgende Beispiel zeigt, wie ein Autorisierungscode über den Token-Endpunkt gegen ein Token ausgetauscht werden kann

curl --request POST 'https://api.vonage.com/token' \ --header 'Content-Type: application/x-www-form-urlencoded' \ --header 'Authorization: Basic $AUTHORIZATION' \ --data-urlencode 'grant_type=authorization_code' \ --data-urlencode 'code=$AUTHORIZATION_CODE' \ --data-urlencode 'redirect_uri=$REDIRECT_URI'

AUTHORIZATION_CODE - Der Code, der von der redirect_uri nach erfolgreicher Anmeldung.
REDIRECT_URI - Die URL, an die der Benutzer nach dem Austausch des Autorisierungscodes weitergeleitet werden soll.
AUTHORIZATION - Ein Base64-kodiertes Token der Anmeldedaten der Anwendung im Format $CONSUMER_KEY:$CONSUMER_SECRET.

Nach dem Austausch des Tokens erhalten Sie eine JSON-Antwort mit dem access_token eingebettet. Sie benötigen dieses Token, um die APIs Account, Extension und User zu verwenden:

{
   "access_token":"xyz123eyJ4NQiOiJNemcxTnpZeU5UTXhPR1kxTlRNMU1HUTBPR1ZsTVRnM05XRXlZamRpWVdRNE1XSTFemhrWmciLCJraWQiOiJNemcxTnpZeU5UTXhPR1kxTlRNMU1HUTBPR1ZsTVRnM05XRXlZamRpWVdRNE1XSTFNemhrWmciLCJhbGciOiJSUzI1NiJ9..gs7JO2RLPFIld7NXM9gnOy9CYaLs_EYXJJilxX76MFBiidoiG9sIW4RkeHLvDVLyFP1eVd_Pt7000wAr13mcXn-6x6D9oJeAH_Iz8nbzd3vmWDZ8VMHf1SueiAaChfvH0yLvwu02sp-QU-tljGYBTJ8Pr1jWQIG-o39XRrBSMis",
   "refresh_token":"dde2a67f-d99f-3f03-810b-1fcae59245de",
   "scope":"default",
   "token_type":"Bearer",
   "expires_in":86400
}

Authentifizierung mit Password Grant

Alle Codeschnipsel in der VBC-API-Dokumentation verwenden die Passwort gewähren Art statt der empfohlenen authorization_code damit sie einfach ausgeführt werden können. Bei diesem Erteilungstyp müssen Sie keine Callback-URL implementieren. Stattdessen geben Sie Ihren VBC-Benutzernamen und Ihr Passwort an, um ein Token anzufordern.

Ersetzen Sie die folgenden Platzhalter im Beispiel durch Ihre eigenen Werte:

VBC_USERNAME - Ihr Vonage Business Communications-Benutzername
VBC_PASSWORD - Ihr Passwort für Vonage Business Communications
CONSUMER_KEY - Der Verbraucherschlüssel, den Sie in Schritt 5 oben erzeugt haben
CONSUMER_SECRET - Das Verbrauchergeheimnis, das Sie in Schritt 5 oben erstellt haben

Anmerkung: Bei der Verwendung von Password Grant müssen Sie Folgendes anhängen @vbc.prod zu Ihrem Benutzernamen.

Warnung: Verwenden Sie für die Token-Anforderung nicht Ihre Anmeldedaten für den VBC Developer Account (*.api). Sie müssen Ihre VBC-Benutzeranmeldeinformationen verwenden für VBC_USERNAME und VBC_PASSWORD.

curl --request POST 'https://api.vonage.com/token' \ --header 'Content-Type: application/x-www-form-urlencoded' \ --data-urlencode 'grant_type=password' \ --data-urlencode 'scope=openid' \ --data-urlencode 'username=$VBC_USERNAME@vbc.prod' \ --data-urlencode 'password=$VBC_PASSWORD' \ --data-urlencode 'client_id=$VBC_CLIENT_ID' \ --data-urlencode 'client_secret=$VBC_CLIENT_SECRET'

Wenn Sie es ausführen, erhalten Sie eine JSON-Antwort mit dem access_token eingebettet. Sie benötigen dieses Token, um die APIs Account, Extension und User zu verwenden:

Token Verfall

Zugangs-Token - Zugangstoken laufen nach 24 Stunden (86400 Sekunden) ab. Wenn ein Zugriffstoken abgelaufen ist, müssen Sie das Aktualisierungs-Token mit dem Aktualisierungs-Gewährungstyp verwenden, um ein neues Zugriffstoken anzufordern.
Token aktualisieren - Aktualisierungs-Tokens laufen nach 7 Tagen (604800 Sekunden) ab. Nach dem Austausch eines Aktualisierungs-Tokens gegen ein Zugangs-Token ist das Aktualisierungs-Token nicht mehr verwendbar, und es wird ein neues Aktualisierungs-Token bereitgestellt. Wenn das Refresh-Token nicht innerhalb des Ablauffensters verwendet wird, müssen Sie sich erneut authentifizieren.

Verwendung des Aktualisierungs-Tokens

Wenn das Zugriffstoken abläuft, müssen Sie mit dem Refresh-Token ein neues Zugriffstoken generieren. Das Refresh-Token wird gesendet, wenn Sie zum ersten Mal eine Anfrage an die /token Endpunkt.

Um das Zugriffstoken neu zu generieren:

curl --location --request POST 'https://api.vonage.com/token' \ --header 'Content-Type: application/x-www-form-urlencoded' \ --data-urlencode 'grant_type=refresh_token' \ --data-urlencode 'client_id=$VBC_CLIENT_ID' \ --data-urlencode 'client_secret=$VBC_CLIENT_SECRET' \ --data-urlencode 'refresh_token=$REFRESH_TOKEN'

Ersetzen Sie die folgenden Platzhalter im Beispiel durch Ihre eigenen Werte:

VBC_CLIENT_ID - Die Client-ID aus Ihrer Entwickleranwendung
VBC_CLIENT_SECRET - Das Geheimnis Ihrer Entwickleranwendung
REFRESH_TOKEN - Das Refresh-Token aus Ihrer ersten Anfrage zum Abrufen eines Zugriffstokens.

Dies liefert ein neues Zugriffstoken und ein Refresh-Token

Für alle weiteren API-Anfragen müssen Sie dieses Zugriffs-Token verwenden. Wenn dieses Zugriffs-Token abläuft, müssen Sie ein neues Zugriffs-Token unter Verwendung des letzten Refresh-Tokens generieren.

Nächste Schritte

Nachdem Sie nun ein Zugriffstoken erstellt haben, können Sie eine API-Anfrage stellen.