Authentification aux API de Vonage Business Communications

Une fois que vous avez a créé votre applicationet souscrit à l'API de provisionnement vous êtes prêt à créer un jeton d'accès. Les API de Vonage Business Communications utilisent OAuth pour l'authentification.

Création de clés d'authentification

  1. Se connecter à l'application Portail des développeurs pour les communications d'entreprise en utilisant vos identifiants de développeur.

  2. Sélectionner Applications dans le menu de navigation supérieur.

  3. Sur le site Applications localisez votre application dans le tableau et cliquez sur l'application nom lien.

  4. Sélectionnez l'option Clés de production dans le menu de navigation de gauche :

    Screenshot showing the Production Keys tab of the My Applications page

    Note : Le type de subvention par défaut est Password. Les type de subvention est la méthode utilisée par OAuth pour générer un jeton d'accès. Lorsque vous créez une application de production, vous souhaitez généralement utiliser la méthode Code pour authentifier les demandes. La méthode d'authentification Refresh Token créera un nouveau jeton lorsque le jeton actuel expirera.

  5. Si Code sélectionné, dans le URL de rappel saisissez une URL de rappel valide que votre application utilisera pour recevoir le code généré. Si vous n'avez pas encore créé votre application, entrez http://localhost pour l'instant et n'oubliez pas d'entrer l'URL correcte lorsque vous serez prêt à le tester.

    Remarque : Si vous prévoyez d'utiliser le type de subvention par mot de passe pour votre application, vous n'aurez pas besoin d'utiliser une URL de rappel pour récupérer le jeton comme vous le feriez en utilisant le flux de code d'autorisation. Si vous utilisez la subvention par mot de passe, vous pouvez laisser ce champ vide.

  6. Cliquez sur le bouton Générer des clés bouton. Cela génère le Clé du consommateur et Secret du consommateur que votre application utilisera pour demander un jeton.

Types de subventions soutenues

Vonage Business Communications prend en charge les types de subventions suivants pour générer des jetons d'accès.

  • Code d'autorisation - Le type de subvention Code d'autorisation est utilisé par les clients confidentiels et publics pour échanger un code d'autorisation contre un jeton d'accès. Une fois que l'utilisateur retourne au client via l'URL de redirection, l'application obtient le code d'autorisation à partir de l'URL et l'utilise pour demander un jeton d'accès.
  • Octroi du mot de passe - Le type de subvention Mot de passe permet d'échanger les informations d'identification d'un utilisateur contre un jeton d'accès.

Quand utiliser le type d'octroi de mot de passe ?

Le type d'octroi Mot de passe exige que l'application recueille le mot de passe de l'utilisateur. Il est recommandé d'utiliser ce type d'octroi uniquement pour activer des applications serveur à serveur dans lesquelles la collecte des informations d'identification de l'utilisateur n'est pas nécessaire.

  1. Regardez le Exemples de points finaux et Générer des jetons d'accès pour savoir comment demander le code d'authentification et l'échanger contre un jeton d'accès :

En production, il convient d'utiliser l'option code_autorisation type de subvention (Code) et c'est la seule option qui apparaît dans l'onglet Mes Applications à l'adresse apimanager.uc.vonage.com. Les Code exige que votre application mette en œuvre une URL de rappel valide pour récupérer le code d'autorisation auprès des serveurs Vonage et l'échanger contre un jeton. Consultez les exemples de points de terminaison dans l'onglet Mes Applications pour savoir comment créer les demandes d'autorisation et de jeton.

Authentification par code d'autorisation Grant

Avertissement : Le SSO n'est pas pris en charge pour le moment

L'exemple suivant montre comment obtenir un code d'autorisation via le point final authorize.

https://api.vonage.com/authorize?scope=openid&response_type=code&redirect_uri=$REDIRECT_URI&client_id=$CONSUMER_KEY
  • REDIRECT_URI - URL vers laquelle rediriger l'utilisateur après l'authentification.
  • CONSUMER_KEY - La clé de consommateur que vous avez générée à l'étape 5 ci-dessus

