Por Mark Tse
¿Qué es OAuth 2.0?
OAuth 2.0 es un marco de autenticación de estándar abierto que proporciona múltiples flujos de autenticación, incluido el Flujo OAuth de tres patas que ahora es compatible con Brightspace. Permite a los desarrolladores escribir aplicaciones que acceden a diferentes servicios en nombre de un usuario.
Público objetivo
Esta publicación está dirigida a desarrolladores que buscan escribir aplicaciones que utilicen las API de Brightspace. Ahora admitimos la especificación OAuth 2.0 para la autenticación de tres patas, además de nuestra especificación de autorización de clave de ID existente.
Hay más información disponible a través de nuestra publicación de blog de preguntas y respuestas de OAuth 2.0, que incluye información sobre lo que esto significa para la autorización de claves de ID y las diferencias entre las dos.
Empezar
El objetivo de OAuth de tres patas para desarrolladores es obtener un Token de acceso que permite a una aplicación de terceros acceder a los recursos de un usuario (por ejemplo, calificaciones a través de nuestras API de aplicaciones) en nombre del usuario.
Entidades
Hay Cuatro entidades involucrados en OAuth de tres patas:
- Apis
- Por ejemplo, nuestras API de aplicaciones o datos
- También conocido como el Servidor de recursos en las especificaciones oficiales
- Aplicación
- Una aplicación de terceros que utiliza nuestras API
- También conocido como el cliente en las especificaciones oficiales
- Servidor de autorización
- Provisiones de tokens de acceso, entre otras responsabilidades
- El servidor de autorización de Brightspace está alojado en auth.brightspace.com
- Usuario
- Por ejemplo, un estudiante o instructor
- También conocido como el Propietario del recurso en las especificaciones oficiales
Registro de una aplicación
- Como administrador del sistema, navegue hasta la Administrar la extensibilidad Herramienta de administración.
- Haga clic en el botón OAuth 2.0 pestaña.
- Haga clic en el botón Registrar una aplicación botón.
- Registre la aplicación de ejemplo. Para este ejemplo, utilice los siguientes valores:
Después de registrarse, se le presentará un ID de cliente y un Secreto de cliente, que necesitará para la siguiente sección.
Más información sobre el registro de aplicaciones está disponible en la sección OAuth 2.0 de nuestra Referencia de la API Documentación.
Tutorial de ejemplo de código
Hemos creado un archivo Ejemplo de aplicación Usando Expresar para ayudar a los desarrolladores a aprovechar OAuth 2.0. Esta aplicación iniciará el flujo de OAuth de tres patas para obtener un token de acceso para un usuario determinado y, a continuación, llamará a la función API de whoami usando ese token.
El usuario realizará varias solicitudes web a la aplicación durante el flujo, y la aplicación define una ruta para cada una de esas solicitudes. El siguiente tutorial recorrerá cada ruta en el orden en que el usuario las encontrará.
1. El usuario visita la página de aterrizaje de la aplicación, que contiene un botón Obtener datos:
app.get('/', function(req, res) {
devuelve una página HTML con un botón "Obtener datos"
res.render('índice');
});
2. El botón Obtener datos llama a la ruta /auth que hace que la aplicación realice una solicitud de autorización. Para ello, la aplicación crea el URI de la solicitud (un punto de conexión en nuestro servidor de autorización) y redirige al usuario a ese URI:
app.get('/auth', function(req, res) {
var authCodeParams = querystring.stringify({
response_type: "código",
redirect_uri: getRedirectUri(req),
client_id: process.env.CLIENT_ID,
Alcance: "Núcleo:*:*",
Estado: "NotASecureState_rfc6749_section_10.12"
});
res.redirect(authCodeEndpoint + "?" + authCodeParams);
});
3. Se le pedirá al usuario que inicie sesión con sus credenciales de Brightspace (si aún no lo ha hecho). Tras un inicio de sesión exitoso, se presentará al usuario una página donde puede confirmar si permite que la aplicación actúe en su nombre. Este paso forma parte de la Solicitud de autorización, pero no implica la aplicación.
4. El servicio de autorización proporciona una Respuesta de autorización a la aplicación redirigiendo al usuario de vuelta a la aplicación. Esto se basa en la URI de redireccionamiento valor proporcionado durante el registro de la solicitud.
Echemos un vistazo a cada componente de esta definición de ruta por separado:
un. Esto registra la ruta de devolución de llamada a la que el servidor de autorización redirigirá al usuario:
app.get('/callback', function(req, res) { ... }
b. Con el código de autorización de la respuesta de autorización, así como las credenciales de la aplicación, la aplicación realiza una solicitud de token de acceso:
var authorizationCode = req.query.code;
var carga útil = {
grant_type: "authorization_code",
redirect_uri: getRedirectUri(req),
código: authorizationCode};
pedir
.post(tokenEndpoint)
.auth(process.env.CLIENT_ID, process.env.CLIENT_SECRET)
.type('formulario')
.send(carga útil)
.end( ... )
c. Importante: aunque no se muestre, la aplicación también debe comprobar el estado para asegurarnos de que tiene el mismo valor que enviamos al servidor de autorización. Esto asegura que el /Callback El punto de conexión no procesa los códigos de autorización que no fueron solicitados por la aplicación. Por esta razón, el estado El valor enviado al servidor de autorización en la solicitud de autorización debe ser un valor que no se pueda adivinar.
d. La respuesta del token de acceso contendrá un token de acceso que permite a la aplicación llamar a las API en nombre del usuario. Almacenamos este valor en una cookie para simplificar, de modo que podamos realizar una llamada a la API en el siguiente paso:
function(err, postResponse) {
if (err) {
console.log(
'Error de token de acceso',
err.respuesta || errar
);
res.redirect('/');
} else {
res.cookie(
cookieName,
{ accessToken: postResponse.body.access_token },
cookieOptions
);
res.redirect('/datos');
}});
e. Poniéndolo todo junto:
app.get('/callback', function(req, res) {
var authorizationCode = req.query.code;
var carga útil = {
grant_type: "authorization_code",
redirect_uri: getRedirectUri(req),
código: authorizationCode
};
pedir
.post(tokenEndpoint)
.auth(process.env.CLIENT_ID, process.env.CLIENT_SECRET)
.type('formulario')
.send(carga útil)
.end(function(err, postResponse) {
if (err) {
console.log(
'Error de token de acceso',
err.respuesta || errar
);
res.redirect('/');
} else {
res.cookie(
cookieName,
{ accessToken: postResponse.body.access_token },
cookieOptions
);
res.redirect('/datos');
}
});
});
5. La aplicación utiliza el token de acceso para llamar a las API en nombre del usuario:
app.get('/data', function(req, res) {
var access_token = req.cookies[cookieName].accessToken;
pedir
.get(process.env.HOST_URL + '/d2l/api/lp/1.10/users/whoami')
.set('Autorización', 'Portador ${access_token}')
.end(función(error, respuesta) {
if (error) {
var errorMessage = JSON.stringify(error, null, 2);
console.log(errorMessage);
res.send('${errorMessage}');
} else {
var locales = {
datos: JSON.stringify(
JSON.parse(respuesta.texto || '{}'),
nulo
2
)
};
res.render('datos', locales);
}
});
});
