Configuração do Jira Cloud

Nesta página, descrevemos como definir e configurar uma configuração de terceiros antes de criar o repositório de dados do Jira Cloud.

Configurar autenticação e permissões

Você precisa configurar a autenticação e as permissões na central de contas de administrador da Atlassian. Isso é fundamental para permitir que o conector acesse e sincronize dados. O conector do Jira Cloud é compatível com vários métodos de autenticação, como credenciais do cliente OAuth ou tokens de API.

Criar um app OAuth 2.0

Para criar um app OAuth 2.0 para autenticação, siga estas etapas para configurar o aplicativo no Atlassian Developer Console e obter o ID do cliente e a chave secreta do cliente necessários.

Verificar o acesso de administrador da organização do Jira

Para verificar o acesso de administrador da organização do Jira, faça o seguinte:

  1. Faça login no Atlassian com suas credenciais de usuário.

  2. Selecione o app Jira.

  3. Clique em Configurações.

    Se a opção Sistema aparecer em Configurações do Jira, você tem acesso de administrador da organização do Jira. Caso contrário, peça ao administrador da organização do Jira para conceder acesso.

Criar um app OAuth 2.0

Para criar um app OAuth 2.0, faça o seguinte:

  1. Faça login no Atlassian Developer Console.

  2. Clique no ícone de perfil e selecione Developer Console.

  3. Na página Console, clique em Criar e selecione Integração do OAuth 2.0.

  4. Na página de criação do app, faça o seguinte:

    1. Insira um nome para o app.

    2. Marque a caixa de seleção para concordar com os termos para desenvolvedores da Atlassian.

    3. Clique em Criar.

  5. Na página do app, faça o seguinte:

    1. No menu de navegação, clique em Autorização.

    2. Na tabela Tipo de autorização, selecione Adicionar para OAuth 2.0 (3LO).

    3. No campo URL de callback, insira o URL de acordo com o modo de conexão do repositório de dados.

      • Pesquisa e ações federadas: https://vertexaisearch.cloud.google.com/oauth-redirect.

      • Ingestão de dados: https://vertexaisearch.cloud.google.com/console/oauth/jira_oauth.html.

  6. Clique em Salvar alterações.

Receber o ID e a chave secreta do cliente

Para obter o ID do cliente e a chave secreta do cliente, faça o seguinte:

  1. Na página do app, clique em Distribuição no menu de navegação.

  2. Na página Distribuição, faça o seguinte:

    1. Na seção Controles de distribuição, selecione Editar.
    2. Na seção Status da distribuição, selecione Compartilhamento para ativar a edição de outros campos.
    3. Insira informações nos seguintes campos obrigatórios:
      1. Em Fornecedor, insira Google.
      2. Em Política de Privacidade, insira https://policies.google.com.
      3. Em O app armazena dados pessoais?, selecione Sim.
      4. Marque a caixa de seleção Confirmo que implementei a API de relatórios de dados pessoais. Para mais informações, consulte a API de relatórios de dados pessoais.
    4. Clique em Salvar alterações.

  3. Na página do app, faça o seguinte:

    1. No menu de navegação, clique em Configurações.
    2. Na página de configurações, copie o ID do cliente e a chave secreta do cliente.

Receber um ID e um URL de instância

  1. Consiga o ID da instância:

    1. Abra uma nova guia, copie o URL da instância e adicione /_edge/tenant_info a ele. Por exemplo, https://YOUR_INSTANCE.atlassian.net/_edge/tenant_info.
    2. Navegue até o link para encontrar o valor cloudId. O cloudId é o ID da instância.

  2. Consiga o URL da instância:

    1. Acesse atlassian.net e faça login com sua conta de administrador.
    2. Selecione o app que você quer sincronizar. Por exemplo, sincronize o primeiro app.
    3. Encontre o URL da instância (o subdomínio na barra de endereço).

Receber a chave do projeto

