¿Qué es una aplicación conectada para insignias digitales de Parchment?
Una aplicación conectada a Parchment Digital Badges es cualquier servicio web que utiliza Open Badges como emisor o visualizador. Si desea incorporar logros verificables a su ecosistema, conéctese a la API de Parchment Digital Badges para simplificar el proceso.
Aplicaciones del emisor
Las aplicaciones emisoras reaccionan a los eventos de su propio dominio para otorgar nuevas insignias a los usuarios.
Aplicaciones de visualización
Las aplicaciones de visualización ayudan a los usuarios a presumir y sacar provecho de las insignias que han ganado.
Conectando con las insignias digitales de Parchment
Acceso a la API mediante concesión de códigos de autorización OAuth2
Parchment Digital Badges ofrece funcionalidades de proveedor de identidad OAuth2, servidor de autorización y servidor de recursos para que tu aplicación conectada obtenga de forma segura un token API específico del usuario y acceda a sus insignias. Puedes añadir un botón de "Conectar con Parchment Digital Badges" o "Iniciar sesión con Parchment Digital Badges" a tu servicio. Existen varios servidores de Parchment Digital Badges distribuidos por todo el mundo, y tu aplicación puede conectarse a cada región por separado. Para firmar las solicitudes OAuth a un servidor específico de Parchment Digital Badges, tu servicio debe establecer una clave secreta compartida con el administrador de dicho servidor.
Puedes crear aplicaciones que se conecten con Parchment Digital Badges. Ponte en contacto con Parchment Digital Badges para solicitar una clave y un secreto de aplicación para firmar tus solicitudes OAuth. Describe qué planeas crear y qué tipo de información necesitas de los usuarios de Parchment Digital Badges.
Solicitud de acceso a la API de insignias digitales de Parchment
Para cada región de disponibilidad del servicio Parchment Digital Badges, al solicitar una clave de desarrollador, se creará un registro de aplicación con una clave y un secreto. Al solicitar una clave, asegúrese de describir la región que desea utilizar (Entorno de pruebas, Australia, Canadá, UE/Irlanda, Singapur o EE. UU.). Estos servidores regionales también tienen su propio dominio de interfaz de usuario y API , así que asegúrese de usar el dominio correcto según el servidor que esté utilizando. En nuestra documentación, usamos el servidor de producción de EE. UU. como predeterminado. La posibilidad de obtener automáticamente una clave y un secreto para ciertos tipos de aplicaciones también está disponible a través del protocolo Badge Connect (Open Badges 2.1) . Estos ámbitos permiten que su aplicación acceda a la mochila de un usuario para leer sus insignias o enviarle nuevas insignias.
Alcances de los permisos
Las aplicaciones emisoras y de visualización necesitan una combinación de permisos para los puntos finales de la API del emisor y del receptor (package). Esto se logra solicitando un conjunto de ámbitos de permisos al registrar su aplicación con el administrador del servidor de Parchment Digital Badges. Estos ámbitos, o un subconjunto de ellos, estarán disponibles cuando solicite autorización en nombre de un usuario de su aplicación.
Alcance del perfil (automático)
- r:profile Esto permite obtener información sobre el usuario que ha definido en Parchment Digital Badges, incluyendo su nombre, apellido y direcciones de correo electrónico registradas. Este ámbito está disponible automáticamente. Permite acceder al punto final GET /v2/user/profile .
Alcances del emisor
- r:issuer Esto le permite obtener información sobre los perfiles de emisores donde el usuario autenticado actúa como miembro del personal, editor o propietario. Puede ver los metadatos del emisor, las insignias definidas por estos emisores y los premios de insignias otorgados por estos emisores.
- rw:issuer Esto permite el acceso de lectura/escritura a los recursos mencionados anteriormente, en la medida en que el usuario autenticado pueda realizar estas acciones. Los usuarios de nivel "Personal" pueden leer todos los datos y otorgar nuevas instancias de insignias definidas; los usuarios de nivel "Editor" también pueden definir nuevas BadgeClasses y editar las existentes. Los miembros "Propietario" pueden modificar la lista de personal.
Telescopios de mochila
- r:backpack Permite leer las aserciones que el usuario ha recibido de los emisores en este servidor de insignias digitales Parchment o importadas a su mochila desde emisores externos de insignias abiertas.
- rw:backpack Permite leer, crear y actualizar aserciones y colecciones de aserciones. En el caso de las aserciones, esto significa que se puede activar la importación de una aserción de Open Badges definida en otro lugar, enviándola a la mochila del destinatario.
El proceso de OAuth2 (flujo de trabajo para la concesión de códigos de autorización)
Una vez que nos hayas enviado por correo electrónico tus URI de alcance y redireccionamiento y te hayamos respondido con un client_id y un client_secret , podemos continuar. Supongamos que una usuaria de Parchment Digital Badges desea otorgarte acceso a sus insignias, emisores e información de perfil. Primero, crea un botón de "Iniciar sesión con Parchment Digital Badges" en tu sitio web que enlace a la siguiente URI (se agregaron saltos de línea para facilitar la lectura):
https://badgr.com/auth/oauth2/authorize?
client_id=123&redirect_uri=https%3A%2F%2Fexample.com%2Fauth&scope=r%3Aprofile%20rw%3Aissuer%20r%3Abackpack
Establezca client_id con el ID de cliente que recibió del equipo de Parchment Digital Badges. Establezca redirect_uri con la URI de redireccionamiento de su aplicación (codifique esta y todas las demás para que sean URL válidas). Usamos esto para redirigir al usuario de vuelta a su sitio web con un código de autorización después de que haya iniciado sesión y le haya otorgado acceso. Establezca scope con el nivel de acceso que solicita.
Después de que Parchment Digital Badges redirija al usuario de vuelta a su aplicación con el código de autorización en el parámetro de consulta code, su aplicación deberá intercambiar ese código temporal por un token de acceso de larga duración mediante una solicitud POST. Aquí hay un ejemplo usando curl :
curl https://api.badgr.io/o/token -d \
"grant_type=authorization_code\
&code=XYZ\
&client_id=123\
&client_secret=ABC\
&redirect_uri=https://example.com/auth"
Nota : Puede pasar un parámetro de estado, que debe ser una cadena codificada en URL segura. Por ejemplo, puede codificar un pequeño fragmento de JSON. Este parámetro se le devolverá en su URL de redireccionamiento.
Intercambia este código de autorización por un token de acceso.
curl https://api.badgr.io/o/token \
-d "grant_type=authorization_code&code=authorization_code"
¡Y eso es todo! Ya terminaste. Recibirás un documento como este:
{
"token_type": "Bearer",
"access_token": "C1HePsbwS3tUmwC6OCKsC41w96xckc",
"expires_in": 86400,
"refresh_token": "xwHPFwH55tQpCy3qCgsIW59k3g3aPh",
"scope": "rw:issuer rw:profile rw:backpack"
}
¡Y listo! Puedes almacenar el token de acceso en tu aplicación. Ahora puedes usar el access_token obtenido en esta solicitud para autenticar las solicitudes a la API. Consulta la sección «Uso de la API de insignias digitales de Parchment» a continuación.
Aquí se muestra un diagrama que ilustra el flujo de autorización inicial:
Tu token de acceso caducará (por defecto, 24 horas después de su emisión). En ese momento, puedes actualizarlo usando el token de actualización incluido. Los tokens de actualización tienen una larga duración y deben almacenarse de forma segura. Los tokens de acceso también deben almacenarse de forma segura, pero presentan un menor riesgo debido a su menor duración. Puedes obtener un nuevo token de acceso usando tu token de actualización realizando una nueva solicitud POST al punto final de autorización.
curl https://api.badgr.io/o/token -X POST -d \
"grant_type=refresh_token&refresh_token=YOURREFRESHTOKEN&client_id=YOURCLIENTID&client_secret=YOURCLIENTSECRET"
Recibirás un nuevo documento de token, que incluye un nuevo access_token y un refresh_token . El nuevo token de acceso será válido durante el número de segundos especificado.
Nota: Si nos ha proporcionado una URI de redirección localhost, recuerde utilizar los puntos finales de nuestro entorno de pruebas (sandbox). Utilice https://test.badgr.com/auth/oauth2/authorize y https://api.test.badgr.com/o/token . Para obtener información más detallada sobre OAuth2, consulte la RFC 6749 : https://tools.ietf.org/html/rfc6749 . En entornos de producción, se requiere HTTPS para las URI de redirección y no se permiten dominios de túnel localhost ni de máquinas de desarrollo.
Uso de la API de insignias digitales de Parchment
Inicio rápido: Consulte la documentación de la API de insignias digitales de Parchment.
Para autenticar una solicitud mediante un token OAuth, utilice el encabezado Authorization con el valor Bearer , un espacio y, a continuación, el token que ha obtenido. Por ejemplo : Authorization: Bearer cZTp1ZMMSasZ4mbP2u2Pjt4NH3AVIf
Las solicitudes a la API /v2/ se devuelven por defecto en formato JSON con un sobre de respuesta predeterminado. Si la solicitud es exitosa, la clave de resultado contendrá una lista de objetos de resultado [], y cada resultado aparecerá como una sola entrada dentro de este array JSON. Para probar el flujo de OAuth y realizar solicitudes, cree una cuenta gratuita y haga clic en el botón Autorizar en la documentación de la API .
