Authentification

Vue d'ensemble

Les jetons Web JSON, ou JWTS, sont un moyen compact et autonome de transmettre des informations en toute sécurité entre des parties, en utilisant un objet JSON pour fournir une structure. Ces informations peuvent être vérifiées et structurées comme elles peuvent être signées numériquement.

Les JWT sont une norme ouverte, formellement définie dans le document RFC 7519Il est ensuite étendu dans une série d'autres RFC. Il constitue une base solide pour la transmission d'informations entre un client et un serveur.

L'une des principales caractéristiques des JWT est leur taille compacte. Ils peuvent donc être transmis dans des URL, POST ou des en-têtes HTTP. Le JWT lui-même est également encodé sous la forme d'une chaîne Base-64, ce qui le rend facile à injecter dans des applications à partir de sources telles que des applications en ligne de commande, des fichiers d'environnement et sur Internet.

Vonage utilise principalement les JWT pour l'authentification à une variété d'API à la fois sur le front-end et le back-end. Le site Web de Vonage In-App Chat et Client Voice SDKet Video API de Vonage utilisent tous deux des jetons Web JSON (JWT) pour l'authentification, et l'API Video de Vonage utilise des JWT pour transmettre une configuration client supplémentaire aux clients vidéo.

Ces jetons sont ensuite signés cryptographiquement à l'aide d'une clé privée associée à un Applications Vonage. Ce processus de signature constitue un moyen sûr de valider que les jetons utilisés proviennent bien de votre application.

Utilisation des JWT

Pour Vonage Video, les JWT sont utilisés à deux endroits :

• Appels à l'API REST
• Connexions des clients vidéo

Bien que les deux usages utilisent des JWT, les informations contenues dans chacun d'entre eux sont différentes.

Appels à l'API REST

L'API Video de Vonage utilise Authentification du porteur. Alors que l'authentification par porteur est une extension du schéma d'authentification OAuth 2.0, Vonage utilise la méthode non interactive de génération OAuth 2.0 pour créer un jeton de porteur à l'aide de la structure JWT et de votre clé privée.

Lors de l'envoi d'une demande à API Video REST de Vonage Vous devrez utiliser le point de terminaison Authorization dans le format suivant :

Authorization: Bearer <JWT>

const JWT = 'eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiaWF0IjoxNTE2MjM5MDIyfQ.SflKxwRJSMeKKF2QT4fwpMeJf36POk6yJV_adQssw5c';