Para conseguir a chave do projeto, faça o seguinte:

  1. Faça login na sua conta do Jira Cloud.

  2. No menu de navegação, selecione Espaços.

  3. Selecione o projeto para o qual você precisa do ID do projeto.

  4. Abra qualquer problema no projeto e clique em more_horiz Ações.

  5. Clique em Exportar XML e faça o download do arquivo.

  6. Abra o arquivo XML que você baixou e procure a tag que contém project id. Copie o valor associado a essa tag para uso posterior.

Conceder papéis de administrador

Para conceder ao administrador do Jira o papel de editor do Discovery Engine no console do Google Cloud , faça o seguinte:

  1. No console do Google Cloud , acesse a página Gemini Enterprise.

  2. Acesse IAM.

    Acessar IAM

  3. Localize a conta de usuário com acesso de administrador no Jira e clique em Editar.

  4. Conceda o papel de editor do Discovery Engine ao administrador.

Para conceder a um usuário uma função de administrador no Atlassian, faça o seguinte:

  1. Faça login no Atlassian usando uma conta de administrador da organização.

  2. Clique no ícone de menu e selecione sua organização. Ou acesse admin.atlassian.com.

  3. Na página Administrador, clique no produto e selecione o botão Gerenciar usuários.

    manage-users
    Gerenciar usuários

  4. Clique em Grupos em Gerenciamento de usuários.

  5. Na página Grupos:

    1. Clique em Criar grupo.
    2. Digite um nome para o grupo.
    create-group
    Criar grupo

Esse grupo recebe as permissões necessárias para o conector. Os usuários adicionados a esse grupo herdam essas permissões. O conector usa esse grupo para autenticar e buscar documentos.

  1. Na página do grupo, clique em Adicionar produto.

  2. Selecione Administrador de acesso do usuário como a função do Jira.

  3. Selecione Administrador do produto como a função para Administração do Jira.

    jira-user-access-admin
    Administrador de acesso do usuário do Jira

  4. Clique em Permitir acesso.

  5. Clique em Adicionar membros do grupo para adicionar uma conta de usuário ou membros do grupo que o conector usa para autenticar e acessar os recursos necessários.

    add-group-members
    Adicionar participantes ao grupo

Gerenciar a visibilidade do usuário

Para tornar o e-mail do usuário visível para qualquer pessoa na conta da Atlassian, faça o seguinte:

  1. Faça login no Atlassian Developer Console.

  2. Clique no ícone de perfil e selecione Developer Console.

  3. Clique no ícone de perfil de usuário e selecione Gerenciar conta.

    manage-account
    Gerenciar conta

  4. Acesse Perfil e visibilidade.

    profile-visibility
    Perfil e visibilidade

  5. Acesse Contato e defina Quem pode ver isso como Qualquer pessoa.

    contact
    Contato

Para tornar o e-mail do usuário visível para qualquer pessoa no Jira, faça o seguinte:

  1. Faça login no Atlassian com suas credenciais de usuário.

  2. Selecione um app do Jira.

  3. Clique em Configurações > Sistema.

  4. Selecione Configuração geral no painel à esquerda.

  5. Clique em Edit Settings.

  6. Em Visibilidade do e-mail do usuário, selecione Público.

    selecionar visibilidade do e-mail
    Selecionar a visibilidade do e-mail

  7. Clique em Atualizar.

Configurar escopos mínimos do aplicativo

