Antes de empezar
Necesitas tener esta información:
- El par de claves de identificación de la aplicación (digamos 'appID' y 'appKey', pero no se verán así)
- El dominio de su servicio de back-end (al LMS al que llama)
- El punto de devolución de llamada para su aplicación/servicio donde el LMS puede Enviar Pares de clave de ID de usuario cuando los solicite
Creación de la cuenta de servicio y recolección de tokens de usuario
La aplicación deberá ejecutarse con una cuenta de servicio u otra cuenta con privilegios suficientes para realizar las acciones que debe realizar con las API. Por lo tanto, el primer paso es crear una cuenta en el entorno de aprendizaje con suficientes privilegios para realizar las llamadas a la API que necesita realizar.
Una vez que creas una cuenta de servicio:
- Debe recolectar manualmente los tokens de usuario utilizando una utilidad como la API Test Tool () para autenticarse con su LMS.
- Almacene esas claves de forma segura y configure su LMS para garantizar que los tokens de usuario sean de larga duración. Muchos sistemas tienen un tiempo de espera de token de 30 días, pero cuando existe una integración sin encabezado como la que está proponiendo, a menudo es una buena idea hacer que el tiempo de espera sea infinito. Puede ponerse en contacto con el soporte de Desire2Learn para verificar el valor de tiempo de espera de los tokens de usuario.
Nota: los "tokens de usuario" anteriores no significan el tiempo de espera establecido a través del d2l. Configuración del servidor SessionTimeout. Más bien, esto se establece a través del d2l. Security.Api.TokenTimeout.
Para aclarar más:
- El d2l. La variable de configuración SessionTimeout hace referencia al período de tiempo de espera de la sesión web (es decir, cuánto tiempo puede estar inactivo antes de que se agote el tiempo de espera de la interfaz de usuario web de LMS y solicite al usuario que vuelva a iniciar sesión). Este tiempo de espera a menudo se establece en un intervalo de varios minutos a una hora.
- El d2l. La variable de configuración Security.Api.TokenTimeout hace referencia al período de tiempo de espera del par de identificación/clave de usuario asociado con el proceso de autenticación de valencia. Dicho de otra manera, estos tokens son el valor x_b y la base del valor x_d que se envían como parámetros de consulta en cada llamada a la API para identificar al usuario. Este tiempo de espera a menudo se establece en un intervalo de varios días, o se puede establecer para que nunca se agote el tiempo de espera. En este último caso, el par id-key de usuario solo se puede invalidar cambiando la contraseña del usuario o revocando explícitamente el acceso a la aplicación. Una vez que el par de ID de usuario y clave deje de ser válido, la aplicación tendrá que reiniciar el proceso de autenticación para recibir un nuevo par de ID de usuario y clave para firmar las llamadas a la API.
Creación de un contexto de aplicación
- Construya un contexto de aplicación con D2LAppContext( "appID", "appKey", ""); esto crea un contexto de aplicación que luego puede usar para realizar la solicitud para obtener un par de clave de identificación de usuario del LMS
- authURL = DAC.createWebUrlForAuthentication( new URI("")); esto hace que el "authURL", debe dirigir un contenedor web (el navegador del usuario) a esta URL: que solicita el envío de LMS al par de claves de identificación de usuario para la sesión de usuario que se establecerá dentro del contenedor web solicitante.
El LMS enviará el par de clave de identificación de usuario mediante el redireccionamiento Volver a con el par de clave de identificación de usuario adjunto como parámetros de consulta en la URL de redireccionamiento. Llamemos a esto lleno URL de redireccionamiento 'fullRedirectUrl'.
Creación de un contexto de usuario
- Puedes cualquiera de los dos Cree un contexto de usuario mediante el uso de fullRedirectUrl: DAC.createUserContext( fullRedirectUrl )
- O, puede extraer el par de clave de identificador de usuario de fullRedirectUrl (digamos 'userID' y 'userKey', pero se verán diferentes) y usar: DAC.createUserContext( "userID", "userKey" )
Hacer llamadas
- Ahora puede usar su contexto de usuario, DUC, para realizar llamadas: DUC.createAuthenticatedUri( "/d2l/api/lp/1.3/users/whoami", "GET")
Nota: que aquí proporciona solo la ruta de la API, más el método HTTP (mayúsculas); asegúrese de usar una ruta en un contrato de API que admita su LMS de back-end: aquí hacemos la llamada whoami desde el contrato de API v1.3, pero es posible que su LMS no admita ese contrato (o puede que admita uno más reciente).
Solución de problemas
Pregunta: Para ser claros, estoy tomando el "... o" mencionada anteriormente, extrayendo los valores de userID y userKey de apitesttool. desire2learnvalence.comy, a continuación, realizar createUserContext con esos valores (junto con el nombre de host D2L, el puerto, etc. --- la versión de 6 parámetros de esa función).
Obtengo un contexto de ese método y cuando lo uso para hacer una llamada a la API, el servicio devuelve un 403 "Token no válido".
Respuesta: Si su aplicación no fuera conocida por el LMS (es decir, no fuera un ID de aplicación habilitado), obtendría un error ligeramente diferente. Esto nos dice que cualquiera de los dos no estás creando una firma de aplicación válida en tu eventual llamada a la API (lo que probablemente signifique que tu clave de aplicación no es adecuada para tu ID de aplicación), o la clave de identificación de usuario que está utilizando de alguna manera no es útil.
Le recomendamos encarecidamente que recorra el recorrido por el Documentos del SDK de cliente de Python incluso si no tiene la intención de usar Python a largo plazo. Puede pasar por este proceso de forma interactiva y paso a paso, y así tener un control más directo sobre lo que está sucediendo en cada paso del proceso para ver lo que está sucediendo. Con una aplicación empresarial creada a partir de C# o Java, se recurre a técnicas de depuración estándar para recorrer el flujo de trabajo, que también funcionan bien: sin embargo, un shell interactivo te permite ejecutar cada paso a medida que avanzas e inspeccionar los resultados.
Para empezar a usar el SDK de Python como en ese tutorial, necesita:
- Para tener una instalación de Python, y ayuda tener instalado el paquete 'pip' para hacer la instalación del módulo de Python
- Para tener instalado el módulo python 'requests' (que pip debería encontrar automáticamente)
- Para tener instalado el módulo de python 'd2lvalence' (que pip debería encontrar automáticamente)
Pregunta: Fui a mirar la página de autenticación de Python a la que hiciste referencia, pero estoy confundido. Esa página me aconseja ir al navegador y capturar la URL de redireccionamiento después de obtener el resultado de createUrlForAuthentication (usando el formato php para la función).
Respuesta:
La forma en que el modelo funciona a un alto nivel es como un modelo de autenticación de tres patas:
- Tienes un usuario real con un navegador
- Tiene un servicio o aplicación de terceros que el usuario puede visitar (normalmente) y que desea realizar llamadas a la API de Valence en nombre de ese usuario
- Tienes el LMS de back-end
Cuando el usuario real visita la aplicación de terceros, antes de que pueda realizar llamadas a la API, debe solicitar al LMS un par de claves de identificación de usuario para que vaya con su par de claves de identificación de la aplicación para que pueda realizar llamadas a la API en nombre del usuario. Para ello, redirige el navegador del usuario a la "ruta de inicio de sesión" del LMS para garantizar que el LMS "sepa" quién es el usuario/navegador:
- Si el navegador del usuario ya tiene una sesión web con LMS, entonces el LMS puede decir "Sé quién es el usuario" y enviar el par de clave de identificación de usuario correcto a la aplicación de terceros.
- Si el navegador del usuario aún no tiene una sesión, el LMS puede tratar de autenticar al usuario utilizando la forma estándar para ese LMS; LUEGO, puede enviar el par de clave de identificación de usuario correcto de vuelta a la aplicación de tercera parte (tenga en cuenta que, en ambos casos, el par de clave de identificación de usuario se genera específicamente para ESE usuario y ESA aplicación: no es transferible a ningún otro par de clave de identificación de aplicación).
Este sistema de autenticación de tres patas tiene sentido en el caso de que realmente tenga tres partes separadas. En casos como el suyo, en el que desea escribir una aplicación de servicio de TI (sin encabezado) que no tenga un "usuario operativo actualmente con su navegador web" real, normalmente le recomendamos que cree una cuenta de servicio, un propósito especial, un "usuario" y un "rol" que solo se use para su aplicación de servicio.
En este caso, debe tener una forma de pasar por el proceso de autenticación anterior cada vez que necesite un par de clave de identificación de usuario válido para este "usuario" del servicio. Hay un montón de formas de hacerlo, pero todas implican que (en algún momento) un usuario real con un navegador real se ponga de pie y desempeñe el papel de esa tercera pata en el proceso de autenticación.
Por lo general, lo que hace es usar una versión alojada localmente de uno de nuestros ejemplos simples o nuestra "Herramienta de prueba de API" en línea (https://apitesttool. desire2learnvalence.com/), o una sesión interactiva de Python con nuestro SDK de Python (como en el tutorial de autenticación que señalé). Por lo general, para obtener la mejor seguridad, le recomendamos que realice este proceso dentro de un entorno seguro, por lo que la herramienta de prueba de API quizás no sea la mejor solución, especialmente si no se va a conectar con HTTPS, porque se encuentra en Internet. Sin embargo, si usas HTTPS para conectarlo a tu LMS, probablemente sea lo suficientemente seguro.
Para el proceso de "recopilación de un par de clave de identificación de usuario", debe usar sus propias credenciales de clave de identificación de aplicación (es decir, el par que ha recibido para la aplicación / servicio que está escribiendo).
Si lo haces de forma interactiva, crea un contexto de aplicación con esas credenciales. Si está utilizando una muestra o la herramienta en línea, proporcione su propio par de claves de identificación de aplicación como las que se usarán (no las predeterminadas en el formulario: son un solo conjunto de claves públicas con fines de demostración). Debe proporcionar el nombre de host de su LMS y el puerto al que llamar. A continuación, se pasa por el "proceso de autenticación":
- Si está utilizando una sesión interactiva con el SDK de Python, cree una "URL de autenticación" que cortará y pegará en su navegador... para hacer esto, también debe proporcionar una "URL de devolución de llamada" que le indique al LMS dónde enviar la clave de identificación de usuario: sugerimos localhost porque eso volverá a la computadora donde se encuentra su navegador, y probablemente su navegador se quejará de que no puede encontrar la URL, pero luego puede copiar la URL completa de la barra de direcciones.
- Si está utilizando la herramienta de muestra o en línea, la "URL de devolución de llamada" está oculta para usted: el formulario la proporciona automáticamente: el par de ID de usuario y clave se enviará de vuelta al servidor web que ejecuta la herramienta de muestra / en línea.
Al devolver el par de ID de usuario y clave, el LMS los pondrá como parámetros de consulta en esa "URL de devolución de llamada" que proporcionó en la solicitud que acaba de enviar.
- Si está utilizando la herramienta en línea o una muestra, la herramienta/muestra debe descomponer automáticamente esta URL de devolución de llamada, extraer las credenciales y mostrárselas.
- Si está utilizando una sesión interactiva de Python, el LMS redirigirá a "localhost" y agregará el par de clave de identificación de usuario en los parámetros de consulta. Copie la URL completa de la barra de direcciones del navegador y devuélvala a su sesión de Python para crear el "contexto de usuario": esto despegará las claves de identificación de usuario de ese URI de resultado y creará un contexto de usuario para usted que puede usar para realizar llamadas API de manera interactiva ... también puede inspeccionarlo para ver cuál es el par de clave de ID de usuario, guardarlos en el disco, etc.
En cualquier caso, no has "reunido con éxito un par de claves de identificación de usuario" para que TU cuenta de servicio vaya con TU clave de identificación de aplicación. Puede almacenarlo en caché en un lugar seguro al que pueda acceder su script/aplicación de administrador (como en un archivo de configuración). Te recomendamos encarecidamente que trates el par de claves de identificación de la aplicación de tu aplicación y todas las claves de identificación de usuario que la acompañan como información altamente confidencial: con esos tokens, CUALQUIERA puede hacer una llamada a tu LMS haciéndose pasar por tu aplicación como un usuario válido, por lo que debes colocarlos en un lugar seguro visible solo para un pequeño número de personas y para el script/aplicación que necesita usarlos.
Cada vez que cambie la contraseña de esta cuenta de servicio, deberá volver a pasar por este proceso para recopilar un nuevo par de ID de usuario y clave. Si tu LMS tiene tokens de API configurados para caducar en un tiempo fijo, también tendrás que volver a hacer este proceso cuando transcurra ese tiempo. De forma predeterminada, los LMS tienen este tiempo de caducidad establecido en "indefinido" y los tokens de clave de identificación de usuario caducan solo cuando cambia la contraseña del usuario o cuando el administrador del sitio deniega el acceso a aplicaciones de terceros para ese usuario.
Para otro punto de explicación, puedes ver este tema en nuestro blog para desarrolladores: Introducción a la autenticación de clave de ID de aplicación. Tiene varios años, pero el material sigue siendo válido y los diagramas son diferentes a los que aparecen en nuestros documentos en línea, por lo que el contraste puede ayudar a obtener una imagen más redonda.https://d2l.someUniversity.eduhttps://yourServer.org/authCallback
https://apitesttool.desire2learnvalence.com/
https://d2l.someUniversity.eduhttps://yourServer.org/authCallbackhttps://yourServer.org/authCallback