Guía de la API de REST (servidor a servidor) rest-api-cookbook-server-to-server
Información general overview
El propósito de este documento de guía es detallar las prácticas recomendadas para implementar la autenticación de Adobe Pass mediante las arquitecturas de servidor a servidor. Proporciona requisitos básicos, implementación de flujo paso a paso y consideraciones generales para entornos y operaciones de producción.
Mecanismo de limitación
La API de REST de autenticación de Adobe Pass se rige por un mecanismo de restricción.
Componentes components
En una solución de servidor a servidor en funcionamiento están implicados los siguientes componentes:
Los términos adicionales utilizados en el flujo se definen en la variable
Glosario.
Flujos flows
Registro dinámico de clientes (DCR)
Adobe Pass utiliza DCR para proteger las comunicaciones de cliente entre una aplicación o un servidor de programación y los servicios de Adobe Pass. El flujo de DCR es independiente y se describe en la documentación de información general sobre el registro dinámico de clientes.
Autenticación (authN)
El flujo de autenticación se utiliza para permitir que un usuario se identifique
a su MVPD para determinar si el usuario tiene una cuenta válida.
- El usuario inicia la aplicación Dispositivo de streaming e intenta iniciar sesión o ver contenido protegido.
- La aplicación Dispositivo de streaming realiza una solicitud al servicio Programador para determinar si el dispositivo ya está autenticado.
- El servicio Programador registra la aplicación mediante DCR.
- El servicio de programación comprueba el estado de authN del dispositivo de streaming llamando a la API del servicio de Adobe Pass checkauthn.
- En el caso de que la llamada checkauthn devuelva el estado de autenticación del dispositivo del usuario, la aplicación podrá continuar con el flujo de autorización.
- En el caso de que la llamada checkauthn devuelva el estado de que el dispositivo de usuario NO está autenticado, la aplicación debería esperar a que un usuario solicite iniciar sesión.
- Cuando el usuario solicita iniciar sesión directamente (por ejemplo, selecciona el botón de inicio de sesión) o indirectamente (por ejemplo, selecciona el contenido protegido cuando aún no se ha autenticado), la aplicación del Dispositivo de streaming realiza una solicitud al Servicio de programador para iniciar la autenticación de usuario. El servicio de programación solicita y recibe un código de registro único (regcode) llamando a la API del servicio de Adobe Pass regcode.
- El servicio Programador también recupera la lista de MVPD y atributos actuales llamando a la API config del servicio Adobe Pass. Nota: También se puede llamar a esta API antes en el flujo y almacenarla en la caché.
- El servicio Programador devuelve el regcode a la aplicación Streaming Device y la lista de MVPD procesadas solicitada en el paso #7. Nota: El programador especifica el formato de lista de MVPD procesadas y se pueden filtrar para permitir o bloquear explícitamente MVPD específicas (es decir, listas de permitidos o de bloqueados).
- Si el es diferente del dispositivo AuthN (es decir, "segunda pantalla"), ya sea por elección o por necesidad (es decir, el dispositivo de streaming no admite un agente de usuario), el dispositivo de streaming debe mostrar el regcode y un URI para que el usuario acceda a la aplicación AuthN. El usuario escribe el URI en el agente de usuario del dispositivo AuthN para iniciar la aplicación AuthN y, a continuación, escribe el código de referencia en esa aplicación. Si el dispositivo de flujo continuo es el mismo que el dispositivo AuthN, el regcode se puede pasar mediante programación al módulo AuthN.
- El módulo AuthN inicia la autenticación del usuario con la MVPD mostrando un selector de MVPD. Una vez que el usuario selecciona la MVPD, el módulo AuthN llama a authenticate con el regcode, que redirige el agente de usuario al IdP de MVPD. Cuando el usuario se autentica correctamente con la MVPD, el agente de usuario se redirige de nuevo a través del servicio Adobe Pass, donde la autenticación correcta se registra con el regcode y, a continuación, se redirige de nuevo al módulo AuthN.
- Si el dispositivo de streaming es diferente del dispositivo AuthN, este debe mostrar un mensaje de autenticación al usuario y los pasos para continuar (p. ej., "Success! Ahora puede volver a la consola de juegos para continuar […]"). Si el dispositivo de streaming es el mismo que el dispositivo AuthN, el dispositivo de streaming puede detectar mediante programación la finalización de la autenticación.
El diagrama siguiente ilustra el flujo de autenticación:
Autorización (authZ)
El flujo de autorización se utiliza para determinar si un usuario tiene derecho a acceder al contenido solicitado.
- Cada vez que el usuario intenta ver contenido protegido en la aplicación del Dispositivo de streaming, la aplicación del Dispositivo de streaming llama al Servicio de programador para identificar el contenido y solicitar el permiso y la información necesarios para iniciar el flujo.
- El servicio de programación llama a la API authorize de Adobe Pass y pasa el identificador de recurso junto con otros parámetros necesarios. El servicio de Adobe llama al servicio MVPD AuthZ con el ID de recurso y recibe una decisión de autorización que, a continuación, se devuelve al servicio de programador. El servicio de Adobe Pass almacenará en caché esta decisión de autorización durante un periodo configurable. En las llamadas subsiguientes authorize del servicio de programador al servicio de Adobe Pass, el valor almacenado en caché se devolverá siempre y cuando sea válido.
- Si se concede la autorización, el servicio de programación debe llamar a la API de Adobe Pass /tokens/media, que devolverá un token de medios firmado. El servicio de programación debe validar el token de medios mediante la biblioteca de comprobador de token de medios (JAR). Si es válido, el servicio de programador debe devolver el permiso y el permiso necesarios para iniciar la secuencia (por ejemplo, la URL de la secuencia) solicitada en el paso #1.
- Si se deniega la autorización, la llamada a authorize devolverá un código de error y una descripción al servicio de programador. El servicio de programación debe devolver el código de error y la descripción (o un mensaje modificado por el programador) a la solicitud en el paso #1.
El diagrama siguiente ilustra el flujo de autorización:
Cerrar sesión
El flujo de cierre de sesión permite al usuario eliminar la identidad actual
asociadas a la aplicación.
- Cuando el usuario solicita cerrar la sesión (es decir, quitar del dispositivo la cuenta de MVPD actual asociada con la aplicación), la aplicación de dispositivos de streaming llama al servicio de programación para indicarle que cierre la sesión del dispositivo.
- El servicio de programación debe llamar a la API de Adobe Pass logout.
El diagrama siguiente ilustra el flujo de cierre de sesión:
[Opcional] Autorización previa (también conocida como Pre-flight)
La preautorización se puede utilizar para determinar rápidamente, a partir de un conjunto de recursos, a qué recursos puede tener acceso un usuario. El resultado de esta llamada se utiliza generalmente para personalizar la interfaz de usuario de un usuario individual.
-
Una vez autenticado el usuario, el Dispositivo de streaming puede llamar al Servicio de programador para solicitar el contenido al que el usuario tiene derecho a transmitir.
-
El servicio de programación debe llamar a la API de Adobe Pass preauthorize con una lista de ID de recursos, que son una cadena simple que normalmente representa un canal al que un usuario podría tener derecho de flujo. Nota: actualmente, la llamada a preauthorize está configurada para limitar la lista a cinco (5) ID de recursos. Cuando se necesitan más de cinco recursos, se pueden realizar varias** llamadas preautorizadas , o bien se puede configurar la llamada para aceptar más de cinco recursos con un acuerdo de las MVPD. Los implementadores deben tener en cuenta el coste de una** llamada preautorizada para los recursos de MVPD, así como el tiempo de respuesta al programador y estructurar su uso de la llamada con prudencia.**
-
La llamada preauthorize responderá al servicio de programador con un objeto JSON que contiene un valor TRUE o FALSE para cada ID de recurso en la solicitud que indica si el usuario tiene derecho al canal asociado o no. Nota: Si una MVPD no proporciona una respuesta para un ID de recurso determinado (por ejemplo, debido a errores de red o tiempos de espera), el valor predeterminado será FALSO.
-
El servicio de programador debe usar la respuesta de llamada preauthorize para crear una respuesta personalizada definida por el programador al dispositivo de flujo, normalmente para personalizar la presentación al usuario en función de sus derechos.
El diagrama siguiente ilustra el flujo de preautorización:
[Opcional] Metadatos
Los metadatos se pueden utilizar para recuperar información de usuario compartida por MVPD.
Algunos ejemplos de esto son el ID de usuario, el código postal, etc.
-
Una vez autenticado el usuario, el servicio de programador puede llamar a la API de Adobe Pass usermetadata para solicitar información sobre el usuario autenticado.
-
La respuesta incluirá todos los metadatos disponibles para el usuario determinado. Los campos específicos se configuran por separado para cada integración de Programador/MVPD.
El diagrama siguiente ilustra el flujo de preautorización:
Entornos y requisitos funcionales environments
Un programador debe crear al menos dos entornos: uno para la producción y uno o más para el ensayo.
Producción
El entorno de producción debe tener una alta disponibilidad y escalarse adecuadamente para picos grandes o inesperados (por ejemplo, deportes en directo, roturas)
noticias).
El servicio Adobe Pass se ejecuta en varios centros de datos distribuidos geográficamente en todo Estados Unidos. Para lograr el mejor tiempo de respuesta (es decir, la menor latencia) desde el servicio de Adobe Pass, el Programador también debe crear un servicio similar disperso geográficamente
infraestructura.
El servicio Programador debe limitar la memoria caché DNS a un máximo de 30 segundos en caso de que el Adobe necesite redireccionar el tráfico. Esto puede ocurrir si un centro de datos deja de estar disponible.
El programador debe proporcionar el rango de IP pública del entorno de producción. Estas se incluirán en una lista de direcciones IP permitidas en la infraestructura de Adobe Pass para su acceso y se administrarán mediante las políticas de uso de API equitativas de Adobe.
Ensayo
El entorno de ensayo puede ser mínimo, pero debe incluir todos los componentes del sistema y la lógica empresarial. Debe funcionar de manera similar a la producción y permitir versiones de prueba fuera de la producción. Lo ideal es que el entorno de ensayo se pueda conectar a los entornos de prueba de Adobe Pass para que el programador lo use y, cuando sea necesario, mediante el Adobe, para que podamos ayudarle en las pruebas y la resolución de problemas.
Requisitos funcionales
El servicio Programador debe pasar información precisa de identificación del dispositivo para el que está ejecutando los flujos. Además, el servicio Programador debe pasar la IP del dispositivo para el que está ejecutando los flujos (en un encabezado x-forwarded-for) junto con el puerto de origen de la conexión (en el campo de información del dispositivo):
**X-Forwarded-For : \<client\_ip\>**
donde \<client\_ip\> es la dirección IP pública del cliente
Es necesario agregar el encabezado en **regcode** y **authorize** llamadas
Ejemplos :
POST /reggie/v1/{req\_id}/regcode HTTP/1.1
X-Forwarded-For:203.45.101.20
GET /api/v1/authorize/1 .1
X-Forwarded-For:203.45.101.20
El servicio Programador debe enviar los datos y el formato requeridos por las MVPD individuales o aplicaciones integradas (por ejemplo, IP del dispositivo, puerto de origen, información del dispositivo, MRSS, datos opcionales como ECID). .
El servicio Programador debe respetar los TTL authN y authZ al almacenar en caché e invalidar las sesiones authN o authZ cuando se le notifique.
El programador debe mantener los certificados compartidos con el Adobe.