Autenticación

Visión general

Los JSON Web Tokens, o JWTS, son una forma compacta y autocontenida de transmitir información de forma segura entre las partes, utilizando un objeto JSON para proporcionar estructura. Esta información puede verificarse y estructurarse al igual que puede firmarse digitalmente.

Los JWT son un estándar abierto, definido formalmente en RFC 7519, y se amplía aún más en otros muchos RFC. Esto proporciona una base sólida para el intercambio de información entre un cliente y un servidor.

Una característica clave de los JWT es su tamaño compacto. Esto los hace idóneos para su transmisión dentro de las URL, POST parámetros o encabezados HTTP. El propio JWT también está codificado como una cadena Base-64, lo que facilita su inyección en aplicaciones desde fuentes como aplicaciones de línea de comandos, archivos de configuración y a través de Internet.

Vonage utiliza principalmente JWT para la autenticación en una variedad de API tanto en el front-end como en el back-end. El sitio web de Vonage Client SDK para el cliente de chat y voz integrado en la aplicacióny API de Video de Vonage ambos utilizan tokens web JSON (JWT) para la autenticación, y la Video API de Vonage utiliza JWT para transmitir la configuración adicional de los clientes de vídeo.

A continuación, estas fichas se firman criptográficamente mediante una clave privada asociada a un Aplicación de Vonage. Este proceso de firma proporciona una forma segura de validar que los tokens utilizados proceden de su aplicación.

Uso de JWT

Para Vonage Video, los JWT se utilizan en dos lugares:

• Llamadas a la API REST
• Conexiones de clientes de vídeo

Aunque ambos usos utilizan JWT, la información contenida en cada uno de ellos es diferente.

Llamadas a la API REST

La API de Video de Vonage utiliza Autenticación del titular. Si bien la autenticación de portador es una extensión del esquema de autenticación de OAuth 2.0, Vonage utiliza el método no interactivo de generación de OAuth 2.0 para crear un token de portador utilizando la estructura JWT y tu clave privada.

Al enviar una solicitud a API REST de Vonage Video punto final, tendrás que utilizar el Authorization con el siguiente formato:

Authorization: Bearer <JWT>

const JWT = 'eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiaWF0IjoxNTE2MjM5MDIyfQ.SflKxwRJSMeKKF2QT4fwpMeJf36POk6yJV_adQssw5c';

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

Para obtener información sobre qué datos se necesitan para un token JWT de la API REST, consulta la sección «Estructura del JWT» que figura a continuación. Todos los tokens JWT de las llamadas a la API REST se consideran tokens «raíz», lo que significa que tienen acceso completo a la API REST. Estos tokens deben NUNCA compartirse con un cliente front-end.

Si bien puedes generar un token JWT tú mismo, tenemos ayudantes incorporados en los SDK, así como envoltorios específicos de JWT que están diseñados para funcionar con las API de Vonage. Los SDK del servidor generan automáticamente JWT para cada solicitud, pero si necesitas generar un JWT para una función que no está en los SDK o para probar funciones beta, también ofrecemos generadores de JWT independientes de los 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,
    });

val token : String = Jwt.builder()
    .applicationId("aaaaaaaa-bbbb-cccc-dddd-0123456789ab")
    .privateKeyPath("/path/to/private.key")
    .issuedAt(ZonedDateTime.now())
    .subject("Alice")
    .addClaim("acl", mapOf(
        "paths" to mapOf(
            ...
        )
    ))
    .build()
    .generate()

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();

var payload = new Dictionary<string, object>
{
    {"sub", "Alice"},
    {"exp", DateTimeOffset.UtcNow.AddDays(1).ToUnixTimeSeconds().ToString()},
    {
        "acl", new Dictionary<string, object>
        {
            ["paths"] = new Dictionary<string, object>
            {
                ...
            },
        }
    },
};

var credentials = Credentials.FromAppIdAndPrivateKeyPath(VONAGE_APPLICATION_ID, VONAGE_APPLICATION_PRIVATE_KEY_PATH);
var token = Jwt.CreateToken(credentials.ApplicationId, credentials.ApplicationKey, payload);

// Using the credentials instance
var result = tokenGenerator.GenerateToken(credentials, payload);

