Use este guia se você administra um espaço de trabalho do ChatGPT ou usa o ChatGPT Plus ou Pro e está configurando o app Databricks Genie com o OAuth integrado ou o cliente OAuth da sua organização.
OAuth integrado: quando estiver disponível no ChatGPT e habilitado para seu espaço de trabalho do Databricks, use a conexão pré-configurada. Você não precisa criar um app OAuth nem inserir um ID ou segredo do cliente. Siga as instruções da seção OAuth integrado abaixo.
Cliente OAuth personalizado: use esta opção se o OAuth integrado não estiver disponível ou se sua organização exigir um cliente OAuth próprio. Siga as instruções da seção Cliente OAuth personalizado abaixo.
O que você vai configurar
Você vai criar uma conexão com o app Databricks para sua conta ou espaço de trabalho do ChatGPT. As duas opções exigem os dados do provedor Databricks solicitados no ChatGPT e permissões para os recursos que você pretende usar. Se você usa um cliente OAuth personalizado, prepare também:
Uma conexão de app OAuth do Databricks criada no Console da conta do Databricks.
O ID e o segredo do cliente OAuth do Databricks.
O URL de callback exato copiado do ChatGPT.
Escopos do Databricks correspondentes às funcionalidades do app que você quer habilitar.
Todos os dados do provedor Databricks solicitados pelo fluxo de configuração do ChatGPT, como host do espaço de trabalho, host da conta, ID da conta ou warehouse.
Antes de começar
Para configurar um espaço de trabalho, abra o console de administração, selecione o espaço de trabalho do ChatGPT desejado e abra Plugins. Selecione Gerenciar apps legados para abrir a página Apps, que continua disponível. Para saber como navegar pelo espaço de trabalho e acessar apps legados, consulte Controles de administração, segurança e conformidade para plugins e apps.
Você precisa de:
Acesso de administrador ou proprietário do espaço de trabalho do ChatGPT, ou uma conta do ChatGPT Plus ou Pro.
Para um cliente OAuth personalizado, acesso de administrador da conta do Databricks. O acesso de administrador do espaço de trabalho pode ser suficiente para algumas tarefas, mas as conexões de apps personalizados são configuradas no Console da conta do Databricks. Para o OAuth integrado, um administrador do Databricks deve verificar se o aplicativo ChatGPT está disponível e habilitado para seu espaço de trabalho.
Para um cliente OAuth personalizado, o Console da conta do Databricks aberto em uma aba separada.
Para um cliente OAuth personalizado, a tela de conexão do Databricks Genie aberta no ChatGPT para que você possa copiar o URL de callback exato.
Uma definição das funcionalidades de que o app precisa: Genie e painéis de IA/BI, acesso mais amplo às APIs do Databricks ou um app limitado às APIs do Databricks SQL. O acesso somente a SQL não é suficiente para ações do Genie ou de painéis.
Para um cliente OAuth personalizado, um local seguro para lidar com o segredo do cliente do Databricks.
Se sua conta ou espaço de trabalho do Databricks restringir o acesso por meio de uma lista de acesso por IP, controle de entrada baseado em contexto, firewall ou outra política de rede, ajuda de um administrador do Databricks que possa permitir os intervalos de IP de saída dos apps do ChatGPT atuais.
Para um cliente OAuth personalizado, copie o URL de callback exato exibido no ChatGPT.
Valores a preparar
Para um cliente OAuth personalizado, URL de callback: copie esse valor do fluxo de configuração do app no ChatGPT.
Para um cliente OAuth personalizado, o ID do cliente OAuth do Databricks.
Para um cliente OAuth personalizado, o segredo do cliente OAuth do Databricks.
Para um cliente OAuth personalizado, escopos de acesso do Databricks adequados às funcionalidades do app. Para uma nova conexão com o Genie ou painéis que exiba
ai-gateway,dashboardseoffline_access, prepare esses escopos. TODAS as APIs (all-apiscomoffline_access) continua sendo a alternativa mais antiga e abrangente. Use SQL apenas para um app limitado às APIs do Databricks SQL.Campos do espaço de trabalho ou da conta do Databricks solicitados pelo fluxo de configuração do ChatGPT.
OAuth integrado
Primeiro, cumpra os pré-requisitos acima. Use esta opção somente quando o OAuth integrado estiver disponível no ChatGPT e habilitado para seu espaço de trabalho do Databricks.
Peça a um administrador do Databricks para verificar se o aplicativo ChatGPT está disponível nas configurações de integrações de apps do Console da conta e habilitado para seu espaço de trabalho. Se o aplicativo ChatGPT não estiver listado no Console da conta do Databricks, entre em contato com o representante da sua conta no Databricks para saber se o recurso está disponível para sua conta.
No ChatGPT, mude para a conta ou o espaço de trabalho em que o app deve ficar disponível. Acesse Configurações > Plugins para uma configuração pessoal ou, como administrador ou proprietário do espaço de trabalho, acesse Console de administração > Plugins para configurar o espaço de trabalho.
Selecione Databricks Genie e, em seguida, Adicionar conexão de app.
Insira o Nome do host do espaço de trabalho (obrigatório) sem
https://nem um caminho de URL.A partir desse nome de host, o ChatGPT determina o endpoint MCP do Genie local ao espaço de trabalho:
https://<workspace-host>/ai-gateway/mcp-services/system.ai.genie_one_mcp. Não é necessário um endpoint MCP regional separado.Selecione Continuar, entre no Databricks e revise a solicitação de consentimento.
Prossiga com as seções Conectar e testar e Gerenciar acesso abaixo, incluindo os testes com membros autorizados e as verificações de acesso ao espaço de trabalho.
Cliente OAuth personalizado
Primeiro, atenda aos pré-requisitos acima. Use esta opção se o OAuth integrado não estiver disponível ou se sua organização exigir um cliente OAuth próprio. Após a configuração, conclua as etapas das seções Conectar e testar e Gerenciar o acesso abaixo.
Iniciar a configuração do OAuth personalizado no ChatGPT
No ChatGPT, mude para a conta ou o espaço de trabalho em que o app deve ficar disponível.
Acesse Configurações > Plugins para uma configuração pessoal ou, como administrador ou proprietário do espaço de trabalho, acesse Console de administração > Plugins para configurar o espaço de trabalho.
Selecione Databricks Genie em Diretório.
Selecione Adicionar conexão de app.
Na caixa de diálogo Conectar Databricks Genie, localize os campos ID do cliente OAuth e Segredo do cliente OAuth. Para usar o fluxo de cliente personalizado, basta inserir as credenciais nesses campos visíveis; não é necessário selecioná-lo separadamente.
Copie a URL de callback do ChatGPT. Mantenha essa caixa de diálogo aberta.
Exemplo de URL de callback:
https://chatgpt.com/connector/oauth/<callback_id>
Não remova o ID de callback, não adicione uma barra no final nem substitua a URL por uma URL genérica do ChatGPT. A URL registrada no Databricks deve corresponder exatamente à URL de callback exibida no ChatGPT.
Criar uma conexão de app OAuth personalizado no Databricks
Abra o Console da conta do Databricks correspondente à sua conta.
Na barra lateral esquerda, abra Configurações.
Abra a aba Conexões de apps.
Selecione Adicionar conexão.
Insira um nome para o aplicativo, como ChatGPT Databricks.
Em URLs de redirecionamento, cole o URL de callback exato copiado do ChatGPT.
Em Escopos de acesso, escolha os escopos de que o app precisa.
Para uma nova conexão com o Genie ou painéis que exiba
ai-gateway,dashboardseoffline_accessno ChatGPT, permita esses mesmos escopos no app OAuth do Databricks.TODAS as APIs continua sendo a alternativa mais antiga e abrangente para acesso geral às APIs do Databricks. Para essa configuração, use
all-apiseoffline_accessno ChatGPT e verifique se o app OAuth do Databricks permite ambos. Para uma nova conexão com o Genie ou painéis, dê preferência aos escopos granulares exibidos.Use SQL apenas para um app limitado às APIs do Databricks SQL. O acesso somente a SQL não é suficiente para ações do Genie ou de painéis.
Verifique se todos os escopos listados posteriormente no ChatGPT estão habilitados neste app OAuth do Databricks. O Databricks permite automaticamente openid, email, profile e offline_access para apps criados na interface.
Mantenha os TTLs dos tokens nos valores padrão do Databricks, a menos que sua organização tenha uma política específica: 60 minutos para o token de acesso e 10080 minutos para o token de atualização.
Ative Gerar um segredo do cliente. O ChatGPT precisa de um cliente OAuth confidencial para esse fluxo.
Crie a conexão.
Copiar credenciais do Databricks
Na caixa de diálogo Conexão criada, copie o ID do cliente.
Copie o Segredo do cliente imediatamente e armazene-o com segurança.
Se você fechar a caixa de diálogo antes de copiar o segredo, crie ou faça a rotação das credenciais do app OAuth e use o novo segredo.
O Databricks exibe o segredo apenas uma vez. Trate-o como uma credencial e não o inclua em capturas de tela, chamados, comentários ou conversas.
Concluir a configuração do OAuth personalizado no ChatGPT
Volte à caixa de diálogo Conectar Databricks Genie.
Insira o ID do cliente do Databricks em ID do cliente OAuth.
Insira o segredo do cliente do Databricks em Segredo do cliente OAuth.
Ao inserir essas credenciais, seu cliente OAuth personalizado será usado; não é necessário selecioná-lo separadamente.
Em Escopos (opcional), insira os escopos necessários para o endpoint do Databricks e os recursos do seu app. Use os mesmos escopos habilitados no app OAuth do Databricks.
Para uma nova conexão com o Genie/painéis que exiba
ai-gateway,dashboardseoffline_access, mantenha esses escopos. Verifique se o app OAuth do Databricks permite os mesmos escopos.ai-gatewayhabilita a conexão MCP do Genie local ao espaço de trabalho,dashboardshabilita ações em painéis de IA/BI eoffline_accesshabilita tokens de atualização.A alternativa mais antiga e abrangente,
all-apiseoffline_access, continua sendo compatível para um acesso mais amplo às APIs, mas não é a opção preferencial para essa conexão com o Genie/painéis. Se o app do Databricks permitir apenasall-apis, atualize-o ou recrie-o para permitirai-gateway,dashboardseoffline_access. Se os escopos granulares não estiverem disponíveis, configure explicitamente o ChatGPT para usarall-apiseoffline_accesse verifique se o app do Databricks permite ambos. Não solicite os três escopos granulares no ChatGPT se o app do Databricks permitir apenasall-apis.Insira um escopo por linha ou separe os escopos por vírgulas. Todos os escopos listados no ChatGPT devem estar habilitados no app OAuth do Databricks.
Insira o Nome do host do espaço de trabalho (obrigatório) sem https:// nem um caminho de URL. Preencha os demais campos obrigatórios do provedor Databricks exibidos no fluxo de configuração.
A partir desse nome de host, o ChatGPT determina o endpoint MCP do Genie local ao espaço de trabalho:
https://<workspace-host>/ai-gateway/mcp-services/system.ai.genie_one_mcp. Não é necessário um endpoint MCP regional separado.Selecione Continuar.
O ChatGPT solicita exatamente os escopos inseridos em Escopos (opcional). Ele não adiciona automaticamente escopos mais abrangentes do modelo de configuração.
Conectar e testar
Realize os testes de conexão e as verificações de acesso a seguir para qualquer uma das opções de OAuth.
Revise os detalhes, as ações e as configurações de autenticação do app.
Se você administra o espaço de trabalho, habilite o app para ele e configure quem pode usá-lo de acordo com a política do espaço de trabalho.
Inicie o fluxo de conexão no ChatGPT com um usuário de teste que tenha permissão e, em seguida, entre no Databricks.
Confirme se o navegador abre a conta ou o espaço de trabalho do Databricks esperado.
Revise os escopos solicitados e selecione Autorizar.
Verifique se o navegador retorna ao ChatGPT e se o app aparece como conectado.
Execute uma ação de leitura de baixo risco compatível com as funcionalidades da conexão. Para uma conexão com o Genie, envie uma solicitação ao Genie sobre dados que o usuário de teste tem permissão para acessar. Para outras funcionalidades compatíveis, obtenha informações do usuário atual ou consulte um recurso aprovado do Databricks SQL. Confirme se o usuário tem as permissões necessárias para os recursos do Databricks; os escopos OAuth, por si só, não concedem acesso aos dados.
Se as ações de gravação estiverem habilitadas, faça um teste com um fluxo de trabalho do Databricks claramente de baixo risco antes de ampliar a disponibilização.
Ao configurar um espaço de trabalho, peça a um membro com permissão, mas sem acesso de administrador, que se conecte e repita o teste de baixo risco.
Gerenciar o acesso
Tanto o Databricks quanto o ChatGPT contribuem para o controle de acesso.
No ChatGPT, os administradores do espaço de trabalho gerenciam a disponibilidade do app e como os membros podem usá-lo. No Business, os administradores gerenciam se o app está habilitado para todo o espaço de trabalho. Revise os controles de administração dos apps do Databricks (Configurações do espaço de trabalho > Apps ou Console de administração > Plugins > Gerenciar apps legados):
Acesso de usuários, para configurar quais funções do espaço de trabalho podem usar o app nos espaços de trabalho Enterprise e Edu compatíveis.
Controle de ações, para configurar quais ações do Databricks estão habilitadas.
Permissões do app, para configurar quando o ChatGPT pede confirmação aos membros antes de usar o app.
Essas permissões do app se aplicam às conversas do ChatGPT. Os agentes do espaço de trabalho usam controles individuais definidos por quem criou cada agente para determinar quais ações de apps estão disponíveis e quando os usuários finais devem aprová-las. Para saber mais sobre o comportamento dos agentes, consulte: Agentes do espaço de trabalho do ChatGPT para Enterprise e Business.
No Databricks, os administradores gerenciam quais usuários podem autorizar o app OAuth e quais recursos do Databricks esses usuários podem acessar. As permissões do provedor continuam valendo após a habilitação do app no ChatGPT.
Para saber como navegar pelo espaço de trabalho, acessar apps e usar os controles de apps específicos de cada plano, consulte: Controles de administração, segurança e conformidade em apps.
Solução de problemas na configuração do app Databricks
URI de redirecionamento incompatível: se você usa um cliente OAuth personalizado, confirme se o valor de URLs de redirecionamento no Databricks corresponde exatamente ao URL de callback exibido no ChatGPT, incluindo o caminho e o ID de callback. Não remova o ID de callback, não adicione uma barra ao final nem substitua o URL por outro URL de redirecionamento do ChatGPT.
Segredo ausente: se você usa um cliente OAuth personalizado, os segredos do Databricks são exibidos apenas uma vez. Gere um novo segredo do cliente se ele não tiver sido copiado.
App OAuth não disponível imediatamente: segundo o Databricks, as atualizações de aplicativos OAuth podem levar até 30 minutos para serem processadas.
Escopo insuficiente ou incompatível: se você usa um cliente OAuth personalizado, compare os Escopos (opcional) no ChatGPT com os Escopos de acesso no app OAuth do Databricks. Todos os escopos solicitados pelo ChatGPT devem estar habilitados no app. Confirme se os escopos são compatíveis com o endpoint e as funcionalidades que você usa.
Para uma nova conexão com o Genie ou painéis que exiba
ai-gateway,dashboardseoffline_access, mantenha esses escopos no ChatGPT e verifique se o app do Databricks permite os três. Se o app permitir apenasall-apis, atualize-o ou recrie-o para permitir os três escopos granulares.Se os escopos granulares não estiverem disponíveis, use a alternativa mais ampla compatível: configure o ChatGPT com
all-apiseoffline_accesse verifique se o app do Databricks permite ambos. Um app que permite apenasall-apisnão atende a uma solicitação do ChatGPT paraai-gateway,dashboardseoffline_access. O acesso somente a SQL é adequado apenas para um app limitado às APIs do Databricks SQL; ele não é suficiente para ações do Genie ou de painéis.Falha nas ações SQL: para um app limitado às APIs do Databricks SQL, confirme o escopo SQL, a configuração do warehouse e as permissões do Databricks.
Espaço de trabalho do ChatGPT incorreto: crie e habilite o app no mesmo espaço de trabalho do ChatGPT em que os usuários vão conectá-lo.
Conta ou espaço de trabalho do Databricks incorreto: confirme o valor de Nome do host do espaço de trabalho (obrigatório), repita o fluxo de login e verifique se o Databricks abre a conta ou o espaço de trabalho esperado.
Os usuários não conseguem se conectar: confirme se o usuário tem acesso ao Databricks e permissão para autorizar o app OAuth. No Business, confirme se o app está habilitado para todo o espaço de trabalho. Nos espaços de trabalho Enterprise e Edu compatíveis, confirme também se o Acesso de usuários do ChatGPT permite o uso do app.
A política de rede do Databricks bloqueia o app: se o Databricks permitir apenas IPs de origem específicos, um administrador do Databricks deverá atualizar as listas de acesso por IP da conta ou do espaço de trabalho, os controles de entrada baseados em contexto, o firewall ou outras regras de rede pertinentes controladas pelo cliente.
Permita conexões de entrada provenientes dos intervalos de IP de saída dos apps do ChatGPT atuais.
Configure essa lista de permissões no Databricks ou na camada de rede controlada pelo cliente. Ela é independente da lista de IPs permitidos do espaço de trabalho do ChatGPT.
Os intervalos publicados podem mudar. Sempre que possível, automatize as atualizações a partir do JSON.
Não faça a rotação do segredo do cliente nem altere os escopos OAuth para contornar um bloqueio de rede. Primeiro, confirme se o Databricks está rejeitando os IPs de origem do app.