Antes de começar
Você precisa ter estas informações:
- O par Id-Key do seu aplicativo (digamos 'appID' e 'appKey', mas eles não serão assim)
- O domínio do seu serviço de back-end (qual LMS você está chamando)
- O ponto de retorno de chamada para seu aplicativo/serviço em que o LMS pode Enviar Pares de ID de usuário e chave quando você os solicita
Criando a conta de serviço e coletando tokens de usuário
Seu aplicativo precisará ser executado com uma conta de serviço ou outra conta com privilégios suficientes para executar as ações necessárias com as APIs. Portanto, o primeiro passo é criar uma conta no Ambiente de Aprendizagem com privilégios suficientes para fazer as chamadas de API que você precisa fazer.
Depois de criar uma conta de serviço:
- Você precisa coletar manualmente os tokens de usuário usando um utilitário como a API Test Tool () para autenticar com seu LMS.
- Armazene essas chaves com segurança e configure seu LMS para garantir que os tokens de usuário sejam duradouros. Muitos sistemas têm um tempo limite simbólico de 30 dias, mas quando uma integração headless está em vigor como a que você está propondo, geralmente é uma boa ideia tornar o tempo limite infinito. Você pode entrar em contato com o Suporte do Desire2Learn para verificar o valor de tempo limite para os tokens de usuário.
Nota: os "tokens de usuário" acima não significam o tempo limite definido por meio do d2l. Configuração do servidor SessionTimeout. Em vez disso, isso é definido por meio do d2l. Configuração Security.Api.TokenTimeout.
Para esclarecer melhor:
- O d2l. A variável de configuração SessionTimeout refere-se ao período de tempo limite da sessão da Web (ou seja, quanto tempo alguém pode ficar ocioso antes que a interface do usuário da Web do LMS atinja o tempo limite e solicite que o usuário faça login novamente). Esse tempo limite geralmente é definido em um intervalo de vários minutos a uma hora.
- O d2l. A variável de configuração Security.Api.TokenTimeout refere-se ao período de tempo limite do par id do usuário\chave associado ao processo de autenticação Valence. Em outras palavras, esses tokens são o valor x_b e a base para o valor x_d que são enviados como parâmetros de consulta em cada chamada de API para identificar o usuário. Esse tempo limite geralmente é definido em um intervalo de vários dias ou pode ser definido como nunca expirado. No último caso, o par de id/chave do usuário só pode ser invalidado alterando a senha do usuário ou revogando explicitamente o acesso ao aplicativo. Depois que o par de ID de usuário\chave se tornar inválido, o aplicativo terá que reiniciar o processo de autenticação para receber um novo par de ID de usuário\chave para assinar chamadas de API.
Criar um contexto de aplicativo
- Construa um contexto de aplicativo com D2LAppContext( "appID", "appKey", ""); isso cria um contexto de aplicativo que você pode usar para fazer a solicitação para buscar um par de ID de usuário e chave do LMS
- authURL = DAC.createWebUrlForAuthentication( new URI("")); isso torna o "authURL", você precisa direcionar um contêiner da web (o navegador do usuário) para este URL: que solicita que o LMS envie de volta o par de chaves de ID do usuário para a sessão do usuário que será estabelecida dentro do contêiner da web solicitante.
O LMS enviará o par de chave de identificação do usuário redirecionando voltar para com o par ID do usuário-chave anexado como parâmetros de consulta na URL de redirecionamento. Vamos chamar isso de cheio URL de redirecionamento 'fullRedirectUrl'.
Criar um contexto de usuário
- É possível tampouco Crie um contexto de usuário usando fullRedirectUrl: DAC.createUserContext( fullRedirectUrl )
- OU, você pode extrair o par UserId-Key de fullRedirectUrl (digamos 'userID' e 'userKey', mas eles terão uma aparência diferente) e usar: DAC.createUserContext( "userID", "userKey" )
Fazer chamadas
- Agora você pode usar seu contexto de usuário, DUC, para fazer chamadas: DUC.createAuthenticatedUri( "/d2l/api/lp/1.3/users/whoami", "GET")
Nota: que aqui você fornece apenas a rota da API, mais o método HTTP (maiúsculas); certifique-se de usar uma rota em um contrato de API compatível com seu LMS de back-end - aqui fazemos a chamada whoami do contrato de API v1.3, mas seu LMS pode não suportar esse contrato (ou pode suportar um mais recente).
Solucionando problemas
Pergunta: Para ser claro, estou pegando o "... ou" mencionada acima, extraindo os valores userID e userKey de apitesttool. desire2learnvalence.come, em seguida, fazer createUserContext usando esses valores (junto com o nome do host D2L, porta, etc. --- a versão de 6 parâmetros dessa função).
Recebo um contexto desse método e, quando o uso para fazer uma chamada à API, o serviço retorna um 403 "Token inválido".
Responder: Se o seu aplicativo não fosse conhecido pelo LMS (ou seja, não fosse uma ID de aplicativo habilitada), você receberia um erro ligeiramente diferente. Isso nos diz que tampouco você não está fazendo uma assinatura de aplicativo válida em sua eventual chamada de API (o que provavelmente significa que sua chave de aplicativo não é adequada para seu ID de aplicativo), ou a chave de identificação do usuário que você está usando de alguma forma não é útil.
É altamente recomendável que você percorra a caminhada no Documentos do SDK do cliente Python mesmo que você não pretenda usar Python a longo prazo. Você pode passar por esse processo de forma interativa e passo a passo e, assim, ter um controle mais direto sobre o que está acontecendo em cada etapa do processo para ver o que está acontecendo. Com um aplicativo corporativo criado em C# ou Java, você usa técnicas de depuração padrão para sentir o fluxo de trabalho – que também funcionam bem: no entanto, um shell interativo permite que você execute cada etapa à medida que avança e inspeciona os resultados.
Para começar a usar o SDK python como nesse passo a passo, você precisa:
- Para ter uma instalação do Python, e ajuda ter o pacote 'pip' instalado para fazer a instalação do módulo python
- Para ter o módulo python 'requests' instalado (que o pip deve encontrar automaticamente)
- Para ter o módulo python 'd2lvalence' instalado (que o pip deve encontrar automaticamente)
Pergunta: Fui dar uma olhada na página de autenticação do Python que você referenciou, mas estou confuso. Essa página me aconselha a ir ao navegador e pegar o URL de redirecionamento depois de obter o resultado de createUrlForAuthentication (usando o formato php para a função).
Responder:
A maneira como o modelo funciona em alto nível é como um modelo de autenticação de três pernas:
- Você tem um usuário real com um navegador
- Você tem um serviço ou aplicativo de terceiros que o usuário pode visitar (normalmente) que deseja fazer chamadas à API Valence em nome desse usuário
- Você tem o LMS de back-end
Quando o usuário real visita o aplicativo de terceiros, antes de fazer chamadas de API, ele precisa solicitar ao LMS um par de ID de usuário e chave para acompanhar seu par de ID de aplicativo para que ele possa fazer chamadas de API em nome do usuário. Para fazer isso, ele redireciona o navegador do usuário para o "caminho de login" do LMS para garantir que o LMS "saiba" quem é o usuário/navegador:
- Se o navegador do usuário já tiver uma sessão da Web com LMS, o LMS poderá dizer "Eu sei quem é o usuário" e enviar o par de chave de identificação do usuário correto para o aplicativo de terceiros.
- Se o navegador do usuário ainda não tiver uma sessão, o LMS poderá tentar autenticar o usuário usando a maneira padrão para esse LMS; ENTÃO, ele pode enviar o par de chave de ID de usuário correto de volta para o aplicativo de terceiros. (Observe que, em ambos os casos, o par de chave de ID de usuário é gerado especificamente para AQUELE usuário e AQUELE aplicativo: não é transferível para nenhum outro par de chave de ID de aplicativo.)
Este sistema de autenticação de três pernas faz sentido no caso em que você realmente tem três partes separadas. Em casos como o seu, em que você deseja escrever um aplicativo de serviço de TI (sem periféricos) que não tenha um "usuário operacional no momento com seu navegador da Web", normalmente recomendamos que você crie uma conta de serviço – uma finalidade especial, "usuário" e "função" que só é usada para seu aplicativo de serviço.
Nesse caso, você precisa ter uma maneira de passar pelo processo de autenticação acima toda vez que precisar de um par de ID de usuário válido para esse "usuário" de serviço. Existem várias maneiras de fazer isso, mas todas envolvem (em algum momento) um usuário real com um navegador real se levantar e desempenhar o papel dessa terceira perna no processo de autenticação.
Normalmente, o que você faz é usar uma versão hospedada localmente de um de nossos exemplos simples ou nossa "Ferramenta de teste de API" online (https://apitesttool. desire2learnvalence.com/) ou uma sessão interativa do Python com nosso SDK do Python (como no passo a passo de autenticação que apontei). Normalmente, para melhor segurança, recomendamos que você faça esse processo dentro de um ambiente seguro, portanto, a API Test Tool talvez não seja a melhor solução, especialmente se você não for se conectar com HTTPS, porque ele está na Internet. No entanto, se você usar HTTPS para conectá-lo ao seu LMS, provavelmente é suficientemente seguro.
Para o processo de "coleta de um par de chave de ID de usuário", você precisa usar suas credenciais de chave de ID de aplicativo OWN (ou seja, o par que você recebeu para o aplicativo/serviço que está escrevendo).
Se você estiver fazendo isso interativamente, crie um contexto de aplicativo com essas credenciais. Se você estiver usando um exemplo ou a ferramenta online, forneça seu próprio par de ID do Aplicativo-Chave como os que devem ser usados (não os padrão no formulário: esses são um único conjunto de chaves públicas para fins de demonstração). Você precisa fornecer o nome do host do seu LMS e a porta para chamar. Em seguida, você passa pelo "processo de autenticação":
- Se você estiver usando uma sessão interativa com o SDK do Python, crie uma "URL de autenticação" que será recortada e colada em seu navegador... para fazer isso, você também precisa fornecer um "URL de retorno de chamada" informando ao LMS para onde enviar a chave de identificação do usuário - sugerimos localhost porque isso voltará para o computador onde seu navegador está e provavelmente seu navegador reclamará que não consegue encontrar o URL, mas você pode copiar o URL completo da barra de endereços.
- Se você estiver usando a ferramenta de amostra ou online, a "URL de retorno de chamada" ficará oculta para você - o formulário a fornece automaticamente: o par de ID de usuário e chave será enviado de volta ao servidor web que executa a ferramenta de amostra/online.
Ao passar de volta o par User-Id-Key, o LMS os colocará como parâmetros de consulta naquele "URL de retorno de chamada" que você forneceu na solicitação que acabou de enviar.
- Se você estiver usando a ferramenta online ou uma amostra, a ferramenta/amostra deverá decompor automaticamente esse URL de retorno de chamada, retirar as credenciais e mostrá-las a você.
- Se você estiver usando uma sessão interativa do Python, o LMS redirecionará para "localhost" e adicionará o par User Id-Key nos parâmetros de consulta. Copie todo o URL da barra de endereços do navegador e alimente-o de volta em sua sessão Python para criar o "contexto do usuário" - isso removerá as chaves de identificação do usuário desse URI de resultado e criará um contexto de usuário para você que você pode usar para fazer chamadas de API interativamente ... você também pode inspecioná-lo para ver o que é o par User-Id-Key, salvá-los no disco e assim por diante.
De qualquer forma, você não "reuniu com sucesso um par de chave de ID de usuário" para que SUA conta de serviço acompanhe a chave de ID do aplicativo. Você pode armazenar isso em cache em um local seguro acessível ao seu script / aplicativo de administração (como em um arquivo de configuração). É altamente recomendável que você trate o par de chaves de ID do aplicativo e todas as chaves de identificação de usuário que o acompanham como informações altamente confidenciais - com esses tokens, QUALQUER PESSOA pode fazer uma chamada para o seu LMS fingindo ser seu aplicativo como um usuário válido, então você deseja colocá-los em um local seguro visível apenas para um pequeno número de pessoas e para o script / aplicativo que precisa usá-los.
Sempre que a senha dessa conta de serviço for alterada, você precisará passar por esse processo novamente para coletar um novo par de ID de usuário e chave. Se o seu LMS tiver tokens de API configurados para expirar em um tempo fixo, você também precisará refazer esse processo quando esse tempo expirar. Por padrão, os LMSs têm esse tempo de expiração definido como "indefinido" e os tokens de chave de ID do usuário expiram somente quando a senha do usuário é alterada ou o administrador do site nega o acesso a aplicativos de terceiros para esse usuário.
Para outro ponto de explicação, você pode ver este tópico em nosso blog do desenvolvedor: Introdução à autenticação de chave de ID do aplicativo. Tem vários anos, mas o material ainda é verdadeiro, e os diagramas são diferentes dos que aparecem em nossos documentos online, de modo que o contraste pode ajudar a obter uma imagem mais arredondada.https://d2l.someUniversity.eduhttps://yourServer.org/authCallback
https://apitesttool.desire2learnvalence.com/
https://d2l.someUniversity.eduhttps://yourServer.org/authCallbackhttps://yourServer.org/authCallback