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 7519y se amplía en otras RFC. Esto proporciona una base sólida para el paso de información entre un cliente y un servidor.

Una característica clave de los JWT es su tamaño compacto. Esto los hace adecuados para su transmisión dentro de URL, POST o cabeceras 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 entorno 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 SDK de cliente de voz y chat en la aplicacióny API de Video de Vonage ambos utilizan tokens web JSON (JWT) para la autenticación, y la API de Video API de Vonage utiliza JWT para pasar la configuración adicional del cliente para los clientes de video.

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 cliente 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 portador. 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 Video de Vonage tendrá que utilizar el parámetro 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 saber qué información se necesita para un token JWT de API REST, consulte la sección Estructura JWT más abajo. Todos los tokens JWT de llamada 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);

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 Applications cliente que utilizan los SDK cliente de la Video API necesitan 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 lado del servidor de tu aplicación y luego se pasan al cliente. Esto permite que el token se firme de manera segura usando la clave privada de la aplicación de Vonage. Para facilitar este proceso, la creación de tokens de conexión de cliente está incorporada 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 tiene una variedad de formas en las que puedes crear JWT, que pueden ser útiles durante las pruebas y la depuración.

Uso del SDK del servidor de Vonage

Recomendamos utilizar los SDK de servidor para generar 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 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 se puede utilizar esta herramienta para crear testigos de conexión de cliente.

Uso de la CLI de Vonage

En 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

Puede utilizar el CLI de Vonage para crear tokens de conexión de cliente también. Es necesario pasar el reclamaciones adicionales de 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 encontrarás ejemplos del uso de las bibliotecas de Vonage para generar JWTs. Si no utilizas una biblioteca de Vonage, consulta 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 ser compartida entre un cliente (ya sea un cliente de sesión de video o un servidor backend) con las propias API de Vonage. Esto incluye información que se necesita para ayudar a trabajar con los puntos finales de la API REST y los servidores cliente, así como información sobre la validez del token en sí.

Todos los JWT que interactúan con la Video API de Vonage tienen los siguientes Claims básicos o claves informativas:

Ejemplo de token 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 utilizados para realizar llamadas a la API REST sólo necesitan estas declaraciones.

Reclamaciones adicionales para tokens de conexión de clientes

Para generar un JWT para su uso como testigo de conexión para un cliente que utilice uno de los SDK para clientes de vídeodebe presentar solicitudes adicionales a las descritas anteriormente.

Ejemplo de carga útil de token de conexión de cliente de 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/** lo que les permite unirse a una sesión de vídeo. Hay más puntos finales disponibles, pero no relacionados con Video API.

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

Ver también

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