Para realizar as ações definidas, configure as seguintes permissões para o conector do Jira Cloud na plataforma Atlassian.

  1. Na página do aplicativo, clique em Permissões.

  2. Acesse API Jira e clique em Adicionar.

  3. Clique em Configurar.

  4. Acesse a guia Escopos clássicos.

  5. Clique em Editar escopos e selecione os escopos clássicos de acordo com sua necessidade na tabela a seguir:

    Modo de conexão Permissão Finalidade
    Pesquisa e ações federadas read:jira-user, read:jira-work Permite que o assistente busque e mostre resultados da pesquisa e detalhes do usuário em tempo real.
    write:jira-work Permite que o assistente modifique itens de trabalho (por exemplo, atualizando campos de problemas), gerencie comentários ou problemas e faça upload de anexos.
    manage:jira-project Permite que o assistente gerencie as configurações do projeto do Jira e crie novos objetos para envolvidos no projeto, como versões e componentes. Obrigatório para as ações de criação e atualização de projetos.
    Somente pesquisa federada read:jira-user, read:jira-work Permite que o assistente pesquise e visualize problemas, projetos e perfis de usuário.
    Ingestão e ações de dados read:jira-work Permite que o assistente faça rastreamento e indexação de dados abrangentes de itens de trabalho.
    write:jira-work Permite que o assistente execute ações de gravação (criação, atualizações, comentários e anexos) em itens de trabalho no ambiente ingerido.
    Ingestão de dados read:jira-work Permite que o assistente rastreie e indexe o conteúdo do Jira para disponibilizá-lo na pesquisa.

  6. Confirme se todos os escopos estão selecionados e clique em Salvar.

  7. Acesse a guia Escopos granulares.

  8. Clique em Editar escopos e selecione os escopos granulares de acordo com suas necessidades na tabela a seguir:

Modo de conexão Permissão Finalidade
Pesquisa e ações federadas write:comment:jira Permite que o repositório de dados poste novos comentários ou respostas diretamente da interface do Gemini Enterprise.
write:issue:jira Permite que o repositório de dados crie novos problemas ou faça edições importantes nos atuais.
write:attachment:jira Permite que o repositório de dados faça upload de anexos para problemas do Jira.
write:project:jira Permite que o repositório de dados crie e atualize projetos do Jira.
write:issue-worklog:jira Permite que o repositório de dados crie e atualize registros de trabalho de problemas.
write:issue-link:jira Permite que o repositório de dados crie e atualize links entre problemas.
read:issue:jira Permite que o repositório de dados leia problemas.
read:issue-type:jira Permite que o repositório de dados leia tipos de problemas.
read:comment:jira Permite que o repositório de dados leia comentários.
read:comment.property:jira Permite que o repositório de dados leia as propriedades dos comentários de problemas.
read:project:jira Permite que o repositório de dados leia projetos.
read:priority:jira Permite que o repositório de dados leia as prioridades.
read:issue.transition:jira Permite que o repositório de dados leia as transições de problemas.
read:issue-meta:jira Permite que o repositório de dados leia metadados de problemas.
read:board-scope.admin:jira-software Permite que o repositório de dados leia a configuração, os recursos do projeto, os filtros, as propriedades e os filtros rápidos de um quadro.
read:board-scope:jira-software Permite que o repositório de dados leia quadros, problemas em um quadro, problemas de um backlog, relatórios e versões.
read:issue-details:jira Permite que o repositório de dados leia detalhes do problema.
read:jql:jira Permite que o repositório de dados leia consultas da linguagem de consulta do Jira (JQL).
Somente pesquisa federada read:issue:jira Permite que o repositório de dados leia problemas.
read:issue-type:jira Permite que o repositório de dados leia tipos de problemas.
read:comment:jira Permite que o repositório de dados leia comentários.
read:comment.property:jira Permite que o repositório de dados leia as propriedades dos comentários de problemas.
read:project:jira Permite que o repositório de dados leia projetos.
read:priority:jira Permite que o repositório de dados leia as prioridades.
read:issue.transition:jira Permite que o repositório de dados leia as transições de problemas.
read:issue-meta:jira Permite que o repositório de dados leia metadados de problemas.
read:board-scope.admin:jira-software Permite que o repositório de dados leia a configuração, os recursos do projeto, os filtros, as propriedades e os filtros rápidos de um quadro.
read:board-scope:jira-software Permite que o repositório de dados leia quadros, problemas em um quadro, problemas de um backlog, relatórios e versões.
read:sprint:jira-software Permite que o repositório de dados leia detalhes do sprint.
read:issue-details:jira Permite que o repositório de dados leia os detalhes do problema.
read:jql:jira Permite que o repositório de dados leia consultas da linguagem de consulta do Jira (JQL).
Ingestão e ações de dados read:user:jira, read:group:jira, read:avatar:jira Permite sincronizar metadados de usuários/grupos e mostrar perfis de usuários.
read:issue-security-level:jira, read:issue-security-scheme:jira Permite o controle de acesso, garantindo que os dados ingeridos respeitem os limites de segurança do Jira.
read:audit-log:jira Permite rastrear mudanças e realizar sincronizações incrementais para manter os dados ingeridos atualizados.
write:comment:jira Permite adicionar comentários a problemas usando o repositório de dados.
write:issue:jira Permite que o assistente crie ou modifique problemas.
Ingestão de dados read:user:jira, read:group:jira, read:avatar:jira Permite rastrear e indexar conteúdo do Jira e relacionamentos de usuários.
read:issue-security-level:jira, read:issue-security-scheme:jira Permite mapear permissões para que apenas usuários autorizados possam pesquisar os dados ingeridos.
read:audit-log:jira Permite que o mecanismo de sincronização identifique quais itens foram atualizados ou excluídos.
read:sprint:jira-software Permite que o repositório de dados leia os detalhes do sprint.

