O Azure Cards permite que os usuários importem e sincronizem itens de trabalho do Azure Boards com boards da Miro. Este guia aborda a implementação técnica da integração, o modelo de segurança, o tratamento de dados e o fluxo de consentimento da Microsoft para admins que estão avaliando ou configurando a integração. Para ver o passo a passo completo e as instruções de configuração para usuários finais, consulte Azure Cards.
Requisitos e limitações
- Personalização de cartões (escolher quais atributos são exibidos em um cartão) não é suportada.
- Importar um cartão colando a URL de uma tarefa a partir da área de transferência não é suportado.
Implementação técnica
A Miro integra-se ao Azure Boards por meio da API REST do Azure DevOps e inscreve-se nos service hooks do Azure DevOps para receber atualizações de work items em tempo real.
Fluxo de dados
O fluxo de dados ocorre em ambos os sentidos entre o Azure DevOps e a Miro.
Azure DevOps → Miro:
- A lista de work items exibida no seletor de work items do Azure DevOps. Essa lista inclui apenas os work items aos quais o usuário solicitante tem acesso no Azure DevOps, e contém o ID, tipo, título, responsável e status.
- Detalhes do work item exibidos em um cartão do Azure: ID, título, projeto, tipo, status, descrição, work item pai, responsável, prioridade, área, iteração, story points e a URL do work item no Azure Boards. Esses dados chegam a cada atualização do item correspondente no Azure Boards. O Azure DevOps envia outros campos do work item junto a esses, mas a Miro descarta quaisquer campos fora desta lista.
Miro → Azure DevOps:
- Informações do item de trabalho usadas para criar um cartão do Azure: título, projeto, tipo, status, descrição, item de trabalho pai, responsável, prioridade, área, iteração e story points.
- Strings de pesquisa usadas para filtrar os resultados do seletor e para filtrar responsáveis, áreas, iterações e itens de trabalho pai ao criar um cartão.
Dados em trânsito
Os dados trocados entre o Azure DevOps e a Miro são criptografados usando TLS.
Retenção de dados
A Miro retém os dados do item de trabalho adicionados a um board enquanto o cartão permanecer no board, e os mantém atualizados se hooks de serviço estiverem configurados. Não há um limite de retenção fixo para esses dados; aplicam-se os protocolos padrão de segurança da conta da Miro.
Autenticação e autorização
Os usuários autenticam sua conta do Azure usando o OAuth 2.0 (authorization code grant), trocando um código de autorização por um token de acesso. Consulte a documentação OAuth da Microsoft para detalhes sobre como o OAuth do Azure DevOps funciona.
Cada usuário da Miro que autoriza o Azure Cards recebe seu próprio token de acesso, e o acesso não é compartilhado entre usuários.
Escopos de autorização necessários
-
vso.identity: ler identidades e grupos. -
vso.graph: ler informações sobre usuários, grupos, escopos e filiação a grupos. -
vso.memberentitlementmanagement: ler usuários, suas licenças e os projetos e extensões aos quais têm acesso. -
vso.project: ler projetos e times. -
vso.work_full: acesso total a work items, queries, backlogs, plans e metadados de rastreamento de work items; também necessário para receber notificações de eventos de work items via service hooks. Esse escopo concede acesso mais amplo do que a Miro utiliza. O Azure DevOps não oferece um escopo mais restrito limitado apenas a work items, e a Miro apenas lê e grava dados de work items.
Consulte a referência de escopos da Microsoft para mais detalhes.
O que é armazenado na Miro e como
Somente tokens de acesso são usados durante a operação da integração. A Miro não retém tokens de solicitação nem outros segredos OAuth além do token de acesso. Os tokens de acesso são armazenados com segurança no banco de dados da Miro e usados apenas no lado do servidor.
Segurança do service hook
A Miro gera uma URL única de service hook, contendo uma chave secreta, para cada time que configura a integração. Cada instância do Azure DevOps chama sua própria URL única de service hook para notificar a Miro sobre alterações em work items.
As requisições são enviadas por uma conexão criptografada, portanto a própria URL não fica exposta em trânsito. A principal forma de uma URL de service hook chegar a terceiros não autorizados é se um admin do Azure DevOps compartilhar a chave fora da organização, intencionalmente ou por engano.
Cenários de consentimento ao conectar ou reconectar
Conectar ou reconectar a instância do Azure DevOps (por exemplo, após a Miro atualizar o app Azure Cards registrado) faz com que o admin passe pelo fluxo de consentimento da Microsoft. O que o admin vê depende das configurações de consentimento do tenant do Microsoft Entra (veja visão geral do consentimento para admins e usuários da Microsoft):
- Se a aprovação de admin do Entra for necessária e o admin que conecta a integração tiver as permissões adequadas: o admin pode marcar Consentir em nome da sua organização na tela de consentimento da Microsoft. Isso aprova o app para todos os usuários do tenant do Entra de uma só vez.
- Se o consentimento do usuário for permitido: o admin que conecta a integração consente apenas por conta própria. Cada outro usuário consente individualmente na primeira vez que usar a integração.
- Se o admin que está conectando a integração não tiver permissão para aprovar: será exibida a mensagem Precisa de aprovação do admin, e o admin deverá solicitar que um admin do Microsoft Entra conceda o consentimento, seja enviando uma solicitação a partir da tela de consentimento (se o tenant permitir) ou entrando em contato diretamente com um admin do Entra.
Reconectar no nível Enterprise ou de organização
Requer permissões de Admin da empresa na Miro e permissões do grupo Project Collection Admin no Azure Boards.
- Na Miro, acesse Configurações da empresa > Aplicativos e integrações > Aplicativos > Gerenciar aplicativos > Azure Cards > Configurações.
- Selecione Desconectar ao lado da instância existente do Azure DevOps.
- Selecione Conectar para reconectar a instância do Azure DevOps. Você será redirecionado para a Microsoft para iniciar sessão.
- Após iniciar sessão, você verá a tela de consentimento para o aplicativo Miro Azure Cards. O que acontece a seguir depende das suas permissões no Entra e das configurações de consentimento do seu locatário. Consulte os cenários acima.
Reconectar no nível do time Enterprise ou no plano Business
Exige permissões de admin do time na Miro e permissões do grupo Project Collection Admin no Azure Boards.
- Na Miro, acesse Configurações do time > Aplicativos > Azure Cards.
- Selecione Desconectar ao lado da instância do Azure.
- Selecione Desconectar ao lado da conta Microsoft.
- Selecione Conectar para reconectar a conta Microsoft. Você será redirecionado para a Microsoft para iniciar sessão.
- Após iniciar sessão, você verá a tela de consentimento do aplicativo Miro Azure Cards. O que acontece a seguir depende das suas permissões no Entra e das configurações de consentimento do seu locatário, veja os cenários acima.
- De volta à Miro, selecione Conectar ao lado da instância do Azure para reconectá-la.
- Repita estas etapas para cada time que usa a integração Azure Cards.