Authentification

L'API Verify prend en charge deux types d'authentification :

• Authentification de base
• JWT

Quand faut-il utiliser l'authentification de base ou le JWT ?

Verify V2 prend en charge deux méthodes d'authentification : l'authentification de base et l'authentification par porteur JWT. Il est important de comprendre les différences entre ces deux méthodes pour garantir une migration en douceur et tirer pleinement parti des fonctionnalités de la version 2.

Vous pouvez utiliser l'une ou l'autre option, mais pas les deux en même temps. En règle générale, nous recommandons d'utiliser JWT lors de l'utilisation de l'API Verify. Bien que l'authentification de base soit plus facile à mettre en œuvre, elle ne prend pas en charge les fonctions de l'API Verify. Authentification silencieuse canal.

Authentification de base

L'authentification de base envoie votre clé et votre secret API Codé en base64 dans le Authorization de l'en-tête. Vous pouvez trouver ces informations d'identification dans votre fichier Paramètres de l'API dans le tableau de bord de Vonage.

C'est la façon la plus simple de commencer à utiliser Verify V2, car aucune installation de l'application Vonage n'est nécessaire, et vos informations d'identification sont immédiatement disponibles à partir de la page d'accueil de Verify. Tableau de bord Vonage.

Comment ça marche

Authorization: Basic <base64(api_key:api_secret)>

Créer l'en-tête de la demande

• Commencez par concaténer votre clé API et votre secret : API_KEY:API_SECRET.
• Ensuite, Encodage Base64 le résultat. En savoir plus ici.
• Enfin, envoyez-le dans la demande sous la forme suivante Authorization: Basic BASE64_ENCODED_STRING.

Vous pouvez le faire dans le code de votre application - par exemple, en JavaScript :

const credentials = btoa('YOUR_API_KEY:YOUR_API_SECRET');

const response = await fetch('https://api-eu.vonage.com/v2/verify', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'Authorization': 'Basic ' + credentials
  },
  body: JSON.stringify({ ... })
});

Exemple de demande

curl --location --request POST 'https://api.nexmo.com/v2/verify' \
  --header 'Authorization: Basic <base64(YOUR_API_KEY:YOUR_API_SECRET)>' \
  --header 'Content-Type: application/json' \
  --data-raw '{
    "brand": "Acme Inc.",
    "workflow": [
      { "channel": "sms", "to": "447700000000" }
    ]
  }'

Vous pouvez générer la chaîne encodée en Base64 à partir de api_key:api_secret en utilisant n'importe quel outil ou bibliothèque standard de codage Base64.

Limites

L'authentification de base permet d'accéder au flux de demandes de Verify V2 (envoi, vérification, annulation, déclenchement du flux de travail suivant), mais il existe deux limitations importantes :

• Les callbacks/webhooks ne sont pas pris en charge. La réception de rappels d'événements ou de résumés nécessite une authentification JWT Bearer, ainsi qu'une application Vonage configurée avec une URL d'état.
• La prise en charge des listes de contrôle d'accès (ACL) n'est pas disponible. Les jetons JWT permettent d'étendre les autorisations à des points d'extrémité spécifiques de l'API, ce qui n'est pas possible avec l'authentification de base.

Compte tenu de ces limitations, l'authentification de base convient mieux aux tests initiaux et aux intégrations POC. Pour les déploiements en production, l'authentification JWT Bearer est fortement recommandée.

JWT

A JWT (JSON Web Token) est un standard ouvert (RFC 7519) pour la transmission sécurisée d'informations entre les parties sous la forme d'un objet JSON. L'objet peut éventuellement être crypté et signé à l'aide d'une clé privée/publique.

L'authentification par porteur JWT utilise un jeton Web JSON signé avec la clé privée de votre application Vonage. Cette méthode permet de débloquer toutes les capacités de Verify V2, y compris les rappels d'événements et de résumés, la configuration des webhooks et les tokens à portée d'ACL.

Comment ça marche

Authorization: Bearer <JWT>

Le JWT est généré à l'aide de votre identifiant d'application et de votre clé privée, tous deux obtenus lors de la création d'une application Vonage dans le tableau de bord.

Pour générer un JWT, vous aurez besoin de votre fichier application ID et private keyqui se trouvent tous deux dans le Applications dans votre Tableau de bord.

Il existe plusieurs façons de générer un nouveau JWT :

• L'utilisation de la Générateur en ligne JWT.

• L'utilisation de la Outil CLI de Vonage. La clé privée et un identifiant de l'application doivent être fournis :

A noter :

• Si vous utilisez l'un des systèmes Vonage SDK de serveur il n'est pas nécessaire de générer un JWT séparément, car tous les SDK prennent en charge la génération de jetons JWT.

• Si vous ne souhaitez pas générer le JWT à l'aide d'un outil ou d'une bibliothèque externe, comme les SDK de Vonage, vous pouvez mettre en œuvre votre propre génération de JWT. L'outil de génération de JWT de comment générer un JWT comprend des exemples en JavaScript et en Python qui montrent comment générer un JWT sans dépendances externes.

Une fois généré, les utilisateurs doivent pouvoir utiliser le jeton pour accéder aux points d'extrémité protégés. Cela se fait généralement à l'aide de l'en-tête Authorization qui utilise le schéma Bearer :

Authorization: Bearer <JWT>

Étapes d'installation de Verify V2

1. Créez une application Vonage dans l'application Tableau de bord Vonage.
2. Générer une paire de clés publique/privée - télécharger et stocker en toute sécurité la clé privée.
3. Activez Verify V2 pour l'application et configurez l'URL d'état (point d'arrivée du webhook) pour recevoir des rappels.
4. Générez un JWT signé avec votre identifiant d'application et votre clé privée. Vous pouvez utiliser la clé Générateur de JWT, le CLI Vonageou tout SDK de Vonage.
5. Inclure le JWT dans toutes les demandes d'API à l'aide de l'option Authorization: Bearer l'en-tête.

Exemple de demande

curl --location --request POST 'https://api.nexmo.com/v2/verify' \
  --header 'Authorization: Bearer YOUR_JWT' \
  --header 'Content-Type: application/json' \
  --data-raw '{
    "brand": "Acme Inc.",
    "workflow": [
      { "channel": "sms", "to": "447700000000" }
    ]
  }'

Les jetons JWT ont une durée de vie maximale de 24 heures. Assurez-vous que votre intégration rafraîchit les jetons avant leur expiration afin d'éviter que les jetons n'expirent. 401 Unauthorized erreurs.

Ce que JWT débloque

• Rappels sommaires - recevoir un rapport d'état complet à la fin de chaque demande de vérification.
• Rappels d'événements - recevoir des événements en temps réel pendant la demande (par exemple, pour les canaux Silent Auth et WhatsApp Interactive).
• Jetons définis par l'ACL - restreindre les autorisations des jetons à des points d'extrémité spécifiques pour une sécurité accrue.
• Configuration du webhook - configurer verify_event_url et verify_status_url par application Vonage.

Migration de l'authentification à partir de Verify Legacy (V1)

L'un des principaux changements lors de la migration de Verify V1 vers Verify V2 est la manière dont l'authentification est gérée.

Dans Verify V1, l'authentification était gérée par le passage du code api_key et api_secret en tant que paramètres de requête ou dans le corps de la requête. Cette méthode n'est pas prise en charge dans Verify V2.