\
--json '{"permissions": ["USER"]}'
```
Use `USER`, não `ADMIN`. O Devin não precisa ser admin do workspace.
## Etapa 2: Conecte o Devin à entidade de serviço
Siga **uma** das duas opções abaixo. Cada uma é completa por si só: instala a CLI do Databricks por meio de um [blueprint](/pt-BR/onboard-devin/environment/blueprints) em **Configurações > Ambiente > Blueprints** e configura a CLI para autenticar como a entidade de serviço criada na Etapa 1.
* [**Opção A: client secret do OAuth**](#option-a-oauth-client-secret). [OAuth M2M](https://docs.databricks.com/aws/en/dev-tools/auth/oauth-m2m) padrão: a entidade de serviço recebe um client secret, que você armazena nos Secrets do Devin. É a forma mais rápida de começar.
* [**Opção B: federação de tokens OIDC**](#option-b-oidc-token-federation). Cada sessão do Devin pode gerar um token OpenID Connect de curta duração assinado pelo Devin. A [federação de tokens](https://docs.databricks.com/aws/en/dev-tools/auth/oauth-federation) do Databricks permite que a entidade de serviço confie nesse issuer, de modo que o Devin troca seu próprio token de identidade por um token OAuth do Databricks. Nenhum segredo do Databricks chega a ser criado ou armazenado, e é por isso que o Databricks recomenda fortemente essa abordagem para cargas de trabalho automatizadas.
Personal access tokens (PATs) vinculados a um human user não são recomendados em nenhuma das opções. Eles contornam a entidade de serviço, expiram de forma imprevisível e atribuem as ações do Devin a uma pessoa.
### Opção A: client secret OAuth
Prefere não gerenciar nenhum segredo do Databricks? Vá direto para a [Opção B: federação de tokens OIDC](#option-b-oidc-token-federation). Você também pode começar por aqui e mudar depois: troque para o blueprint da Opção B, crie a policy de federação e, em seguida, exclua o segredo OAuth e o Devin Secret `DATABRICKS_CLIENT_SECRET`.
#### 1. Gere um segredo OAuth
No console da conta, abra a entidade de serviço da Etapa 1 e gere um **segredo OAuth**. Defina o menor tempo de vida compatível com seu processo de rotação (o máximo é 730 dias) e restrinja o segredo aos escopos de API de que o Devin precisa, como `sql`, `jobs` e `unity-catalog`. Evite selecionar todos os escopos.
#### 2. Adicione os Devin Secrets
No Devin, adicione os itens a seguir como [Devin Secrets](/pt-BR/product-guides/secrets) na aba **Secrets** do blueprint que você editará em seguida (organização ou repositório):
| Segredo | Valor |
| -------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `DATABRICKS_HOST` | A URL do **workspace** em que o Devin deve atuar, por exemplo `https://dbc-xxxx.cloud.databricks.com` ou `https://adb-xxxx.azuredatabricks.net`, sem o sufixo `/api`. Não é o host `accounts.*`. |
| `DATABRICKS_CLIENT_ID` | O `applicationId` da entidade de serviço (um UUID) obtido na Etapa 1, e não o `id` numérico |
| `DATABRICKS_CLIENT_SECRET` | O segredo OAuth que você gerou |
A CLI seleciona o OAuth M2M automaticamente quando há um client ID e um client secret, portanto `DATABRICKS_AUTH_TYPE` não é obrigatório. Defina-o como `oauth-m2m` apenas se quiser descartar explicitamente todos os outros métodos.
Os segredos são injetados como variáveis de ambiente no início de cada nova sessão, então a CLI não precisa de um arquivo de perfil. Um segredo rotacionado passa a valer na próxima sessão, sem necessidade de rebuild.
#### 3. Adicione o blueprint
Instala apenas a CLI. A autenticação é feita inteiramente pelos três segredos acima.
```yaml theme={null}
initialize:
- name: Install Databricks CLI
run: |
sudo rm -f /usr/local/bin/databricks
curl -fsSL https://raw.githubusercontent.com/databricks/setup-cli/main/install.sh | sudo sh
databricks --version
knowledge:
- name: databricks-auth
contents: |
The `databricks` CLI authenticates as a service principal using the DATABRICKS_HOST,
DATABRICKS_CLIENT_ID, and DATABRICKS_CLIENT_SECRET environment variables, which are
provided as Devin Secrets. Do not run `databricks auth login`, do not set DATABRICKS_TOKEN,
and do not ask for a personal access token. Check auth with `databricks current-user me`.
Write only to the devin_dev catalog; production catalogs are read-only. Ship notebook and
job changes through a pull request.
```
Não grave os segredos em um arquivo durante o `initialize`; tudo o que for escrito ali fica embutido no snapshot.
Também não defina `DATABRICKS_TOKEN` nem deixe um perfil `~/.databrickscfg` no snapshot. Credenciais conflitantes são a causa mais comum de falha na autenticação M2M.
#### 4. Faça o build do snapshot
Salve o blueprint e aguarde o build exibir **Success**; em seguida, inicie uma nova sessão. As sessões existentes mantêm o snapshot antigo. Prossiga para a [Etapa 3](#step-3-grant-permissions).
### Opção B: federação de tokens OIDC
As sessões do Devin emitem tokens de identidade de curta duração (`iss`, `sub`, `aud`), e uma policy de federação na entidade de serviço instrui o Databricks a confiar neles. O blueprint instala a CLI `devin-oidc`, encapsula o `databricks` para que cada chamada leve um token novo e grava um perfil que aponta para a sua entidade de serviço. Em seguida, você lê as claims do token em uma sessão e cria uma policy que corresponda a elas.
Quer o caminho mais curto primeiro? Comece pela [Opção A](#option-a-oauth-client-secret) e volte aqui quando estiver pronto para abrir mão do segredo armazenado.
#### 1. Adicione o blueprint
Dois espaços reservados no perfil devem ser substituídos pelos seus próprios valores:
| Espaço reservado | Substitua por |
| ----------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `` | A URL do **workspace** em que o Devin deve trabalhar, por exemplo `https://dbc-xxxx.cloud.databricks.com` ou `https://adb-xxxx.azuredatabricks.net`, sem o sufixo `/api`. Não é o host `accounts.*`. É o mesmo valor de `DATABRICKS_HOST` na Opção A. |
| `` | O `applicationId` da entidade de serviço (um UUID) exibido na saída de `databricks account service-principals create` na Etapa 1. Não é o `id` numérico, que serve apenas para anexar a policy de federação. |
```yaml theme={null}
initialize:
- uses: github.com/CognitionAI/actions/setup-devin-oidc@main
- name: Install Databricks CLI
run: |
sudo rm -f /usr/local/bin/databricks
curl -fsSL https://raw.githubusercontent.com/databricks/setup-cli/main/install.sh | sudo sh
sudo mv /usr/local/bin/databricks /usr/local/bin/databricks-bin
- name: Wrap the CLI so each call carries a fresh Devin OIDC token
run: |
sudo tee /usr/local/bin/databricks > /dev/null <<'EOF'
#!/usr/bin/env bash
set -euo pipefail
DATABRICKS_OIDC_TOKEN="$(devin-oidc token --audience "${DATABRICKS_DEVIN_AUDIENCE:-databricks}")"
export DATABRICKS_OIDC_TOKEN
exec /usr/local/bin/databricks-bin "$@"
EOF
sudo chmod +x /usr/local/bin/databricks
- name: Write Databricks CLI profile
run: |
cat > ~/.databrickscfg <<'EOF'
[DEFAULT]
host =
auth_type = env-oidc
client_id =
audience = databricks
EOF
chmod 600 ~/.databrickscfg
knowledge:
- name: databricks-auth
contents: |
The `databricks` CLI is preconfigured to authenticate as a service principal through
Devin OIDC token federation. Do not run `databricks auth login`, do not set
DATABRICKS_TOKEN, and do not ask for a personal access token. Check auth with
`databricks current-user me`. Write only to the devin_dev catalog; production catalogs
are read-only. Ship notebook and job changes through a pull request.
```
| Componente | Finalidade |
| ---------------------- | ------------------------------------------------------------------------------------------------------------- |
| `setup-devin-oidc` | Instala a CLI `devin-oidc`, que emite tokens de identidade do Devin ([detalhes](/pt-BR/product-guides/oidc)). |
| Wrapper | Os tokens de identidade do Devin expiram após 60 segundos, então cada chamada da CLI emite o seu próprio. |
| `auth_type = env-oidc` | Fixa a CLI na federação de tokens, de modo que ela nunca recorra a um PAT ou a login interativo. |
| `host` / `client_id` | A URL do workspace e o `applicationId` da entidade de serviço da tabela acima. |
| `audience` | O audience que o wrapper solicita e que você vai informar na policy de federação abaixo. |
| `knowledge` | Informa ao Devin que a CLI já está autenticada, para que ele não tente executar `databricks auth login`. |
O perfil não contém nenhum segredo, portanto é seguro gravá-lo durante o `initialize`. Se você estiver migrando da Opção A, remova o Devin Secret `DATABRICKS_CLIENT_SECRET` assim que a policy abaixo estiver configurada, para que a CLI não encontre duas credenciais.
#### 2. Faça o build do snapshot
Salve o blueprint e aguarde até que o build exiba **Success**. Nada no blueprint depende da policy de federação que você vai criar em seguida, portanto não será necessário refazer o build depois.
#### 3. Crie a policy de federação
Com o blueprint construído, as sessões do Devin podem emitir tokens de identidade. Use um deles para ler exatamente em quais claims o Databricks precisa confiar e, em seguida, crie na entidade de serviço uma policy de federação que corresponda a elas.
Inicie uma nova sessão do Devin e peça que ele execute o comando a seguir. Ele imprime apenas as claims de identidade do token, nunca o token em si.
```bash theme={null}
devin-oidc token --audience databricks | python3 -c '
import sys, json, base64
p = sys.stdin.read().strip().split(".")[1]
c = json.loads(base64.urlsafe_b64decode(p + "=="))
print(json.dumps({k: c[k] for k in ("iss", "sub", "aud")}, indent=2))'
```
Formato esperado:
```json theme={null}
{
"iss": "https://app.devin.ai",
"sub": "org_id:",
"aud": "databricks"
}
```
Em deployments enterprise, `iss` é a sua URL personalizada do Devin (por exemplo, `https://yourcompany.devinenterprise.com`). Copie `iss` e `sub` exatamente como foram impressos. Não cole o token bruto em tickets ou documentos; ele é uma credencial bearer válida pelos próximos 60 segundos.
Salve isto como `devin-federation-policy.json`, substituindo os valores da etapa anterior:
```json theme={null}
{
"description": "Allow Devin sessions to authenticate as the devin-sessions service principal",
"oidc_policy": {
"issuer": "https://",
"audiences": ["databricks"],
"subject": "org_id:"
}
}
```
Os três campos exigem correspondência exata:
* `issuer` deve ser igual ao `iss` do token, incluindo o esquema e sem barra no final.
* `audiences` deve incluir a audience que o Devin solicita (`databricks`, neste guia).
* `subject` deve ser igual ao `sub` do token. O subject padrão é o ID da sua organização, portanto todas as sessões da organização podem se autenticar como esse principal. Essa é a granularidade adequada para o Databricks, porque as policies de federação comparam o subject como uma string literal. Claims por sessão, como `devin_id`, mudam a cada sessão e não podem ser correspondidas por uma policy estática.
Deixe `subject_claim`, `jwks_uri` e `jwks_json` sem definição. O Databricks usa por padrão a claim `sub` e descobre o JWKS a partir do `/.well-known/openid-configuration` do issuer.
```bash theme={null}
databricks account service-principal-federation-policy create \
--policy-id devin-sessions \
--json @devin-federation-policy.json
```
Confirme que ela existe:
```bash theme={null}
databricks account service-principal-federation-policy list
```
O perfil que o blueprint escreveu já aponta para essa entidade de serviço, então não é preciso reconstruir nada. Continue para a [Etapa 3](#step-3-grant-permissions).
### Rebuilds e fixação de versão
Tanto o script de instalação do Databricks quanto o `setup-devin-oidc@main` acompanham seus branches `main` upstream, ou seja, um build completo incorpora novas versões; já um [build diferencial](/pt-BR/onboard-devin/environment/differential-builds) pula o `initialize` e mantém as versões já presentes no snapshot até que o blueprint seja alterado. Se você precisa de builds reproduzíveis, baixe o instalador a partir de uma tag de versão em vez de `main` (por exemplo, `.../databricks/setup-cli/v1.17.0/install.sh`), o que instala exatamente aquela versão do CLI, e fixe a GitHub Action em um SHA de commit (`setup-devin-oidc@`).
## Etapa 3: Conceder permissões
A autenticação apenas comprova quem é o Devin. O que o Devin pode ver ou alterar é definido pelas permissões do workspace e pelas concessões do Unity Catalog, que você pode ajustar a qualquer momento sem mexer no blueprint. Comece com o perfil mais restrito que atenda ao trabalho e amplie de forma deliberada.
### Perfis de permissão
| Perfil | Trabalho típico | Concessões no Unity Catalog | Permissões no workspace |
| ------------------------- | --------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------- |
| **Explore** (comece aqui) | Responder perguntas sobre dados, documentar schemas, investigar jobs que falharam, propor correções de query em um PR | `USE CATALOG`, `USE SCHEMA`, `SELECT`, `BROWSE` nos catálogos de produção; `READ VOLUME` onde o Devin precisar de arquivos | `CAN USE` em um SQL warehouse; `CAN VIEW` nos jobs e pipelines que o Devin deve investigar |
| **Build** | Prototipar tabelas, funções e notebooks em um sandbox; executar testes com dados reais em modo somente leitura | Concessões do Explore em produção, mais a propriedade (ou `ALL PRIVILEGES`) de um catálogo ou schema `devin_dev` dedicado | Permissões do Explore, mais `CAN MANAGE RUN` nos jobs de sandbox e uma policy de cluster restritiva caso o Devin possa iniciar computação |
| **Operate** | Reexecutar ou reparar jobs de produção específicos depois que Explore e Build estiverem comprovados | Concessões do Explore, mais `MODIFY` nas tabelas específicas em que um job escreve | `CAN MANAGE RUN` nos jobs específicos, concedido job a job em vez de para todo o workspace |
Os statements de concessão apontam para a entidade de serviço pelo seu ID de aplicação:
```sql theme={null}
-- Explore: somente leitura no catalog de análises de produção
GRANT USE CATALOG, BROWSE ON CATALOG analytics TO ``;
GRANT USE SCHEMA, SELECT ON SCHEMA analytics.gold TO ``;
GRANT READ VOLUME ON VOLUME analytics.gold.landing TO ``;
-- Build: um catalog de sandbox pertencente ao Devin, isolado da produção
CREATE CATALOG IF NOT EXISTS devin_dev;
ALTER CATALOG devin_dev OWNER TO ``;
```
Se você preferir administração baseada em grupos, adicione a entidade de serviço a um grupo como `devin-agents` e conceda as permissões ao grupo.
Alterações de código devem continuar passando por pull requests. O Devin pode ler dados de produção para entender um problema e validar uma correção no sandbox, mas a alteração no notebook, na definição de job ou no Asset Bundle é aplicada por meio do seu processo normal de revisão, e não editando a produção diretamente.
## Etapa 4: Instale o plugin de skills do Databricks (opcional)
O Databricks publica [Agent Skills](https://github.com/databricks/databricks-agent-skills) que ensinam aos coding agents os fluxos de trabalho do Databricks: Asset Bundles, jobs, SQL, Unity Catalog e Spark. Instalá-los como um [plugin](/pt-BR/product-guides/plugins) do Devin dá ao Devin esse conhecimento, além da CLI.
1. Abra **Customize → Plugins** e escolha **Add plugin → From repository**.
2. Informe o repositório `databricks/databricks-agent-skills` e o subdiretório `plugins/databricks/claude`. O manifest do plugin fica nessa subpasta, portanto a instalação a partir do repository root retorna **No plugin manifest found**.
3. Instale no escopo **Organization** caso tenha usado um blueprint de organização na Etapa 2. Se usou um blueprint de repositório, declare o plugin no `.devin/config.json` desse repositório (consulte [herança e níveis](/pt-BR/cli/extensibility/plugins/overview#inheritance-and-levels)), assim apenas as sessões que têm a CLI também recebem as skills.
4. [Fixe o plugin em um commit](/pt-BR/product-guides/plugins#pinning-a-plugin) assim que ele estiver funcionando, para que mudanças upstream não cheguem às suas sessões sem revisão.
A skill principal do plugin recomenda executar `databricks auth login` para configurar um perfil. Esse fluxo interativo no navegador não pode ser concluído em uma sessão do Devin sem supervisão, e não é necessário aqui: a entrada `knowledge` da Etapa 2 informa ao Devin que a CLI já está autenticada.
## Etapa 5: Verificar
Inicie uma nova sessão (após o build do blueprint ser concluído com sucesso) e peça ao Devin para executar:
```bash theme={null}
databricks --version
databricks current-user me
```
`current-user me` deve retornar a entidade de serviço, com `userName` igual ao ID de aplicação. Para confirmar qual método de autenticação a CLI escolheu:
```bash theme={null}
databricks auth describe
```
Na Opção A, isso retorna `oauth-m2m`; na Opção B, `env-oidc`.
Uma autenticação bem-sucedida não significa que o Devin consegue acessar seus dados. Confirme que as concessões da Etapa 3 estão em vigor:
```bash theme={null}
databricks catalogs list
databricks warehouses list
databricks grants get catalog
```
Substitua `` por um catálogo que você concedeu na Etapa 3 (os exemplos ali usam `analytics`). Em seguida, peça ao Devin para executar uma pequena consulta somente leitura em um warehouse no qual ele tenha `CAN USE` e, caso você tenha configurado um perfil de Build, para criar e remover uma tabela em `devin_dev`. Uma consulta a uma tabela de produção na qual o Devin não tenha `SELECT` deve falhar; essa falha mostra o limite de permissão funcionando.
## Solução de problemas
| Sintoma | Aplica-se a | Causa e solução |
| ------------------------------------------------------------------------- | ----------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Erros sobre credenciais conflitantes ou mais de um método de autenticação | Opção A | Remova `DATABRICKS_TOKEN`, `DATABRICKS_USERNAME` e qualquer perfil em `~/.databrickscfg`. A CLI se recusa a adivinhar quando há mais de um método de autenticação configurado. |
| `DATABRICKS_OIDC_TOKEN` não definido ou vazio | Opção B | O wrapper foi ignorado ou não foi instalado. Confirme que `which databricks` aponta para o wrapper e que `devin-oidc token --audience databricks` funciona sozinho. |
| `invalid_grant` ou um erro mencionando o subject | Opção B | O `subject` da policy não é exatamente igual ao `sub` do token. Execute novamente o script de claims da etapa 2 e compare caractere por caractere. |
| Erro mencionando a audience | Opção B | O campo `audiences` da policy não inclui a audience que o wrapper solicita. Ambos usam `databricks` por padrão; mantenha-os idênticos. |
| Erro mencionando o issuer, o JWKS ou a assinatura | Opção B | O `issuer` tem um erro de digitação (barra no final, `http`, host incorreto) ou o Databricks não consegue acessar `https:///.well-known/jwks.json`. Abra essa URL de fora da sua rede para confirmar que ela é pública. |
| Token expirado | Opção B | Os tokens de identidade do Devin duram 60 segundos. Use o wrapper em vez de gerar um token manualmente. |
| A CLI não reconhece `env-oidc` | Opção B | O snapshot tem uma CLI antiga (ou o pacote Python legado `databricks-cli`). Remova o pacote antigo do blueprint e refaça o build. |
| Autenticado, mas `catalogs list` está vazio ou uma query é negada | Ambos | O principal está autenticado, mas não autorizado. Verifique a atribuição de workspace (etapa 1) e as concessões do Unity Catalog (etapa 3) com `databricks grants get catalog `. |
| Timeouts de conexão ou falhas de DNS | Ambos | O host do workspace não está acessível a partir do Devin. Adicione-o (e o host da conta, se necessário) à [network policy](/pt-BR/product-guides/security-profiles) do seu Devin. |
## Suporte
Para a configuração no lado do Databricks (entidades de serviço, segredos OAuth, policies de federação, Unity Catalog), consulte a [documentação de autenticação do Databricks](https://docs.databricks.com/aws/en/dev-tools/auth/) (alterne para a edição Azure ou GCP conforme necessário). Para a configuração no lado do Devin (blueprints, OIDC, plugins, network policy), entre em contato com [support@cognition.ai](mailto:support@cognition.ai) ou com a sua equipe de conta.