9. Confirme se todos os escopos estão selecionados e clique em Salvar.

Instalar o User Identity Accessor

Para instalar o app User Identity Accessor for Jira Cloud no seu site do Jira Cloud, siga estas etapas:

  1. Acesse o Atlassian Marketplace.

  2. Clique em Obtenha agora.

    configure-uia-button-jira
    Assine agora

  3. Na lista Selecione um site, escolha o site do Jira em que você quer instalar o app.

  4. Clique em Revisar para autorizar as permissões necessárias e aceitar os Termos e Condições.

  5. Clique em Instalar agora para concluir a instalação do app.

    Após a instalação, uma mensagem de confirmação vai aparecer: "Seu app foi adicionado à sua instância e está pronto para uso".

Configurar o User Identity Accessor

Depois de instalar o app User Identity Accessor for Jira Cloud, configure uma chave de API que seu sistema externo (por exemplo, o conector do Jira Cloud) usa para chamar com segurança o gatilho da Web do app e buscar e-mails.

Acessar a página de configuração

Para acessar a página de configuração do app User Identity Accessor for Jira Cloud:

  1. Na sua instância do Jira Cloud, clique no ícone Configurações ⚙️ no menu de navegação.
  2. Selecione Apps no menu.
  3. Na página Administração de apps, localize o app User Identity Accessor for Jira Cloud na lista Gerenciar apps.

  4. Clique em Configurar ou no link associado ao app. A página de configuração dedicada do app será aberta no Jira Cloud.

    configure-uia-button-jira
    Configurar o User Identity Accessor para o app Jira Cloud

Configurar a chave de API

Para configurar a chave de API na página de configuração, faça o seguinte:

  1. Na seção Configuração da chave de API, especifique a chave secreta para autenticar solicitações ao web trigger do app. É possível autenticar solicitações usando qualquer um dos seguintes métodos:

    • Inserir sua própria chave: digite ou cole sua própria chave de API forte e exclusiva no campo Chave de API. Use uma chave de pelo menos 20 a 30 caracteres com uma combinação de letras maiúsculas, minúsculas, números e símbolos.

      save-key
      Insira sua própria chave

    • Gerar uma chave: clique no botão Gerar nova chave. O sistema gera e mostra uma chave forte e aleatória no campo.

      generate-key
      Gerar uma chave

      Importante: copie imediatamente a chave de API exibida no campo. Por motivos de segurança, talvez não seja possível ver a chave completa novamente depois de salvar ou sair da página. Se você perder a senha, será necessário definir ou gerar uma nova.

  2. Clique em Salvar chave de API. Uma mensagem de confirmação vai aparecer informando que a chave foi salva com segurança.