fetch(`https://video.api.vonage.com/session/create`, {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${JWT}`
  }
});

Pour savoir quelles informations sont nécessaires pour un jeton JWT de l'API REST, voir la section Structure des JWT ci-dessous. Tous les jetons JWT des appels à l'API REST sont considérés comme des jetons "root", ce qui signifie qu'ils ont un accès complet à l'API REST. Ces jetons doivent JAMAIS être partagée avec un client frontal.

Bien que vous puissiez générer un jeton JWT vous-même, nous avons des aides intégrées aux SDK ainsi que des wrappers spécifiques aux JWT qui sont conçus pour fonctionner avec les API de Vonage. Les SDK du serveur génèrent automatiquement des JWT pour chaque demande, mais si vous avez besoin de générer un JWT pour une fonction qui n'est pas dans les SDK ou pour tester des fonctions bêta, nous fournissons également des générateurs de JWT indépendants des SDK :

const { tokenGenerate } = require('@vonage/jwt');

const privateKey = readFileSync('path/to/private.key');

const aclPaths = {
  "paths": {
    ...
  }
}

const token = tokenGenerate("aaaaaaaa-bbbb-cccc-dddd-0123456789ab", privateKey, {
      //expire in 24 hours
      exp: Math.round(new Date().getTime()/1000)+86400,
      sub: "Alice",
      acl: aclPaths,
    });

String token = Jwt.builder()
    .applicationId("aaaaaaaa-bbbb-cccc-dddd-0123456789ab")
    .privateKeyPath(Paths.get("/path/to/private.key"))
    .subject("Alice")
    .issuedAt(ZonedDateTime.now())
    .expiresAt(ZonedDateTime.now().plusMinutes(20))
    .addClaim("acl", Map.of(
        "paths", Map.of(
            ...
        )
    ))
    .build()
    .generate();

$keypair = new \Vonage\Client\Credentials\Keypair(
    file_get_contents('/path/to/private.key'),
    'aaaaaaaa-bbbb-cccc-dddd-0123456789ab'
);
$client = new \Vonage\Client($keypair);

$claims = [
    'acl' => [
        'paths' => [
            ...
        ]
    ]
];
$token = $client->generateJwt($claims);
$tokenString = $token->toString();

Client SDK Jetons de connexion

Les applications clientes utilisant les SDK clients de Video API nécessitent jetons de connexion pour s'authentifier lorsque se connecter à une session. Il s'agit d'un moyen signé et sécurisé de transmettre les informations de connexion d'un utilisateur spécifique sans avoir à fournir un accès complet à l'API. Les JWT clients sont verrouillés pour une application spécifique, ont une portée stricte dans ce à quoi ils peuvent accéder, et ne sont valides que pour des routes et des méthodes HTTP spécifiques. Les jetons du Client SDK vidéo contiennent des informations supplémentaires qui facilitent la transmission d'informations au client frontal.

Les jetons de connexion client sont générés sur la partie serveur de votre application, puis transmis au client. Cela permet de signer le jeton en toute sécurité à l'aide de la clé privée de l'Application Vonage. Pour faciliter ce processus, la création de jetons de connexion client est intégrée dans les SDK et nous fournissons des wrappers :

Comme pour les SDK côté serveur, vous pouvez créer vous-même des jetons clients si vous en avez besoin. Consultez la page Structure JWT pour savoir quelles sont les informations supplémentaires requises pour un jeton client. Chaque Client SDK contient une méthode d'aide pour créer des jetons clients pour vous :

const { Auth } = require('@vonage/auth');
const { Vonage } = require('@vonage/server-sdk');

const APPLICATION_ID = '0400b206-2602-474b-ac63-361b7474ca37';
const PRIVATE_KEY = fs.readFileSync('/path/to/private.key');
const SESSION_ID = '1_MX4wNDA3YjIwNi0yMTAyLTQ3NGItYWM2My0zNjFiNzQ3NGNhMzN-fjE3NDc3Mzc5NjI5MjR-NkQwd2g1TEdpSHEyZENzUk1QaEpDUWFPfn5-';

const credentials = new Auth({
    applicationId: 'APPLICATION_ID',
    privateKey: 'PRIVATE KEY',
});

const vonage = new Vonage(credentials);
const options = {
    role: "moderator",
    data: "name=Johnny",
    initialLayoutClassList: ["focus"]
}
const token = vonage.video.generateClientToken(sessionId, options);

// `token` can then be returned to the client

Création de JWTs

Vonage propose plusieurs façons de créer des JWT, ce qui peut s'avérer utile lors des tests et du débogage.

Utilisation du SDK de Vonage Server

Nous recommandons d'utiliser les SDK du serveur pour générer un jeton côté client. Cela offre des garanties supplémentaires et des valeurs par défaut pour les JWT, et réduit la création des jetons à un seul appel. Les appels à l'API REST génèrent automatiquement des JWT par demande, de sorte qu'il n'est pas nécessaire pour un utilisateur de créer un JWT pour accéder à l'API REST.

Utilisation de l'outil en ligne Vonage API

Si vous souhaitez générer un JWT côté serveur à des fins de test, vous pouvez générer un JWT à l'aide de la fonction outil en ligne.

Saisissez votre clé privée et l'identifiant d'application de votre application vidéo. Pour les jetons JWT côté serveur vidéo, vous devrez laisser les options "Sub" et "ACL" vides. Le JWT résultant peut être utilisé dans les commandes cURL ou les clients API pour tester les appels à l'API REST.

Actuellement, vous ne pouvez pas utiliser cet outil pour créer des jetons de connexion client.

Utilisation de la CLI de Vonage

Les CLI Vonage fournit une commande pour générer un JWT. Le CLI vous permet de définir toutes les propriétés/réclamations supplémentaires nécessaires à un JWT et peut être utilisé de manière programmatique pour créer des JWT.

Pour générer un JWT à utiliser avec l'API REST, vous pouvez procéder comme suit :

Vous pouvez utiliser le CLI Vonage pour créer des jetons de connexion client. Vous devez passer le code réclamations supplémentaires des clients dans le cadre de la commande :

Utilisation d'autres bibliothèques

Vous trouverez ci-dessous des exemples d'utilisation des bibliothèques Vonage pour générer des JWT. Si vous n'utilisez pas de bibliothèque Vonage, vous devez vous référer à RFC 7519 pour mettre en œuvre votre propre solution JWT. Si vous ne souhaitez pas le faire, JWT.io propose une sélection de bibliothèques permettant de générer des JWT dans plusieurs langues.

Structure JWT

Les JWT contiennent des informations qui doivent être partagées entre un client (soit un client de session vidéo, soit un serveur dorsal) et les API de Vonage elles-mêmes. Il s'agit notamment des informations nécessaires pour faciliter le travail avec les points d'extrémité de l'API REST et les serveurs clients, ainsi que des informations sur la validité du jeton lui-même.

Tous les JWT qui interagissent avec l'API Video de Vonage ont les revendications de base suivantes, ou clés d'information :

Exemple de jeton pour les appels à l'API REST

{
  "iat": 1532093588,
  "jti": "705b6f50-8c21-11e8-9bcb-595326422d60",
  "exp": 1532179987,
  "application_id": "aaaaaaaa-bbbb-cccc-dddd-0123456789ab"
}

Les jetons côté serveur utilisés pour effectuer des appels à l'API REST n'ont besoin que de ces revendications.

Revendications supplémentaires pour les jetons de connexion du client

Pour générer un JWT à utiliser en tant que jeton de connexion pour un client utilisant l'un des SDK pour les clients vidéovous devez fournir des déclarations supplémentaires à celles décrites ci-dessus.

Exemple de charge utile de jeton de connexion du client vidéo

{
  "scope": "session.connect",
  "session_id": "1_MX44YjY4NTFmZS01NjdjLTRlODYtYWRmOC0zYmVhODM2MzNjNjB-fjE3NDIzMDY0ODY0NjZ-WS9FOHhybUdHV0JtTGZYTEV2aVlwV1N4fn5-",
  "role": "moderator",
  "initial_layout_class_list": "",
  "sub": "video",
  "acl": {
    "paths": {
      "/session/**": {}
    }
  },
  "jti": "c04c96ba-3229-4fd4-9f55-406b6a6eb485",
  "iat": 1742306486,
  "exp": 1742307386,
  "application_id": "8b6851fe-567c-4e86-adf8-3bea83633c60"
}

Liste de contrôle d'accès (ACL)

Les jetons de connexion du client sont limités par le acl du jeton. Cette liste de contrôle est une liste de chemins auxquels le jeton est autorisé à accéder. Notre API rejettera tout jeton, même un jeton signé avec succès, s'il tente d'appeler une route qui n'est pas décrite dans la section acl.paths.

Dans le cadre de l'API Video, il suffit d'accorder à un utilisateur un accès à /*/session/** ce qui leur permet de participer à une session vidéo. D'autres points de terminaison sont disponibles, mais ils ne sont pas liés à l'API Video.

Notez que les jetons JWT utilisés pour appeler l'API REST n'ont pas besoin de l'option acl réclamer.

Voir aussi

• RFC 7519 - RFC original JWT
• JWT.io - Plus d'informations sur les JWT et les bibliothèques