Door Mark Tse
Wat is OAuth 2.0?
OAuth 2.0 is een open standaard authenticatieframework dat meerdere authenticatiestromen biedt, waaronder de driepotige OAuth-stroom die wordt nu ondersteund door Brightspace. Het stelt ontwikkelaars in staat om namens een gebruiker applicaties te schrijven die toegang hebben tot verschillende services.
Doelgroep
Dit bericht is bedoeld voor ontwikkelaars die applicaties willen schrijven die gebruikmaken van Brightspace-API's. We ondersteunen nu de OAuth 2.0-specificatie voor driepotige authenticatie naast onze bestaande ID-key-autorisatiespecificatie.
Meer informatie is beschikbaar via onze OAuth 2.0 Q&A-blogpost, inclusief informatie over wat dit betekent voor ID-key-autorisatie en de verschillen tussen de twee.
Slag
Het doel van driepotige OAuth voor ontwikkelaars is om een Token voor toegang waarmee een toepassing van derden namens de gebruiker toegang krijgt tot de bron van een gebruiker (bijvoorbeeld cijfers via onze app-API's).
Entiteiten
Er is Vier entiteiten betrokken bij driebenige OAuth:
- Apis
- Bijv. onze applicatie of data-API's
- Ook bekend als de Bron server in de officiële specificaties
- Toepassing
- Een applicatie van derden die gebruikmaakt van onze API's
- Ook bekend als de klant in de officiële specificaties
- Autorisatie server
- Voorziet onder andere in toegangstokens
- De autorisatieserver van Brightspace wordt gehost op auth.brightspace.com
- Gebruiker
- Bijv. een student of instructeur
- Ook bekend als de Eigenaar van de bron in de officiële specificaties
Een aanvraag registreren
- Navigeer als systeembeheerder naar de Uitbreidbaarheid beheren Admin tool.
- Klik op de knop OAuth 2.0 tabblad.
- Klik op de knop Registreer een app knoop.
- Registreer de voorbeeldtoepassing. Gebruik in dit voorbeeld de volgende waarden:
Na registratie krijgt u een Klant-ID en een Geheim van de klant, die u nodig heeft voor het volgende gedeelte.
Meer informatie over applicatieregistratie is beschikbaar in de OAuth 2.0-sectie van onze API-referentie Documentatie.
Code Voorbeeld Walkthrough
We hebben een Voorbeeld applicatie Gebruik Uitdrukken om ontwikkelaars te helpen OAuth 2.0 te benutten. Deze toepassing start de driepotige OAuth-stroom om een toegangstoken voor een bepaalde gebruiker te verkrijgen en roept vervolgens de whoami API met behulp van dat token.
De gebruiker dient tijdens de stroom verschillende webaanvragen in bij de toepassing en de toepassing definieert een route voor elk van deze aanvragen. In de volgende walkthrough wordt elke route doorlopen in de volgorde waarin de gebruiker ze tegenkomt.
1. De gebruiker bezoekt de bestemmingspagina van de applicatie, die een knop Gegevens ophalen bevat:
app.get('/', functie(req, res) {
Retourneert een HTML-pagina met een knop 'Gegevens ophalen'
res.render('index');
});
2. De knop Gegevens ophalen roept de /auth-route aan die ervoor zorgt dat de toepassing een autorisatieaanvraag uitvoert. De toepassing doet dit door de aanvraag-URI (een eindpunt op onze autorisatieserver) op te stellen en de gebruiker om te leiden naar die URI:
app.get('/auth', function(req, res) {
var authCodeParams = querystring.stringify({
response_type: "code",
redirect_uri: getRedirectUri(req),
client_id: process.env.CLIENT_ID,
scope: "kern:*:*",
Staat: "NotASecureState_rfc6749_section_10.12"
});
res.redirect(authCodeEndpoint + "?" + authCodeParams);
});
3. De gebruiker wordt gevraagd om in te loggen met zijn Brightspace-inloggegevens (als hij nog niet is ingelogd). Na een succesvolle aanmelding krijgt de gebruiker een pagina te zien waar hij kan bevestigen of hij de applicatie namens hem laat handelen. Deze stap maakt deel uit van de Autorisatie aanvraag, maar heeft geen betrekking op de toepassing.
4. De autorisatiedienst biedt een Reactie op autorisatie naar de applicatie door de gebruiker terug te leiden naar de applicatie. Dit is gebaseerd op de URI omleiden Waarde die wordt verstrekt tijdens de registratie van de aanvraag.
Laten we elk onderdeel van deze routedefinitie afzonderlijk bekijken:
een. Hiermee wordt de callback-route geregistreerd waarnaar de autorisatieserver de gebruiker zal omleiden:
app.get('/callback', functie(req, res) { ... }
b. Met behulp van de autorisatiecode van het autorisatieantwoord en de referenties van de toepassing maakt de toepassing een aanvraag voor een toegangstoken:
var authorizationCode = req.query.code;
var laadvermogen = {
grant_type: "authorization_code",
redirect_uri: getRedirectUri(req),
code: autorisatieCode};
verzoek
.post(tokenEindpunt)
.auth(process.env.CLIENT_ID, process.env.CLIENT_SECRET)
.type('formulier')
.send (payload)
.einde( ... )
c. Belangrijk: hoewel niet weergegeven, moet de applicatie ook de staat parameter om ervoor te zorgen dat deze dezelfde waarde heeft die we naar de autorisatieserver hebben gestuurd. Dit zorgt ervoor dat de /Callback Het eindpunt verwerkt geen autorisatiecodes die niet door de toepassing zijn aangevraagd. Om deze reden is de staat De waarde die in de autorisatieaanvraag naar de autorisatieserver wordt verzonden, moet een waarde zijn die niet kan worden geraden.
d. Het antwoord op het toegangstoken bevat een toegangstoken waarmee de toepassing namens de gebruiker API's kan aanroepen. Deze waarde slaan we voor het gemak op in een cookie zodat we in de volgende stap een API-aanroep kunnen doen:
functie(err, postResponse) {
als (err) {
console.log(
'Fout met toegangstoken',
err.reactie || zich vergissen
);
res.redirect('/');
} else {
res.cookie(
cookieNaam,
{ accessToken: postResponse.body.access_token },
cookieOpties
);
res.redirect('/data');
}});
e. Alles op een rijtje:
app.get('/callback', function(req, res) {
var authorizationCode = req.query.code;
var laadvermogen = {
grant_type: "authorization_code",
redirect_uri: getRedirectUri(req),
code: autorisatieCode
};
verzoek
.post(tokenEindpunt)
.auth(process.env.CLIENT_ID, process.env.CLIENT_SECRET)
.type('formulier')
.send (payload)
.end(function(err, postResponse) {
als (err) {
console.log(
'Fout met toegangstoken',
err.reactie || zich vergissen
);
res.redirect('/');
} else {
res.cookie(
cookieNaam,
{ accessToken: postResponse.body.access_token },
cookieOpties
);
res.redirect('/data');
}
});
});
5. De applicatie gebruikt het toegangstoken om namens de gebruiker API's aan te roepen:
app.get('/data', functie(req, res) {
var access_token = req.cookies[cookieName].accessToken;
verzoek
.get(process.env.HOST_URL + '/d2l/api/lp/1.10/users/whoami')
.set('Autorisatie', 'Aan toonder ${access_token}')
.end(functie(fout, antwoord) {
als (fout) {
var errorMessage = JSON.stringify(fout, null, 2);
console.log(foutmelding);
res.send('${errorMessage}');
} else {
var locals = {
gegevens: JSON.stringify(
JSON.parse(antwoord.tekst || '{}'),
nul
2
)
};
res.render('gegevens', lokale gegevens);
}
});
});
