Configure o OAuth M2M para ingestão do SharePoint

Para a maioria dos usuários, o Databricks recomenda OAuth U2M: gerenciado pelo Databricks, que não exige registro de aplicativo do Azure e é gerenciado inteiramente pelo Databricks. Use M2M para pipelines de produção totalmente automatizados que são executados sem interação do usuário.

Qual modelo de permissões devo usar?

A autenticação M2M suporta os seguintes modelos de permissão no Microsoft Azure:

• Sites.Read.All : Concede acesso a todos os sites do SharePoint em sua organização. Esta opção tem menos etapas de configuração, mas oferece um acesso mais amplo.
• Sites.Selected : Concede acesso somente a sites específicos do SharePoint. Isso requer configuração adicional, mas segue o princípio do menor privilégio.

Databricks recomenda o uso de Sites.Selected sempre que possível para limitar o acesso da entidade de serviço apenas aos sites que você precisa ingerir.

Qual tipo de credencial devo usar?

A autenticação M2M suporta os seguintes tipos de credenciais para a aplicação Microsoft Entra ID:

• Certificado : um certificado X.509 e sua key privada.
• Segredo do cliente : uma strings secreta que você gera no portal do Azure.

A Databricks recomenda usar um certificado. Uma conexão usa um tipo de credencial, seja um certificado ou um segredo do cliente.

Pré-requisitos

• Privilégios de administrador em seu tenant Microsoft Entra ID.

Sites.Read.All permissões

Esta opção concede à entidade de serviço acesso a todos os sites do SharePoint em sua organização.

Passo 1: Obtenha o ID do site do SharePoint

1. Acesse o site do SharePoint desejado em seu navegador.
2. Adicione /_api/site/id à URL.
3. Digite Enter .

Etapa 2: Obter nomes de unidades do SharePoint (opcional)

Se você deseja importar todas as unidades e documentos do seu site do SharePoint, ignore esta etapa. Se você deseja importar apenas um subconjunto das unidades, precisa coletar seus nomes.

Os nomes das unidades estão listados no menu à esquerda. Em cada site, existe uma unidade default chamada Documentos . No entanto, sua organização pode ter unidades adicionais. Por exemplo, as unidades na seguinte captura de tela incluem doclib1, subsite1doclib1 e mais.

Algumas unidades podem estar ocultas na lista. O criador da unidade pode configurar isso nas configurações da unidade. Nesse caso, unidades ocultas podem ficar visíveis na seção Conteúdo do site .

o passo 3: Crie um aplicativo Microsoft Entra ID

Este passo cria um registro de aplicativo que pode acessar os arquivos do SharePoint usando uma entidade de serviço.