L'exemple suivant montre comment échanger un code d'autorisation contre un jeton via le point de terminaison du jeton

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 - Le code reçu par le redirect_uri après avoir réussi à se connecter.
  • REDIRECT_URI - URL vers laquelle rediriger l'utilisateur après l'échange du code d'autorisation.
  • AUTHORIZATION - Un jeton codé en Base64 des informations d'identification de l'application au format $CONSUMER_KEY:$CONSUMER_SECRET.

Après avoir échangé le jeton, vous recevrez une réponse JSON contenant le code access_token qui y est incorporé. Vous avez besoin de ce jeton pour utiliser les API Account, Extension et User :

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

Authentification par l'octroi d'un mot de passe

Tous les extraits de code de la documentation de l'API VBC utilisent l'élément mot de passe type de subvention au lieu de l'option recommandée authorization_code afin de faciliter leur exécution. Ce type de subvention ne nécessite pas la mise en œuvre d'une URL de rappel. Au lieu de cela, vous fournissez votre nom d'utilisateur et votre mot de passe VBC pour demander un jeton.

Remplacez les espaces réservés suivants dans l'exemple par vos propres valeurs :

  • VBC_USERNAME - Votre nom d'utilisateur Vonage Business Communications
  • VBC_PASSWORD - Votre mot de passe Vonage Business Communications
  • CONSUMER_KEY - La clé de consommateur que vous avez générée à l'étape 5 ci-dessus
  • CONSUMER_SECRET - Le secret du consommateur que vous avez généré à l'étape 5 ci-dessus

Remarque : Si vous utilisez l'octroi d'un mot de passe, vous devrez ajouter l'élément suivant @vbc.prod à votre nom d'utilisateur.

Avertissement : N'utilisez pas les informations d'identification de votre compte VBC Developer (*.api) pour la demande de jeton. Vous devez utiliser vos informations d'identification d'utilisateur VBC pour la demande de jeton. VBC_USERNAME et 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'

Lorsque vous l'exécutez, vous recevrez une réponse JSON avec la balise access_token qui y est incorporé. Vous avez besoin de ce jeton pour utiliser les API Account, Extension et User :

{
    "access_token": "xyz123eyJ4NQiOiJNemcxTnpZeU5UTXhPR1kxTlRNMU1HUTBPR1ZsTVRnM05XRXlZamRpWVdRNE1XSTFemhrWmciLCJraWQiOiJNemcxTnpZeU5UTXhPR1kxTlRNMU1HUTBPR1ZsTVRnM05XRXlZamRpWVdRNE1XSTFNemhrWmciLCJhbGciOiJSUzI1NiJ9..gs7JO2RLPFIld7NXM9gnOy9CYaLs_EYXJJilxX76MFBiidoiG9sIW4RkeHLvDVLyFP1eVd_Pt7000wAr13mcXn-6x6D9oJeAH_Iz8nbzd3vmWDZ8VMHf1SueiAaChfvH0yLvwu02sp-QU-tljGYBTJ8Pr1jWQIG-o39XRrBSMis",
    "refresh_token": "abc123-5903-3513-8d27-333daf581837",
    "scope": "openid",
    "id_token": "abc123eyJ4NQiOiJNemcxTnpZeU5UTXhPR1kxTlRNMU1HUTBPR1ZsTVRnM05XRXlZamRpWVdRNE1XSTFemhrWmciLCJraWQiOiJNemcxTnpZeU5UTXhPR1kxTlRNMU1HUTBPR1ZsTVRnM05XRXlZamRpWVdRNE1XSTFNemhrWmciLCJhbGciOiJSUzI1NiJ9..gs7JO2RLPFIld7NXM9gnOy9CYaLs_EYXJJilxX76MFBiidoiG9sIW4RkeHLvDVLyFP1eVd_Pt7000wAr13mcXn-6x6D9oJeAH_Iz8nbzd3vmWDZ8VMHf1SueiAaChfvH0yLvwu02sp-QU-tljGYBTJ8Pr1jWQIG-o39XRrBSMis",
    "token_type": "Bearer",
    "expires_in": 82566
}