// Using ApplicationId and ApplicationKey values
var result = tokenGenerator.GenerateToken(credentials.ApplicationId, credentials.ApplicationKey, payload);

$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();

from vonage_jwt import JwtClient

jwt_client = JwtClient(application_id, private_key)

# The `claims` field is optional and can be omitted as defaults are set

paths = { ... }
claims = {'sub': 'Alice', 'paths': paths}
vonage_jwt = jwt_client.generate_application_jwt(claims)

@builder = Vonage::JWTBuilder.new(application_id: YOUR_APPLICATION_ID, private_key: YOUR_PRIVATE_KEY)
@token = @builder.jwt.generate

Tokens de conexión Client SDK

Las aplicaciones cliente que utilizan los SDK de cliente de la Video API requieren fichas de conexión para autenticar cuando conectarse a una sesión. Esto permite una forma firmada y segura de transmitir la información de conexión para un usuario específico sin necesidad de proporcionar acceso completo a la API. Los JWT de cliente están restringidos a una aplicación específica, tienen un alcance estricto en cuanto a lo que pueden acceder y sólo son válidos para rutas y métodos HTTP específicos. Los tokens Video Client SDK tienen información adicional para facilitar la transmisión de información al cliente front-end.

Los tokens de conexión del cliente se generan en la parte del servidor de tu aplicación y, a continuación, se envían al cliente. Esto permite que el token se firme de forma segura utilizando la clave privada de la aplicación de Vonage. Para facilitar este proceso, la creación de tokens de conexión del cliente está integrada en los SDK, y proporcionamos envoltorios:

Al igual que con los SDK del lado del servidor, usted mismo puede crear tokens de cliente si tiene una necesidad específica de hacerlo. Consulte el Estructura JWT para saber qué información adicional necesita un token de cliente. Cada SDK contiene un método de ayuda para crear tokens de cliente:

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

Creación de JWTs

Vonage ofrece diversas formas de crear JWT, lo cual puede resultar útil durante las pruebas y la depuración.

Uso del SDK del servidor de Vonage

Recomendamos utilizar los SDK de servidor para generar un token del lado del cliente. Esto proporciona algunas salvaguardas adicionales y valores por defecto para los JWT, y reduce la creación de los tokens a una sola llamada. Las llamadas a la API REST generan automáticamente JWT por solicitud, por lo que no es necesario que un usuario cree un JWT para acceder a la API REST.

Uso de la herramienta en línea de la API de Vonage

Si desea generar un JWT del lado del servidor con fines de prueba, puede generar un JWT utilizando nuestra herramienta herramienta en línea.

Introduzca su clave privada y el ID de aplicación de su aplicación de vídeo. Para los tokens JWT del lado del servidor de vídeo, deberá dejar vacías las opciones "Sub" y "ACL". El JWT resultante puede utilizarse en comandos cURL o clientes API para probar las llamadas a la API REST.

Actualmente no es posible utilizar esta herramienta para crear tokens de conexión de cliente.

Uso de la CLI de Vonage

El CLI de Vonage proporciona un comando para generar un JWT. La CLI permite establecer todas las propiedades/reclamaciones adicionales que se necesitan para un JWT, y se puede utilizar mediante programación para crear JWT.

Para generar un JWT para su uso con la API REST, puede utilizar lo siguiente:

# A command with parameters
vonage jwt create `
--app-id='00000000-0000-0000-0000-000000000000' `
--private-key=./private.key

# Will produce a token
eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9.eyJleHAiOjE3MzYyODE5NDYsImp0aSI6IjBmZjcwZDNmLTAzN2EtNGY4MC04ODZjLWI3MmM3MmQyMWNmMiIsImlhdCI6MTczNjI4MTA0NiwiYXBwbGljYXRpb25faWQiOiIwMDAwMDAwMC0wMDAwLTAwMDAtMDAwMC0wMDAwMDAwMDAwMDAifQ.gA7jClpqaZ2OoS0iri-zGCbda4jO7C0M8mka0EnSyjlds1EeY8fNoBEx3FTXHfkkzzrj0TskrWc_dcs1wuM8Kx55c5rLQ7taVpDAYopKSc_CeeOaad8S6aWnRkTUTNeduO4aIn-0CbyRTluBYsH1RBqYBQvobuQIDEwbFw8xBgx0UfREMMN6DAWknR57eiVXN9x_oD6CGQJ1yV3025nGboeMsP9YgX4Nwc-rE2r8c1ZGwCLO81x8i19Qil3Nwu5q1nzouyavQjIw00B_TZkushnI1ufdi_GNqk-h5q2HvGkg7Pj9bVkZHFdVTO8im03JYNyJmcV83vnpjOLuCFRzxQ