1. No portal do Microsoft Azure (https://portal.azure.com), Clique em ID do Microsoft Entra . Você talvez precise pesquisar por "Microsoft Entra ID".

   

2. Na barra lateral esquerda, na seção Gerenciar , clique em Registros de Aplicativos .

3. Clique em Novo registro .

   

4. No formulário de inscrição , especifique o seguinte:

   • Um nome para sua aplicação (por exemplo, "Databricks SharePoint Ingestion").
   • Se você deseja que outros inquilinos acessem este aplicativo.

   Não é necessário especificar um URL de redirecionamento para autenticação M2M.

5. Clique em registrar . Você será redirecionado para a página de detalhes do aplicativo.

6. Anote os seguintes valores:

   • ID da aplicação (cliente)
   • ID do diretório (tenant)

Em seguida, adicione uma credencial de cliente ao aplicativo. Siga os passos para o tipo de credencial que você escolheu. Consulte Qual tipo de credencial devo usar?.

Certificate

A conexão requer um certificado X.509 em formato PEM e uma key privada RSA não criptografada em formato PKCS #8 PEM. Chaves privadas criptografadas não são suportadas.

1. Gere um certificado e uma key privada. Por exemplo, o comando OpenSSL a seguir cria um certificado autoassinado válido por dois anos:

   Bash

   openssl req -x509 -newkey rsa:2048 -sha256 -days 730 -nodes \
     -keyout ~/databricks_key.pem -out ~/databricks_cert.pem \
     -subj "/CN=databricks-sharepoint"

   O comando cria databricks_cert.pem (o certificado público) e databricks_key.pem (a key privada) em seu diretório home. Você também pode usar um certificado emitido pela autoridade de certificação da sua organização.

2. Se o senhor estiver usando uma key privada de outra fonte, confirme se o arquivo começa com o delimitador BEGIN PRIVATE KEY . Se ele começar com o delimitador BEGIN RSA PRIVATE KEY , converta-o para o formato PKCS #8 e use o arquivo convertido como key privada:

   Bash

   openssl pkcs8 -topk8 -nocrypt -in <private-key-file> -out ~/databricks_key.pem

3. Na barra lateral esquerda da página de registro do aplicativo, em Gerenciar , clique em Certificados e segredos .

4. Clique na tab Certificados .

5. Clique em Upload certificado .

6. Selecione databricks_cert.pem, adicione uma descrição e clique em Adicionar .

   

7. Armazene o arquivo de key privada com segurança. Você insere o certificado e a key privada ao criar a conexão.

Os certificados expiram. Antes que o certificado expire, upload de um novo certificado para o aplicativo e atualize a conexão com o novo certificado e a key privada.

Client secret

1. Clique em Credenciais do cliente: Adicionar um certificado ou segredo .

2. Clique em + Novo segredo do cliente .

   

3. Adicione uma descrição.

4. Clique em Adicionar . A lista atualizada de segredos do cliente é exibida.

5. Copie o valor secreto do cliente e armazene-o em local seguro. Depois de sair da página, você não poderá mais acessar o segredo do cliente.

o passo 4: Configurar permissões API

Conceda ao aplicativo as permissões necessárias para ler os arquivos do SharePoint.

1. Na página de registro do aplicativo, clique em "Permissões da API" no menu à esquerda.

2. Clique em + Adicionar uma permissão .

3. No painel de permissões API de solicitação , clique em Microsoft gráfico .

4. Clique em Permissões do aplicativo .

5. Procure e selecione as seguintes permissões:

   • Sites.Leia.Tudo
   • Arquivos.Ler.Tudo

6. Clique em Adicionar permissões .

7. Clique em Conceder permissão de administrador para [sua organização] .

8. Clique em Sim para confirmar.

   A lista de permissões exibe uma marca de seleção verde na coluna Status , indicando que o consentimento do administrador foi concedido.

o passo 5: Criar uma conexão no Databricks

1. No Explorador de Catálogo, clique em Dados externos no menu à esquerda.

2. Clique em Criar conexão .

3. Na caixa de diálogo Criar conexão , especifique o seguinte:

   • Nome da conexão : Um nome exclusivo para sua conexão.
   • Tipo de conexão : Microsoft SharePoint
   • Tipo de autenticação : OAuth Máquina a Máquina
   • ID do cliente : O ID do aplicativo (cliente) do passo 3
   • Usar certificado : marque esta caixa de seleção para autenticar com um certificado. Deixe-a desmarcada para autenticar com um segredo do cliente.
   • Segredo do cliente : O valor do segredo do cliente do Passo 3. Este campo aparece apenas quando Usar certificado está desmarcado.
   • Certificado de cliente pem : o conteúdo de databricks_cert.pem do Passo 3, incluindo os delimitadores BEGIN CERTIFICATE e END CERTIFICATE. Obrigatório quando Usar certificado está selecionado.
   • Pem da key privada do cliente : O conteúdo de databricks_key.pem do passo 3, incluindo os delimitadores BEGIN PRIVATE KEY e END PRIVATE KEY. Obrigatório quando Usar certificado está selecionado.
   • Domínio : Seu domínio do SharePoint no formato https://YOURINSTANCE.sharepoint.com
   • ID do locatário : O ID do diretório (tenant) do passo 3

4. Clique em Criar .

Sites.Selected permissões

Esta opção restringe o acesso da entidade de serviço apenas a sites específicos do SharePoint.

os passos 1-3: Conclua a configuração básica

Siga os passos 1 a 3 na seçãoSites.Read.All. Esses passos são os mesmos para ambos os modelos de permissão.

1. Obtenha o ID do site do SharePoint.
2. Obtenha os nomes das unidades do SharePoint (opcional).
3. Crie um aplicativo Microsoft Entra ID.

o passo 4: Configurar permissões API para Sites.Selected

Conceda ao aplicativo permissões restritas que exigem autorização adicional específica do site.

1. Na página de registro do aplicativo, clique em "Permissões da API" no menu à esquerda.

2. Clique em + Adicionar uma permissão .

3. No painel de permissões API de solicitação , clique em Microsoft gráfico .

4. Clique em Permissões do aplicativo .

5. Pesquise e selecione Sites.Selecionados .

6. Clique em Adicionar permissões .

7. Clique em Conceder permissão de administrador para [sua organização] .

   Este passo requer privilégios de administrador em seu tenant Microsoft Entra ID.

8. Clique em Sim para confirmar.

   A lista de permissões exibe uma marca de seleção verde na coluna Status , indicando que o consentimento do administrador foi concedido.

o passo 4b: Conceder permissões específicas do local

Após configurar Sites.Selected no Azure, você deve conceder explicitamente ao aplicativo acesso a sites específicos do SharePoint. Você pode fazer isso usando Microsoft Gráfico Explorer ou um Notebook Python .

Microsoft Graph Explorer

1. Vá para o Microsoft gráfico Explorer.

2. Faça login com uma account que tenha permissões de administrador para o seu site do SharePoint.

3. Clique em Modificar permissões e conceda as permissões necessárias (Sites.FullControl.All).

4. Altere o método HTTP para POST .

5. Insira o seguinte URL, substituindo {site_id} pelo ID do seu site do SharePoint da etapa 1:

   https://graph.microsoft.com/v1.0/sites/{site_id}/permissions

6. Na seção Corpo da solicitação , cole o seguinte JSON, substituindo os valores de espaço reservado:

   JSON

   {
     "roles": ["read"],
     "grantedToIdentities": [
       {
         "application": {
           "id": "<YOUR_CLIENT_ID>",
           "displayName": "<YOUR_APP_NAME>"
         }
       }
     ]
   }

   Substituir:

   • <YOUR_CLIENT_ID>O ID do aplicativo (cliente) do passo 3
   • <YOUR_APP_NAME>: O nome do seu registro de inscrição

7. Clique em executar consulta .

   Uma resposta positiva indica que a permissão foi concedida.

Python notebook

1. Crie um novo Notebook em seu workspace Databricks .

2. Instale a biblioteca MSAL executando o seguinte comando em uma célula:

   Python

   %pip install msal

3. Em uma nova célula, cole o seguinte código e substitua os valores de espaço reservado:

   Python

   import msal
   import requests
   
   # Configuration - Replace these values
   TENANT_ID = "<YOUR_TENANT_ID>"  # Directory (tenant) ID from Step 3
   ADMIN_CLIENT_ID = "<ADMIN_CLIENT_ID>"  # Client ID of an app with admin consent
   ADMIN_CLIENT_SECRET = "<ADMIN_CLIENT_SECRET>"  # Client secret of admin app
   TARGET_APP_CLIENT_ID = "<TARGET_CLIENT_ID>"  # Client ID from Step 3
   TARGET_APP_DISPLAY_NAME = "<TARGET_APP_NAME>"  # Name of your app
   SITE_ID = "<YOUR_SITE_ID>"  # SharePoint site ID from Step 1
   
   # Authenticate using MSAL
   authority = f"https://login.microsoftonline.com/{TENANT_ID}"
   app = msal.ConfidentialClientApplication(
       ADMIN_CLIENT_ID,
       authority=authority,
       client_credential=ADMIN_CLIENT_SECRET
   )
   
   # Acquire token
   token_result = app.acquire_token_for_client(
       scopes=["https://graph.microsoft.com/.default"]
   )
   
   if "access_token" in token_result:
       access_token = token_result["access_token"]
   
       # Grant site permissions
       grant_url = f"https://graph.microsoft.com/v1.0/sites/{SITE_ID}/permissions"
       headers = {
           "Authorization": f"Bearer {access_token}",
           "Content-Type": "application/json"
       }
       grant_payload = {
           "roles": ["read"],
           "grantedToIdentities": [
               {
                   "application": {
                       "id": TARGET_APP_CLIENT_ID,
                       "displayName": TARGET_APP_DISPLAY_NAME
                   }
               }
           ]
       }
   
       response = requests.post(grant_url, headers=headers, json=grant_payload)
   
       if response.status_code in [200, 201]:
           print("Successfully granted site permissions")
           print(response.json())
       else:
           print(f"Error: {response.status_code}")
           print(response.text)
   else:
       print("Failed to acquire token")
       print(token_result.get("error"))
       print(token_result.get("error_description"))

4. execução da célula. Uma resposta positiva indica que a permissão foi concedida.

o passo 5: Criar uma conexão no Databricks

Siga os passos em Passo 5: Criar uma conexão no Databricks para criar a conexão no Databricks usando as credenciais do seu registro de aplicativo.

Próximos passos

1. Ingerir dados do SharePoint
2. Tarefa comum de manutenção pipeline