Par Mark Tse
Qu’est-ce que OAuth 2.0 ?
OAuth 2.0 est un framework d’authentification standard ouvert qui fournit plusieurs flux d’authentification, y compris le écoulement OAuth à trois pattes qui est maintenant pris en charge par Brightspace. Il permet aux développeurs d’écrire des applications qui accèdent à différents services au nom d’un utilisateur.
Public cible
Cet article s’adresse aux développeurs qui cherchent à écrire des applications qui utilisent des API Brightspace. Nous prenons désormais en charge la spécification OAuth 2.0 pour l’authentification à trois pattes en plus de notre spécification d’autorisation de clé d’ID existante.
Plus d’informations sont disponibles via notre article de blog OAuth 2.0 Q&A, y compris des informations sur ce que cela signifie pour l’autorisation de clé d’identification et les différences entre les deux.
Mise en route
L’objectif de OAuth à trois pattes pour les développeurs est d’obtenir un jeton d’accès qui permet à une application tierce d’accéder à la ressource d’un utilisateur (par exemple, les notes via nos API d’application) au nom de l’utilisateur.
Entités
Il y a quatre entités impliqué dans OAuth à trois pattes :
- API
- Par exemple, nos API d’application ou de données
- Aussi connu sous le nom de serveur de ressources dans les spécifications officielles
- Demande d’admission
- Une application tierce qui utilise nos API
- Aussi connu sous le nom de client dans les spécifications officielles
- Serveur d’autorisation
- Les dispositions accèdent aux jetons d’accès entre autres responsabilités
- Le serveur d’autorisation de Brightspace est hébergé sur auth.brightspace.com
- Utilisateur
- Par exemple, un étudiant ou un instructeur
- Aussi connu sous le nom de propriétaire de la ressource dans les spécifications officielles
Enregistrement d’une demande
- En tant qu’administrateur système, accédez à l' Gérer l’extensibilité outil d’administration.
- Cliquez sur le bouton OAuth 2.0 onglet.
- Cliquez sur le bouton Enregistrer une application bouton.
- Enregistrez l’exemple d’application. Pour cet exemple, utilisez les valeurs suivantes :
Après l’inscription, vous serez présenté avec un Client ID et un Client Secret, dont vous aurez besoin pour la section suivante.
Plus d’informations sur l’enregistrement de la demande sont disponibles dans la section OAuth 2.0 de notre Référence de l’API Documentation.
Exemple de code Procédure pas à pas
Nous avons créé un exemple d’application utilisation Express pour aider les développeurs à tirer parti d’OAuth 2.0. Cette application lancera le flux OAuth à trois pattes pour obtenir un jeton d’accès pour un utilisateur donné, puis appellera le API whoami en utilisant ce jeton.
L’utilisateur fera plusieurs demandes Web à l’application pendant le flux, et l’application définit un itinéraire pour chacune de ces demandes. La procédure pas à pas suivante passera par chaque itinéraire dans l’ordre dans lequel l’utilisateur les rencontrera.
1. L’utilisateur visite la page de destination de l’application, qui contient un bouton Obtenir des données :
app.get('/', function(req, res) {
renvoie une page HTML avec un bouton « Obtenir des données »
res.render('index') ;
});
2. Le bouton Obtenir des données appelle la route /auth qui provoque l’application d’effectuer une demande d’autorisation. L’application le fait en créant l’URI de demande (un point de terminaison sur notre serveur d’autorisation) et en redirigeant l’utilisateur vers cet URI :
app.get('/auth', function(req, res) {
var authCodeParams = querystring.stringify({
response_type : « code »,
redirect_uri : getRedirectUri(req),
client_id : process.env.CLIENT_ID,
portée : « core 
:* »,
État : « NotASecureState_rfc6749_section_10.12 »
});
res.redirect(authCodeEndpoint + « ? » + authCodeParams) ;
});
3. L’utilisateur sera invité à se connecter à l’aide de ses informations d’identification Brightspace (s’il n’est pas déjà connecté). Lors d’une connexion réussie, l’utilisateur se verra présenter une page où il pourra confirmer s’il autorise l’application à agir en son nom. Cette étape fait partie de l' demande d’autorisation, mais n’implique pas la demande.
4. Le service d’autorisation fournit un réponse d’autorisation à l’application en redirigeant l’utilisateur vers l’application. Ceci est basé sur l' Rediriger l’URI valeur fournie lors de l’enregistrement de la demande.
Regardons chaque composant de cette définition d’itinéraire séparément :
un. Ceci enregistre l’artère de rappel que le serveur d’autorisation redirigera l’utilisateur à :
app.get('/callback', function(req, res) { ... }
b. À l’aide du code d’autorisation de la réponse d’autorisation, ainsi que des informations d’identification de l’application, l’application effectue une demande de jeton d’accès :
var authorizationCode = req.query.code ;
charge utile var = {
grant_type : « authorization_code »,
redirect_uri : getRedirectUri(req),
code : authorizationCode} ;
demande
.post(tokenEndpoint)
.auth(process.env.CLIENT_ID, process.env.CLIENT_SECRET)
.type('form')
.send(charge utile)
.end( ... )
c. Important: bien qu’elle ne soit pas présentée, l’application doit également vérifier le état pour s’assurer qu’il a la même valeur que nous avons envoyée au serveur d’autorisation. Cela garantit que l' /rappel endpoint ne traite pas les codes d’autorisation qui n’ont pas été demandés par l’application. Pour cette raison, l' état la valeur envoyée au serveur d’autorisation dans la demande d’autorisation doit être une valeur non devinable.
d. La réponse du jeton d’accès contiendra un jeton d’accès qui permet à l’application d’appeler des API au nom de l’utilisateur. Nous stockons cette valeur dans un cookie pour plus de simplicité afin que nous puissions passer un appel API à l’étape suivante :
function(err, postResponse) {
if (err) {
console.log(
'Erreur de jeton d’accès',
err.response || err
);
res.redirect('/') ;
} else {
res.cookie(
cookieName,
{ accessToken : postResponse.body.access_token },
cookieOptions
);
res.redirect('/data') ;
}});
e. Mettre tout cela ensemble :
app.get('/callback', function(req, res) {
var authorizationCode = req.query.code ;
charge utile var = {
grant_type : « authorization_code »,
redirect_uri : getRedirectUri(req),
code : authorizationCode
};
demande
.post(tokenEndpoint)
.auth(process.env.CLIENT_ID, process.env.CLIENT_SECRET)
.type('form')
.send(charge utile)
.end(function(err, postResponse) {
if (err) {
console.log(
'Erreur de jeton d’accès',
err.response || err
);
res.redirect('/') ;
} else {
res.cookie(
cookieName,
{ accessToken : postResponse.body.access_token },
cookieOptions
);
res.redirect('/data') ;
}
});
});
5. L’application utilise le jeton d’accès pour appeler des API au nom de l’utilisateur :
app.get('/data', function(req, res) {
var access_token = req.cookies[cookieName].accessToken ;
demande
.get(process.env.HOST_URL + '/d2l/api/lp/1.10/users/whoami')
.set('Autorisation', 'Porteur ${access_token}')
.end(function(error, response) {
if (error) {
var errorMessage = JSON.stringify(error, null, 2) ;
console.log(errorMessage) ;
res.send('${errorMessage}') ;
} else {
var locals = {
données : JSON.stringify(
JSON.parse(response.text || '{}'),
null,
2
)
};
res.render('data', locals) ;
}
});
});
