Configuração do Jira Cloud

Acesso antecipado:os recursos de pesquisa e ações federadas estão em Acesso antecipado. Esse recurso está sujeito aos "Termos das ofertas pré-GA" na seção Termos gerais de serviço dos Termos específicos de serviço. Os recursos pré-GA estão disponíveis "no estado em que se encontram" e podem ter suporte limitado. Para mais informações, consulte as descrições da fase de lançamento.

Nesta página, descrevemos como 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 Play Console e receber 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).

6. No campo URL de callback, insira https://vertexaisearch.cloud.google.com/console/oauth/jira_oauth.html.

7. Clique em Salvar alterações.

Obter o ID do cliente e a chave secreta do cliente

Para conseguir o ID 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 de 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).

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 no ícone 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.

   

   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.

   

   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.

   

   Administrador de acesso de 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.

   

   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.

   

   Gerenciar conta

4. Acesse Perfil e visibilidade.

   

   Perfil e visibilidade

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

   

   Entre em 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

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.

   Observação: depois de adicionar a API Jira, o botão Configurar pode levar um tempo para aparecer. Se ele não aparecer imediatamente, tente atualizar a página ou espere alguns segundos.

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	Necessário para buscar e mostrar resultados da pesquisa e detalhes do usuário em tempo real.
	write:jira-work	Permite que o assistente modifique itens de trabalho (por exemplo, atualize campos de problemas) e gerencie comentários ou problemas.
Somente pesquisa federada	read:jira-user, read:jira-work	Obrigatório para pesquisar e visualizar problemas, projetos e perfis de usuário.
Ingestão de dados e ações	read:jira-work	Obrigatório para rastreamento e indexação de dados abrangentes de itens de trabalho.
	write:jira-work	Necessário para realizar ações de gravação (criação, atualizações, comentários) em itens de trabalho no ambiente ingerido.
Ingestão de dados	read:jira-work	Necessário para rastrear e indexar o conteúdo do Jira para disponibilidade de pesquisa.

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

2. Acesse a guia Escopos granulares.

3. Clique em Editar escopos e selecione os escopos granulares de acordo com sua necessidade na tabela a seguir:

Modo de conexão	Permissão	Finalidade
Pesquisa e ações federadas	write:comment:jira	Permite que o assistente poste novos comentários ou respostas diretamente na interface de pesquisa.
	write:issue:jira	Necessário para criar novos problemas ou fazer edições importantes nos atuais.
Ingestão de dados e ações	read:user:jira, read:group:jira, read:avatar:jira	Necessário para sincronizar metadados de usuários/grupos e mostrar perfis de usuários.
	read:issue-security-level:jira, read:issue-security-scheme:jira	Essencial para o controle de acesso, garante que os dados ingeridos respeitem os limites de segurança do Jira.
	read:audit-log:jira	Usado para rastrear mudanças e realizar sincronizações incrementais para manter os dados ingeridos atualizados.
	write:comment:jira	Necessário para adicionar comentários a problemas usando o Google Assistente.
	write:issue:jira	Permite criar ou modificar problemas.
Ingestão de dados	read:user:jira, read:group:jira, read:avatar:jira	Necessário para rastrear e indexar conteúdo do Jira e relacionamentos de usuários.
	read:issue-security-level:jira, read:issue-security-scheme:jira	Necessário para mapear permissões e permitir que apenas usuários autorizados pesquisem os dados ingeridos.
	read:audit-log:jira	Necessário para que o mecanismo de sincronização identifique quais itens foram atualizados ou excluídos.

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

Observação: se você quiser pular ações e usar o repositório de dados para pesquisa, limite as permissões apenas a read. As permissões write são necessárias apenas para realizar as ações mencionadas em Ações compatíveis.

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 Developer Console.

2. Revise as permissões Ler endereço de e-mail e Escopo de armazenamento do app e clique em Fazer o download app.

   

   Revisar permissões e fazer o download do app

3. Na lista Selecione um site para instalar este app, escolha o site do Jira em que você quer instalar o app. Essa lista mostra apenas os sites em que você tem acesso de administrador.

   Observação: é necessário ser administrador de pelo menos um site do Jira para instalar o app.

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

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.

   

   Configurar o app User Identity Accessor para 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 gatilho da Web 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.

     

     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.

     

     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.

Observação: a chave de API gerada ou criada nesta seção serve como valor para o campo Chave secreta do cliente do Jira Identity Sync Forge na seção Opções avançadas durante a configuração do conector.

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 de 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 webtrigger 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.