REM A command with parameters
vonage jwt create ^
--app-id='00000000-0000-0000-0000-000000000000' ^
--private-key=./private.key

REM Will produce a token
eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9.eyJleHAiOjE3MzYyODE5NDYsImp0aSI6IjBmZjcwZDNmLTAzN2EtNGY4MC04ODZjLWI3MmM3MmQyMWNmMiIsImlhdCI6MTczNjI4MTA0NiwiYXBwbGljYXRpb25faWQiOiIwMDAwMDAwMC0wMDAwLTAwMDAtMDAwMC0wMDAwMDAwMDAwMDAifQ.gA7jClpqaZ2OoS0iri-zGCbda4jO7C0M8mka0EnSyjlds1EeY8fNoBEx3FTXHfkkzzrj0TskrWc_dcs1wuM8Kx55c5rLQ7taVpDAYopKSc_CeeOaad8S6aWnRkTUTNeduO4aIn-0CbyRTluBYsH1RBqYBQvobuQIDEwbFw8xBgx0UfREMMN6DAWknR57eiVXN9x_oD6CGQJ1yV3025nGboeMsP9YgX4Nwc-rE2r8c1ZGwCLO81x8i19Qil3Nwu5q1nzouyavQjIw00B_TZkushnI1ufdi_GNqk-h5q2HvGkg7Pj9bVkZHFdVTO8im03JYNyJmcV83vnpjOLuCFRzxQ

Puedes utilizar el CLI de Vonage para crear tokens de conexión de cliente también. Es necesario pasar el reclamaciones adicionales de los clientes como parte del comando:

# A command with parameters
vonage jwt create `
--app-id='00000000-0000-0000-0000-000000000000' `
--private-key=./private.key `
--sub='Alice' `
--acl="{\"paths\":{\"\/*\/sessions\/**\":{}}}"

# Will produce a token
eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9.eyJhY2wiOnsicGF0aHMiOnsiLyovcnRjLyoqIjp7fSwiLyovdXNlcnMvKioiOnt9LCIvKi9jb252ZXJzYXRpb25zLyoqIjp7fSwiLyovc2Vzc2lvbnMvKioiOnt9LCIvKi9kZXZpY2VzLyoqIjp7fSwiLyovcHVzaC8qKiI6e30sIi8qL2tub2NraW5nLyoqIjp7fSwiLyovbGVncy8qKiI6e319fSwiZXhwIjoxNzQxMTgyMzA3LCJzdWIiOiJBbGljZSIsImp0aSI6Ijg1MTViNzk2LTA1YjktNGFkMS04MTRkLTE1NWZjZTQzZWM1YiIsImlhdCI6MTc0MTE4MTQwNywiYXBwbGljYXRpb25faWQiOiIwMDAwMDAwMC0wMDAwLTAwMDAtMDAwMC0wMDAwMDAwMDAwMDAifQ.BscMdDXZ1-nuLtKyPJvw9tE8E8ZjJvTPJPMT9y0TjPz4Q7qqNaqxcjglc5QPtYEjh2YpZH6btSKbUF4XTClI026Hl5_QOBlnayYo7jXwhba16fa5PeyzSf30QFGFrHbANwrQJFVCjd329SZUpwK4GxgB1gf230NhbfmkhegKezqicru2WTGCKm8kQncYliFwIEYUlcRAb2c8xcaVrn_6QNNahyeJRwGFfWpIkX0Oe-S4RDlPjoq47_gYWac9MmaetB4Dd3Yp531AuniGV5JiIShkaEwuY4Zyov4Hcmajm4Lm_UFY119la7vzHis0P7cT9pPUDe5cyPj7eT8-VhitfQ

