O que é um aplicativo conectado para crachás digitais da Parchment?
Um aplicativo conectado ao Parchment Digital Badges é qualquer serviço web que utilize o Open Badges como emissor ou exibidor. Se você deseja incorporar conquistas verificáveis ao seu ecossistema, conecte-se à API do Parchment Digital Badges para facilitar o processo.
Aplicativos do emissor
Os aplicativos emissores reagem a eventos em seu próprio domínio para conceder novos distintivos aos usuários.
Aplicativos de exibição
Os aplicativos de exibição ajudam os usuários a mostrar e a obter valor com os distintivos que conquistaram.
Conectando-se aos crachás digitais da Parchment
Acesso à API com concessão de código de autorização OAuth2
O Parchment Digital Badges oferece funcionalidades de Provedor de Identidade/Servidor de Autorização/Servidor de Recursos OAuth2 para ajudar seu aplicativo conectado a obter, de forma segura, um token de API específico do usuário para acessar seus badges. Você pode adicionar um botão "Conectar ao Parchment Digital Badges" ou "Entrar com o Parchment Digital Badges" ao seu serviço. Existem diversos servidores do Parchment Digital Badges implantados em diferentes regiões do mundo, e seu aplicativo pode se conectar a cada região desejada separadamente. Para assinar solicitações OAuth para um servidor específico do Parchment Digital Badges, seu serviço precisa estabelecer uma chave secreta compartilhada com o administrador desse servidor.
Você pode criar aplicativos que se conectam com os crachás digitais da Parchment. Entre em contato com a Parchment Digital Badges para solicitar uma chave e um segredo do aplicativo para assinar suas solicitações OAuth. Descreva o que você planeja criar e que tipo de informação precisa dos usuários dos crachás digitais da Parchment.
Solicitar acesso à API de crachás digitais da Parchment
Para cada região de disponibilidade do serviço Parchment Digital Badges, ao solicitar uma chave de desenvolvedor, um registro de aplicativo será criado com uma chave e um segredo. Ao solicitar uma chave, certifique-se de descrever qual região você gostaria de usar (Sandbox de teste, Austrália, Canadá, UE/Irlanda, Singapura ou EUA). Esses servidores regionais também têm sua própria interface de usuário e domínio de API , portanto, certifique-se de usar o domínio correto com base no servidor que você está usando. Usamos o servidor de produção dos EUA como padrão em nossa documentação. A capacidade de obter automaticamente uma chave e um segredo para certos tipos de aplicativos também está disponível por meio do protocolo Badge Connect (Open Badges 2.1) . Esses escopos permitem que seu aplicativo acesse a mochila de um usuário para ler seus emblemas ou enviar novos emblemas.
Escopos de Permissão
Os aplicativos emissores e exibidores precisam de uma combinação de permissões para os endpoints da API do emissor e do destinatário (backpackage). Isso é feito solicitando um conjunto de escopos de permissão ao registrar seu aplicativo com o administrador do servidor Parchment Digital Badges. Esses escopos, ou um subconjunto deles, estarão disponíveis quando você solicitar autorização em nome de um usuário do seu aplicativo.
Escopo do perfil (automático)
- r:profile Isso permite obter informações sobre o usuário que ele definiu no Parchment Digital Badges, incluindo nome, sobrenome e endereços de e-mail registrados. Esse escopo está disponível automaticamente. Ele permite acessar o endpoint GET /v2/user/profile .
Âmbito de atuação do emissor
- r:issuer Isso permite obter informações sobre os perfis dos emissores em que o usuário autenticado atua como membro da equipe, editor ou proprietário. Você pode visualizar metadados do emissor, distintivos definidos por esses emissores e prêmios de distintivos concedidos por eles.
- rw:issuer Isso permite acesso de leitura/gravação aos recursos acima, na medida em que o usuário autenticado possa executar essas ações. Usuários com nível "Equipe" podem ler todos os dados e conceder novas instâncias de distintivos definidos; usuários com nível "Editor" também podem definir novas classes de distintivos e editar as existentes. Membros com nível "Proprietário" podem modificar a lista de funcionários.
Lunetas de Mochila
- r:backpack Permite ler as declarações que o usuário recebeu de emissores neste servidor Parchment Digital Badges ou que foram importadas para sua mochila a partir de emissores Open Badges externos.
- rw:backpack Permite ler, criar e atualizar asserções e coleções de asserções. Para asserções, isso significa que você pode acionar a importação de uma asserção do Open Badges definida em outro lugar, enviando-a para a mochila do destinatário.
O fluxo de trabalho de concessão de código de autorização OAuth2 (OAuth2 Dance)
Assim que você nos enviar por e-mail os URIs de Escopo e Redirecionamento e nós respondermos com um client_id e client_secret , podemos prosseguir. Suponha que um usuário do Parchment Digital Badges queira conceder a você acesso aos seus badges, emissores e informações de perfil. Primeiro, crie um botão "Entrar com Parchment Digital Badges" em seu site que direcione para o seguinte URI (quebras de linha adicionadas para facilitar a leitura):
https://badgr.com/auth/oauth2/authorize?
client_id=123&redirect_uri=https%3A%2F%2Fexample.com%2Fauth&scope=r%3Aprofile%20rw%3Aissuer%20r%3Abackpack
Defina `client_id` com o ID do cliente que você recebeu da equipe do Parchment Digital Badges. Defina `redirect_uri` com o URI de redirecionamento do seu aplicativo (codifique este e todos os parâmetros em URL). Usamos isso para redirecionar o usuário de volta ao seu site com um código de autorização depois que ele fizer login e conceder acesso a você. Defina `scope` com o nível de acesso que você está solicitando.
Após o Parchment Digital Badges redirecionar o usuário de volta para seu aplicativo com o Código de Autorização no parâmetro de consulta, seu aplicativo precisará trocar esse código temporário por um Token de Acesso permanente por meio de uma solicitação POST. Aqui está um exemplo usando curl :
curl https://api.badgr.io/o/token -d \
"grant_type=authorization_code\
&code=XYZ\
&client_id=123\
&client_secret=ABC\
&redirect_uri=https://example.com/auth"
Observação : você pode passar um parâmetro de estado, que deve ser uma string codificada em URL e segura para uso em URLs. Por exemplo, você pode codificar um pequeno trecho de JSON. Esse parâmetro será retornado para você na sua URL de redirecionamento.
Troque este código de autorização por um token de acesso.
curl https://api.badgr.io/o/token \
-d "grant_type=authorization_code&code=authorization_code"
E pronto! Você terminou. Você receberá um documento como este:
{
"token_type": "Bearer",
"access_token": "C1HePsbwS3tUmwC6OCKsC41w96xckc",
"expires_in": 86400,
"refresh_token": "xwHPFwH55tQpCy3qCgsIW59k3g3aPh",
"scope": "rw:issuer rw:profile rw:backpack"
}
E pronto! Você pode armazenar o token de acesso em seu aplicativo. Agora você pode usar o `access_token` obtido nesta solicitação para autenticar requisições à API. Veja "Usando a API de Crachás Digitais da Parchment" abaixo.
Segue um diagrama que mostra o fluxo de autorização inicial:
Seu token de acesso expirará (por padrão, 24 horas após a emissão). Nesse momento, você poderá renová-lo usando o refresh_token incluído com o token. Os tokens de atualização têm longa duração e devem ser armazenados com segurança. Os tokens de acesso também devem ser armazenados com segurança, mas apresentam menor risco devido à sua menor duração. Você pode obter um novo token de acesso usando seu token de atualização fazendo uma nova requisição POST para o endpoint de autorização.
curl https://api.badgr.io/o/token -X POST -d \
"grant_type=refresh_token&refresh_token=YOURREFRESHTOKEN&client_id=YOURCLIENTID&client_secret=YOURCLIENTSECRET"
Você receberá um novo documento de token, incluindo um novo access_token e um refresh_token . O novo token de acesso será válido pelo número de segundos especificado.
Observação: Se você nos forneceu um URI de redirecionamento localhost, lembre-se de usar os endpoints do nosso ambiente de teste sandbox para realizar os testes. Use https://test.badgr.com/auth/oauth2/authorize e https://api.test.badgr.com/o/token . Para obter informações mais detalhadas sobre o OAuth2, consulte a RFC 6749 em https://tools.ietf.org/html/rfc6749 . Em ambientes de produção, o HTTPS é obrigatório para URIs de redirecionamento, e domínios de túnel localhost ou de máquinas de desenvolvimento não são permitidos.
Utilizando a API de crachás digitais da Parchment
Guia de Início Rápido: Veja a documentação da API de Insígnias Digitais da Parchment
Para autenticar uma solicitação usando um token OAuth, utilize o cabeçalho Authorization com o valor Bearer , um espaço e, em seguida, o token obtido. Exemplo: Authorization: Bearer cZTp1ZMMSasZ4mbP2u2Pjt4NH3AVIf
As requisições para a API /v2/ são retornadas por padrão em JSON com um envelope de resposta padrão. Se a requisição for bem-sucedida, a chave `result` conterá uma lista de objetos `result` (`[]`), e os resultados individuais aparecerão como uma única entrada dentro desse array JSON. Experimente o fluxo OAuth e faça requisições criando uma conta gratuita e clicando no botão "Autorizar" na documentação da API .
