Por Mark Tse
O que é OAuth 2.0?
O OAuth 2.0 é uma estrutura de autenticação padrão aberta que fornece vários fluxos de autenticação, incluindo o fluxo OAuth de três pernas que agora é compatível com o Brightspace. Ele permite que os desenvolvedores escrevam aplicativos que acessam diferentes serviços em nome de um usuário.
Público-alvo
Esta postagem é direcionada a desenvolvedores que desejam escrever aplicativos que utilizam APIs do Brightspace. Agora oferecemos suporte à especificação OAuth 2.0 para autenticação de três etapas, além de nossa especificação de autorização de chave de ID existente.
Mais informações estão disponíveis em nossa postagem no blog de perguntas e respostas do OAuth 2.0, incluindo informações sobre o que isso significa para a autorização da chave de ID e as diferenças entre as duas.
Começando
O objetivo do OAuth de três pernas para desenvolvedores é obter um token de acesso que permite que um aplicativo de terceiros acesse o recurso de um usuário (por exemplo, notas por meio de nossas APIs de aplicativos) em nome do usuário.
Entidades
Existem quatro entidades envolvido em OAuth de três pernas:
- Apis
- Por exemplo, nosso aplicativo ou APIs de dados
- Também conhecido como o servidor de recursos nas especificações oficiais
- Aplicação
- Um aplicativo de terceiros que usa nossas APIs
- Também conhecido como o cliente nas especificações oficiais
- Servidor de autorização
- Provisiona tokens de acesso entre outras responsabilidades
- O servidor de autorização do Brightspace está hospedado em auth.brightspace.com
- Utilizador
- Por exemplo, um aluno ou instrutor
- Também conhecido como o proprietário do recurso nas especificações oficiais
Registrando um aplicativo
- Como administrador do sistema, navegue até o Gerenciar extensibilidade ferramenta de administração.
- Clique no botão OAuth 2.0 guia.
- Clique no botão Registrar um aplicativo botão.
- Registre o aplicativo de exemplo. Para este exemplo, use os seguintes valores:
Após o registro, você receberá um ID do cliente e um Segredo do cliente, que você precisará para a próxima seção.
Mais informações sobre o registro de aplicativos estão disponíveis na seção OAuth 2.0 do nosso Referência da API Documentação.
Passo a passo de exemplo de código
Criamos um Exemplo de aplicação Usando Expressar para ajudar os desenvolvedores a aproveitar o OAuth 2.0. Esse aplicativo iniciará o fluxo OAuth de três etapas para obter um token de acesso para um determinado usuário e, em seguida, chamará o API whoami usando esse token.
O usuário fará várias solicitações da Web para o aplicativo durante o fluxo, e o aplicativo define uma rota para cada uma dessas solicitações. O passo a passo a seguir percorrerá cada rota na ordem em que o usuário os encontrará.
1. O usuário visita a página de destino do aplicativo, que contém um botão Obter Dados:
app.get('/', function(req, res) {
retorna uma página HTML com um botão "Obter dados"
res.render('índice');
});
2. O botão Obter Dados chama a rota /auth que faz com que o aplicativo execute uma solicitação de autorização. O aplicativo faz isso criando o URI da solicitação (um endpoint em nosso servidor de autorização) e redirecionando o usuário para esse 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,
escopo: "core:*:*",
Estado: "NotASecureState_rfc6749_section_10.12"
});
res.redirect(authCodeEndpoint + "?" + authCodeParams);
});
3. O usuário será solicitado a fazer login usando suas credenciais do Brightspace (se ainda não estiver conectado). Após um login bem-sucedido, será apresentada ao usuário uma página onde poderá confirmar se permite que o aplicativo atue em seu nome. Esta etapa faz parte do Solicitação de autorização, mas não envolve o pedido.
4. O serviço de autorização fornece um Resposta de autorização para o aplicativo redirecionando o usuário de volta para o aplicativo. Isso se baseia no URI de redirecionamento valor fornecido durante o registro do aplicativo.
Vejamos cada componente dessa definição de rota separadamente:
um. Isso registra a rota de retorno de chamada para a qual o servidor de autorização redirecionará o usuário:
app.get('/callback', function(req, res) { ... }
b. Usando o código de autorização da resposta de autorização, bem como as credenciais do aplicativo, o aplicativo faz uma solicitação de token de acesso:
var authorizationCode = req.query.code;
var carga = {
grant_type: "authorization_code",
redirect_uri: getRedirectUri(req),
código: authorizationCode};
pedir
.post(tokenEndpoint)
.auth(process.env.CLIENT_ID, process.env.CLIENT_SECRET)
.type('formulário')
.send (carga útil)
.end( ... )
c. Importante: embora não seja mostrado, o aplicativo também deve verificar o estado para garantir que ele tenha o mesmo valor que enviamos ao servidor de autorização. Isso garante que o /Callback O endpoint não está processando códigos de autorização que não foram solicitados pelo aplicativo. Por esse motivo, o estado O valor enviado ao servidor de autorização na solicitação de autorização deve ser um valor não adivinhável.
d. A resposta do token de acesso conterá um token de acesso que permite que o aplicativo chame APIs em nome do usuário. Armazenamos esse valor em um cookie para simplificar, para que possamos fazer uma chamada à API na próxima etapa:
function(err, postResponse) {
se (err) {
console.log(
'Erro de token de acesso',
err.response || errar
);
res.redirect('/');
} else {
res.cookie(
cookieName,
{ accessToken: postResponse.body.access_token },
Opções de cookies
);
res.redirect('/data');
}});
e. Juntando tudo:
app.get('/callback', function(req, res) {
var authorizationCode = req.query.code;
var carga = {
grant_type: "authorization_code",
redirect_uri: getRedirectUri(req),
código: authorizationCode
};
pedir
.post(tokenEndpoint)
.auth(process.env.CLIENT_ID, process.env.CLIENT_SECRET)
.type('formulário')
.send (carga útil)
.end(função(err, postResposta) {
se (err) {
console.log(
'Erro de token de acesso',
err.response || errar
);
res.redirect('/');
} else {
res.cookie(
cookieName,
{ accessToken: postResponse.body.access_token },
Opções de cookies
);
res.redirect('/data');
}
});
});
5. O aplicativo usa o token de acesso para chamar APIs em nome do usuário:
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('Autorização', 'Portador ${access_token}')
.end(função(erro, resposta) {
if (erro) {
var errorMessage = JSON.stringify(erro, nulo, 2);
console.log(errorMessage);
res.send('${errorMessage}
');
} else {
locais var = {
dados: JSON.stringify(
JSON.parse(resposta.texto || '{}'),
zero
2
)
};
res.render('dados', locais);
}
});
});