Expiration du jeton

  • Jeton d'accès - Les jetons d'accès expirent au bout de 24 heures (86400 secondes). Après l'expiration d'un jeton d'accès, vous devrez utiliser le jeton de rafraîchissement avec le type de subvention de rafraîchissement pour demander un nouveau jeton d'accès.
  • Jeton de rafraîchissement - Les jetons de rafraîchissement expirent au bout de 7 jours (604800 secondes). Lorsqu'un jeton de rafraîchissement est échangé contre un jeton d'accès, le jeton de rafraîchissement n'est plus utilisable et un nouveau jeton de rafraîchissement est fourni. Si le jeton de rafraîchissement n'est pas utilisé dans la fenêtre d'expiration, vous devrez vous réauthentifier.

Utilisation du jeton de rafraîchissement

Lorsque le jeton d'accès expire, vous devez régénérer un nouveau jeton d'accès en utilisant le jeton de rafraîchissement. Le jeton de rafraîchissement sera envoyé lorsque vous ferez une première demande à l'application /token point final.

Pour régénérer le jeton d'accès :

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'

Remplacez les espaces réservés suivants dans l'exemple par vos propres valeurs :

  • VBC_CLIENT_ID - L'identifiant du client de votre application de développement
  • VBC_CLIENT_SECRET - Le secret de votre application de développement
  • REFRESH_TOKEN - Le jeton de rafraîchissement de votre demande initiale de récupération d'un jeton d'accès.

Cette opération renvoie un nouveau jeton d'accès et un nouveau jeton de rafraîchissement.

{
   "access_token": "xyz123eyJ4NQiOiJNemcxTnpZeU5UTXhPR1kxTlRNMU1HUTBPR1ZsTVRnM05XRXlZamRpWVdRNE1XSTFemhrWmciLCJraWQiOiJNemcxTnpZeU5UTXhPR1kxTlRNMU1HUTBPR1ZsTVRnM05XRXlZamRpWVdRNE1XSTFNemhrWmciLCJhbGciOiJSUzI1NiJ9..gs7JO2RLPFIld7NXM9gnOy9CYaLs_EYXJJilxX76MFBiidoiG9sIW4RkeHLvDVLyFP1eVd_Pt7000wAr13mcXn-6x6D9oJeAH_Iz8nbzd3vmWDZ8VMHf1SueiAaChfvH0yLvwu02sp-QU-tljGYBTJ8Pr1jWQIG-o39XRrBSMis",
    "refresh_token": "abc123-5903-3513-8d27-333daf581837",
    "scope": "openid",
    "id_token": "abc123eyJ4NXQiOiJNemcxTnpZeU5UTXhPR1kxTlRNMU1HUTBPR1ZsTVRnM05XRXlZamRpWVdRNE1XSTFNemhrWmciLCJraWQiOiJNemcxTnpZeU5UTXhPR1kxTlRNMU1HUTBPR1ZsTVRnM05XRXlZamRpWVdRNE1XSTFNemhrWmciLCJhbGciOiJSUzI1NiJ9..kpFXRg4qSW9sntliysg-3EGO8KwZ8Vk5jGvOwqq0gJEyPQHL5BQKKrF799VL6Z9OJfCne564N42UWnrQqUmNyU0q8l0td1E3zPA0L5iQQEbaVsbxRf5NCZUwYY9Pb7bXjINCiGF4Xy7wCw2SRpv9iQvg3G68qI5Z8f_25QmxSTY",
    "token_type": "Bearer",
    "expires_in": 86400
}

Pour toutes les demandes d'API ultérieures, vous devrez utiliser ce jeton d'accès. Lorsque ce jeton d'accès expirera, vous devrez régénérer un nouveau jeton d'accès en utilisant le dernier jeton de rafraîchissement.

Prochaines étapes

Maintenant que vous avez créé un jeton d'accès, vous êtes prêt à faire une demande d'API.