Tokens de acceso¶

media.access.token

Para las nuevas integraciones, use JWT de espectador. Su aplicación comprueba los permisos del espectador y obtiene un token de reproducción firmado mediante la API de administración de central. El reproductor presenta este token al streamer, que lo valida localmente sin consultar a su aplicación ni a un backend HTTP de autorización.

Un mismo JWT funciona en todos los edges del clúster que hayan recibido la clave pública correspondiente. Al pasar a otro edge, el espectador no necesita un token nuevo. Este método de admisión elimina la carga de solicitudes de autorización cuando muchos espectadores empiezan a ver contenido a la vez y evita que la admisión de cada espectador dependa de la disponibilidad y la latencia de un backend HTTP externo.

El backend HTTP de autorización es un mecanismo heredado, obsoleto y no recomendado para nuevas integraciones. Se mantiene por compatibilidad.

Cómo se envía el token¶

El token se puede enviar de dos maneras:

• Parámetro de URL — ?token=<token>, que tiene prioridad.
• Cabecera — Authorization: Bearer <token>, que se usa si la URL no contiene el parámetro token.

Para HLS, abra la playlist maestra con el token: Sapsan lo añade a las URL de las playlists y los medios anidados. Si usa una cabecera, el cliente debe enviarla en las solicitudes protegidas. No entregue la clave de administración al reproductor: solo su aplicación la necesita para emitir JWT.

Obtener un JWT mediante central¶

Primero cree un stream llamado news y conecte los streamers a central. Espere a que la configuración y las claves públicas lleguen a los edges. El ejemplo requiere curl y jq; sustituya los dominios y la clave de administración por sus valores.

CENTRAL_URL='https://central.example.com'
EDGE_1='https://edge1.example.com'
EDGE_2='https://edge2.example.com'
ADMIN_KEY='replace-with-management-api-key'

ISSUED=$(curl --fail-with-body --silent --show-error \
  -X POST "$CENTRAL_URL/central/api-v4/play-sessions/grants" \
  -H "Authorization: Bearer $ADMIN_KEY" \
  -H 'Content-Type: application/json' \
  --data '{"streams":["news"],"user_id":"viewer-42","ttl_secs":3600,"max_concurrent":1}')

TOKEN=$(printf '%s' "$ISSUED" | jq -er '.token')
JTI=$(printf '%s' "$ISSUED" | jq -er '.jti')

Central crea una concesión, un registro del acceso otorgado, y devuelve 201 Created. Los campos de la concesión y token están en el mismo nivel de la respuesta. jti identifica la concesión y expires_at indica cuándo caduca, en UTC. El JWT solo se devuelve al crear la concesión; consultarla mediante la API no devuelve el token.

Campos de la solicitud:

Reproducción y cambio de edge¶

Obtenga la playlist HLS del primer edge y después del segundo usando el mismo TOKEN:

curl --fail-with-body --silent --show-error \
  "$EDGE_1/streaming/v/news/index.m3u8?token=$TOKEN"

curl --fail-with-body --silent --show-error \
  "$EDGE_2/streaming/v/news/index.m3u8?token=$TOKEN"

Estos comandos obtienen playlists; para reproducir el contenido, abra la URL correspondiente en un reproductor HLS. Ambos edges deben poder servir el stream news. La validación del JWT por sí sola no asigna el stream ni garantiza la disponibilidad de su fuente.

Para que el balanceador elija el streamer, use https://central.example.com/playback/v/news/index.m3u8?token=<JWT>. La disponibilidad de esta URL también depende de central: selecciona un streamer y redirige la solicitud o actúa como proxy de los medios. Una URL directa del edge la valida el propio streamer.

Cambiar de edge puede crear una nueva sesión local. Central asocia las sesiones con su concesión y tiene en cuenta la actividad para que el edge anterior, que ya no recibe solicitudes de medios, no ocupe el límite indefinidamente. Vea sesión del clúster y cambio de edge.

Alcance y validez¶

El listener MoQ todavía no utiliza este mecanismo de autorización.

El JWT se firma con Ed25519 mediante el algoritmo EdDSA; kid en la cabecera selecciona la clave pública. Su contenido incluye:

• jti — identificador de la concesión.
• user_id — identificador del espectador.
• exp — caducidad en segundos Unix.
• streams — nombres de medios permitidos.
• bind_ip — dirección IP o red, si se ha configurado la vinculación.