Testar a configuração do app

Verifique se o app User Identity Accessor for Jira Cloud está configurado corretamente enviando uma solicitação do seu sistema externo e confirmando que os endereços de e-mail do usuário são retornados corretamente.

Acessar o URL do gatilho da Web

  1. Na página Administração de apps, localize a seção URL do Webtrigger, que mostra o URL exclusivo específico do seu site do Jira e da instalação do app:
    • Seu sistema externo precisa chamar esse URL para solicitar e-mails de usuários.
    • Exemplo de URL: https://YOUR_INSTANCE_ID.hello.atlassian-dev.net/x1/WEBTRIGGER_ID, em que YOUR_INSTANCE_ID é o identificador da instância do Jira Cloud e WEBTRIGGER_ID é o identificador exclusivo do endpoint do gatilho da Web gerado para seu app.
  2. Clique no botão Copiar URL ou copie o URL inteiro.

Configurar o sistema externo

  • Configure seu sistema externo que precisa buscar e-mails de usuários do Jira com a chave de API e o URL do gatilho da Web obtidos nas etapas anteriores.

  • URL do endpoint: o URL do webtrigger que você copiou.

  • Método HTTP: POST

  • Cabeçalhos obrigatórios:

    • Content-Type: application/json

    • X-Api-Key: YOUR_API_KEY

      Substitua YOUR_API_KEY pela chave de API definida ou gerada na seção Configurar a chave de API.

Exemplo de comando curl

Este exemplo demonstra a chamada do gatilho da Web User Identity Accessor for Jira Cloud, que aceita uma matriz de IDs de conta e retorna os endereços de e-mail.

curl --location --request POST 'https://YOUR_INSTANCE_ID.hello.atlassian-dev.net/x1/ENDPOINT_PATH' \
--header 'X-Api-Key: YOUR-API-KEY' \
--header 'Content-Type: application/json' \
--data-raw '{
   "accountIds": [
       "ACCOUNT_ID_1",
       "ACCOUNT_ID_2"
   ]
}'

Substitua:

  • YOUR_INSTANCE_ID com o ID da instância do Jira Cloud
  • ENDPOINT_PATH com o caminho do endpoint de API
  • YOUR_API_KEY com a chave de API que você definiu ou gerou na seção Configurar a chave de API
  • ACCOUNT_ID com os IDs das contas da Atlassian que você quer segmentar
Resposta esperada
[{"accountId":"ACCOUNT_ID_1","emailAddress":"EMAIL_ADDRESS_1"},
 {"accountId":"ACCOUNT_ID_2","emailAddress":"EMAIL_ADDRESS_2"}]

Substitua:

  • ACCOUNT_ID_X com IDs de contas da Atlassian reais
  • USER_EMAIL_X com endereços de e-mail de usuários retornados da chamada de API

Implementar práticas recomendadas de segurança

Para confirmar a segurança da sua chave de API, siga estas recomendações:

  • Armazene a chave de API com segurança na configuração do conector do Jira Cloud.
  • Verifique se toda a comunicação com o URL do webhook ocorre por HTTPS. Esse é o padrão para gatilhos da Web do User Identity Accessor for Jira Cloud.

Suporte para o User Identity Accessor do Jira Cloud

As ofertas de suporte estão disponíveis em Google para o app User Identity Accessor for Jira Cloud, que pode incluir manutenção e atualizações regulares para manter o app atualizado. Se você tiver problemas ou dúvidas específicas sobre a funcionalidade do app, entre em contato com o suporte doGoogle Cloud . Para mais informações, consulte Como receber suporte do Cloud Customer Care.