REM A command with parameters
vonage jwt create ^
--app-id='00000000-0000-0000-0000-000000000000' ^
--private-key=./private.key ^
--sub='Alice' ^
--acl="{\"paths\":{\"\/*\/sessions\/**\":{}}}"

REM Will produce a token
eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9.eyJhY2wiOnsicGF0aHMiOnsiLyovcnRjLyoqIjp7fSwiLyovdXNlcnMvKioiOnt9LCIvKi9jb252ZXJzYXRpb25zLyoqIjp7fSwiLyovc2Vzc2lvbnMvKioiOnt9LCIvKi9kZXZpY2VzLyoqIjp7fSwiLyovcHVzaC8qKiI6e30sIi8qL2tub2NraW5nLyoqIjp7fSwiLyovbGVncy8qKiI6e319fSwiZXhwIjoxNzQxMTgyMzA3LCJzdWIiOiJBbGljZSIsImp0aSI6Ijg1MTViNzk2LTA1YjktNGFkMS04MTRkLTE1NWZjZTQzZWM1YiIsImlhdCI6MTc0MTE4MTQwNywiYXBwbGljYXRpb25faWQiOiIwMDAwMDAwMC0wMDAwLTAwMDAtMDAwMC0wMDAwMDAwMDAwMDAifQ.BscMdDXZ1-nuLtKyPJvw9tE8E8ZjJvTPJPMT9y0TjPz4Q7qqNaqxcjglc5QPtYEjh2YpZH6btSKbUF4XTClI026Hl5_QOBlnayYo7jXwhba16fa5PeyzSf30QFGFrHbANwrQJFVCjd329SZUpwK4GxgB1gf230NhbfmkhegKezqicru2WTGCKm8kQncYliFwIEYUlcRAb2c8xcaVrn_6QNNahyeJRwGFfWpIkX0Oe-S4RDlPjoq47_gYWac9MmaetB4Dd3Yp531AuniGV5JiIShkaEwuY4Zyov4Hcmajm4Lm_UFY119la7vzHis0P7cT9pPUDe5cyPj7eT8-VhitfQ

Utilización de otras bibliotecas

A continuación se incluyen ejemplos del uso de las bibliotecas de Vonage para generar JWT. Si no utilizas una biblioteca de Vonage, debes consultar RFC 7519 para implementar su propia solución JWT. Si usted no quiere hacer eso, JWT.io dispone de una selección de bibliotecas para generar JWT en varios idiomas.

Estructura JWT

Los JWT contienen información que debe compartirse entre un cliente (ya sea un cliente de sesión de vídeo o un servidor backend) y las propias API de Vonage. Esto incluye información necesaria para interactuar con los puntos finales de la API REST y los servidores de los clientes, así como información sobre la validez del propio token.

Todos los JWT que interactúan con la Video API de Vonage cuentan con las siguientes «Claims» básicas, o claves informativas:

Token de ejemplo para llamadas a la API REST

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

Los tokens del lado del servidor que se utilizan para realizar llamadas a la API REST solo necesitan estas afirmaciones.

Reclamaciones adicionales para tokens de conexión de clientes

Para generar un JWT para su uso como token de conexión para un cliente que utiliza uno de los SDK de cliente de vídeo, debes presentar reclamaciones adicionales a las descritas anteriormente.

Ejemplo de carga útil del token de conexión del cliente en vídeo

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

Lista de control de acceso (ACL)

Los tokens de conexión de cliente están limitados por el acl del token. Esta ACL es una lista de rutas a las que el token tiene permitido acceder. Nuestra API rechazará cualquier token, incluso un token firmado correctamente, si intenta llamar a una ruta que no esté indicada en acl.paths.

A efectos de la Video API, sólo es necesario conceder a un usuario acceso a /*/session/** punto final, lo que les permite unirse a una sesión de vídeo. Hay más puntos finales disponibles, pero no están relacionados con la Video API.

Tenga en cuenta que los tokens JWT que se utilizan para llamar a la API REST no requieren un acl afirmación.

Véase también

• RFC 7519 - RFC JWT original
• JWT.io - Más información sobre los JWT y las bibliotecas