El directo y el archivo de un stream usan el mismo nombre: news. Para VOD, indique vod/<asset-id>: la concesión cubre los archivos de ese asset con independencia del root de almacenamiento y del nombre del archivo. El claim estándar aud no se usa para este alcance. El límite max_concurrent se guarda en el registro de central, fuera del JWT.

El edge comprueba localmente la firma, la validez y el alcance, así como la vinculación a IP si está configurada. Se admite un margen de 30 segundos por desfase de reloj. Un JWT no válido se rechaza sin intentar autorizarlo mediante el backend HTTP. Tras la caducidad, se rechazan las siguientes solicitudes HTTP; ampliar el acceso requiere una concesión nueva. No se garantiza la interrupción inmediata de una respuesta HTTP continua ya abierta; esta limitación se explica en autorización de la sesión. Planifique la renovación del token en su aplicación si el espectador puede seguir viendo contenido después de que caduque.

Límite de sesiones y revocación del acceso¶

max_concurrent se aplica a la concesión en todo el clúster. Central recibe información sobre las sesiones y termina de forma asíncrona las sesiones activas más antiguas que superen el límite; la nueva sesión permanece. No se trata de un rechazo inmediato de la segunda solicitud en cada edge. El límite cuenta sesiones del servidor, no necesariamente dispositivos físicos distintos: las solicitudes con los mismos medios, IP y concesión pueden agruparse en una sola sesión HTTP.

Cambiar el límite sin volver a emitir el JWT:

curl --fail-with-body --silent --show-error \
  -X PATCH "$CENTRAL_URL/central/api-v4/play-sessions/grants/$JTI" \
  -H "Authorization: Bearer $ADMIN_KEY" \
  -H 'Content-Type: application/json' \
  --data '{"max_concurrent":2}'

Revocar toda la concesión:

curl --fail-with-body --silent --show-error \
  -X DELETE "$CENTRAL_URL/central/api-v4/play-sessions/grants/$JTI" \
  -H "Authorization: Bearer $ADMIN_KEY"

La revocación devuelve 204 No Content. Central la entrega a los streamers mediante un canal independiente de terminaciones. Al recibirla, el streamer cierra las sesiones de esa concesión y rechaza las nuevas solicitudes. La revocación no es una comprobación global inmediata en cada solicitud de medios: si pierde la conexión con central, el edge no conoce una nueva revocación hasta que se restablece el canal.

Entrega de claves y funcionamiento sin conexión con central¶

Central conserva la clave privada de firma y entrega las claves públicas a los streamers en auth.ticket_keys, junto con la configuración. Si la política no especifica una lista de claves, central inserta las suyas automáticamente. Un edge con una clave pública puede validar JWT, pero no puede emitir tokens nuevos.

La validación en un edge ya configurado no requiere que central esté disponible. Mientras el JWT sea válido y los medios estén disponibles, la admisión local sigue funcionando con las claves recibidas. Las siguientes operaciones siguen dependiendo de central:

• Emisión de nuevas concesiones — requiere la API de central y su almacenamiento.
• Nuevas claves y cambios de política — deben llegar a los streamers.
• Revocaciones y límite global de sesiones — requieren el canal de terminaciones y la información de sesiones.
• Balanceo mediante /playback — lo realiza central.

Durante una rotación, la clave pública anterior debe seguir disponible para validar los JWT que aún sean válidos. No la elimine antes de que caduquen esos tokens. La compatibilidad con varias claves no implica que exista una API pública de rotación automática.

Tokens estáticos¶

Los tokens estáticos se mantienen por compatibilidad y para instalaciones existentes sencillas. No sustituyen la emisión de concesiones individuales a los espectadores:

auth:
  play_tokens:
  - viewer-secret-1
  publish_tokens:
  - publisher-secret-1

• play_tokens — tokens de reproducción.
• publish_tokens — tokens de publicación.

El JWT de espectador está destinado a la reproducción; no lo use como permiso de publicación. En un clúster administrado, central entrega la política auth; el YAML anterior muestra la estructura de configuración de un streamer independiente.

opaque_tokens vale true por defecto para mantener la compatibilidad. Tras la migración, puede establecerlo en false para desactivar la ruta general de tokens opacos y backends HTTP, incluidos los tokens estáticos de la política global. Los tokens de reproducción de la configuración de cada stream siguen funcionando. Un open_playback explícito sigue abriendo el acceso a la reproducción. Compruebe toda la política de acceso durante la migración.