Pré-requisitos para o conector Microsoft SharePoint 365 no Jitterbit Studio

Introdução

Para usar o conector Microsoft SharePoint 365, você precisa ter um app Microsoft SharePoint 365, suas credenciais e certas permissões configuradas. Este documento descreve como criar um app e obter suas credenciais para ambos os tipos de autenticação disponíveis na conexão (Azure Access Control Service ou Microsoft Entra ID).

Consulte a documentação da Microsoft para obter informações sobre como atualizar seu app SharePoint existente do Azure Access Control Service para Microsoft Entra ID.

Microsoft Entra ID

Esta seção descreve como registrar um app usando Microsoft Entra ID, definir suas permissões e gerar uma asserção de cliente.

Etapas de registro de app do Microsoft Entra ID

Siga estas etapas para criar um registro de app com a plataforma de identidade da Microsoft:

1. No portal do Azure, procure e clique em Microsoft Entra ID (anteriormente conhecido como Azure Active Directory ou Azure AD):

   

2. Na barra lateral esquerda, em Gerenciar, clique em Registros de app.

3. Clique em Novo registro:

   

4. Digite um Nome para seu app. Este nome de exibição será visível aos usuários:

   

5. Clique em Registrar para concluir o registro do app. Você será direcionado para a página Visão geral do app:

   

   Importante

   Retenha a ID do Aplicativo (cliente) e a ID do Diretório (locatário) do registro do app para usar como ID do Cliente e ID do Locatário ao configurar uma conexão.

Adicionar permissões necessárias ao registro do app

Seu registro de app deve ter um conjunto específico de permissões.

No portal do Azure, navegue até seu registro de app e clique em Permissões de API na barra lateral esquerda:

Para adicionar permissões de aplicativo do Microsoft SharePoint, siga estas etapas:

1. Na página Permissões de API, clique em Adicionar uma permissão.

2. No painel Solicitar permissões de API, clique na guia APIs que minha organização usa, procure e clique em SharePoint.

3. Clique em Permissões de aplicativo.

4. Ative a permissão Sites.FullControl.All.

5. Clique em Adicionar permissões. A página Permissões configuradas do registro do app atualizado é exibida.

Gerar a asserção de cliente

Siga estas etapas para gerar uma asserção de cliente (necessária para configuração de conexão):

1. Crie um certificado autoassinado completando as seguintes instruções:

   Salve o script PowerShell fornecido pela Microsoft chamado Create-SelfSignedCertificate.ps1 em sua máquina.

Dentro do PowerShell, acesse o diretório onde o script foi salvo e execute este script (como administrador):

.\Create-SelfSignedCertificate.ps1 -CommonName "<Insira um nome para o certificado, exemplo: MyCert>" -StartDate <Insira uma data de início do certificado no formato ISO: 2024-10-01> -EndDate <Insira uma data de expiração do certificado no formato ISO: 2029-10-01>

Substitua o texto do espaço reservado (incluindo os colchetes angulares < >) pelos valores apropriados para seu caso de uso.

Após executar o script, será solicitado que você forneça uma senha para criptografar sua chave privada, e tanto o arquivo .PFX quanto o arquivo .CER serão exportados para o diretório atual.

1. Carregue o certificado autoassinado no registro do aplicativo:

   Na página de visão geral do registro do aplicativo, clique em Adicionar um certificado ou segredo e depois clique em Carregar certificado e selecione o arquivo .CER gerado na etapa 1.

   Após carregar o certificado, retenha o valor na coluna Impressão digital do certificado. Este valor é uma string hexadecimal e deve ser convertido para uma string codificada em base64url para uso como o valor x5t na etapa 4. Para fazer isso, converta a impressão digital hex para sua matriz de bytes brutos, codifique essa matriz de bytes em Base64 e depois converta o resultado para base64url substituindo qualquer caractere + por -, substituindo qualquer caractere / por _ e removendo qualquer caractere = à direita.

   Por exemplo, esta conversão pode ser feita com um script Jitterbit:

   <trans>
   // thumbprint holds the hex value from the certificate's Thumbprint column
   base64 = Base64Encode(HexToBinary(thumbprint));
   x5t = RTrimChars(Replace(Replace(base64, "+", "-"), "/", "_"), "=");
   </trans>
   

2. Gere um arquivo .PEM a partir do arquivo .PFX gerado (da etapa 1) com este script no PowerShell (como administrador):

   openssl pkcs12 -in <Insira o nome do arquivo .PFX gerado>.pfx -out private.pem -nodes
   

   Substitua o texto do espaço reservado (incluindo os colchetes angulares < >) pelos valores apropriados.

   Retenha o valor private_key do arquivo .PEM gerado (para ser usado na etapa 4).

3. Gere a asserção do cliente. As etapas a seguir mostram como fazer isso usando jwt.io.

   Dica

   A asserção do cliente também pode ser gerada inteiramente em um script Jitterbit usando a função CreateJwtToken.

   Em jwt.io, selecione RS256 como Algoritmo e configure o Cabeçalho, Carga útil e Verificar assinatura.

   Dica

   Em vez de criar o Cabeçalho e a Carga útil JSON manualmente, este script Jitterbit gera ambos os valores, incluindo o GUID jti e os timestamps iat, nbf e exp, e os escreve no log de operações. Execute este script em uma operação e depois copie os valores registrados nos campos Cabeçalho e Carga útil abaixo.

   <trans>
   // Application (client) ID from Entra
   client_id = '<Enter client ID>';
   
   // Directory (tenant) ID from Entra
   tenant_id = '<Enter tenant ID>';
   
   // base64url-encoded thumbprint obtained in step 2
   x5t = '<Enter x5t value>';
   
   // If the agent is not running on a server in the Central time zone, replace 'America/Chicago' with the appropriate time zone
   now = Int(ConvertTimeZone(Now(), 'America/Chicago', 'UTC'));
   later = Int(ConvertTimeZone(DateAdd('yyyy', 10, Now()), 'America/Chicago', 'UTC'));
   
   header = '{
    "alg": "RS256",
    "typ": "JWT",
    "x5t":"' + x5t + '"
   }';
   
   payload = '{
    "aud": "https://login.microsoftonline.com/' + tenant_id + '/oauth2/v2.0/token",
    "exp": ' + later + ',
    "iss": "' + client_id + '",
    "jti": "' + GUID() + '",
    "nbf": ' + now + ',
    "iat": ' + now + ',
    "sub": "' + client_id + '"
   }';
   
   WriteToOperationLog('JWT Header:');
   WriteToOperationLog(header);
   WriteToOperationLog('\r\n');
   WriteToOperationLog('JWT Payload:');
   WriteToOperationLog(payload);
   </trans>
   

   Insira o Cabeçalho neste formato:

   Cabeçalho

   {
    "alg": "RS256",
    "typ": "JWT",
    "x5t":"<Enter the base64url-encoded thumbprint obtained in step 2>"
   }
   

   Substitua o texto do espaço reservado (incluindo os colchetes angulares < >) pelo valor apropriado.

   Insira a Carga útil neste formato:

   Carga útil

   {
    "aud": "https://login.microsoftonline.com/<tenantId>/oauth2/v2.0/token",
    "exp": <an expiration time>,
    "iss": "<client ID>",
    "jti": "<a GUID>",
    "nbf": <a "not before" claim>,
    "iat": <an "issued at" claim>,
    "sub": "<client ID>"
   }
   

   Substitua o texto do espaço reservado (incluindo os colchetes angulares < >) pelos valores apropriados para seu caso de uso. Para mais informações sobre esses campos, consulte a documentação da Microsoft.

   Na seção Verificar assinatura, insira a private_key (obtida na etapa 3) do registro do aplicativo.

   Após configurar as seções Cabeçalho, Carga útil e Verificar assinatura, o valor gerado na seção Codificado é o valor a ser usado como a Asserção do cliente na configuração de conexão.

Serviço de Controle de Acesso do Azure (Descontinuado)

Esta seção descreve como criar um app usando o modelo de Suplemento do SharePoint e o Serviço de Controle de Acesso (ACS) do Azure, além de configurar suas permissões. As etapas para autenticação com Microsoft Entra ID estão descritas na próxima seção.

Criar um app

Estas são as instruções para criar um app:

1. Faça login na instância do Microsoft SharePoint.

2. Após fazer login, navegue para esta URL (substituindo <office_365_tenant_URL> pela URL do seu locatário do Office 365):

   https://<office_365_tenant_URL>/_layouts/15/appregnew.aspx

3. Ao acessar a URL acima, você verá esta interface:

   

   • Client Id: Clique em Generate para gerar um ID de cliente para seu app.

   • Client Secret: Clique em Generate para gerar um segredo do cliente para seu app.

   • Title: Digite um título para seu app.

   • App Domain: Digite um domínio para seu app ou insira um valor de espaço reservado.

   • Redirect URI: Digite um URI de redirecionamento para seu app ou insira um valor de espaço reservado.

   Nota

   O conector Microsoft SharePoint 365 não usa o App Domain ou Redirect URI configurados.

4. Após preencher todos os campos, clique em Create. Uma página exibe as informações do app. Guarde essas informações para usar ao configurar permissões do app.

Configurar permissões

Estas são as instruções para autorizar o app para uso com o conector Microsoft SharePoint 365:

1. Navegue para esta URL (substituindo <office_365_tenant_URL> pela URL do seu locatário do Office 365):

   https://<office_365_tenant_URL>/_layouts/appinv.aspx

2. Ao acessar a URL acima, você verá esta interface:

   

   • App Id: Digite o ID de cliente do app (gerado durante a criação do app).

   • Title: Digite o título do seu app (definido durante a criação do app).

   • App Domain: Digite o domínio do seu app (definido durante a criação do app).

   • Redirect URL: Digite a URL de redirecionamento do seu app (definida durante a criação do app).

   • Permission Request XML: Digite esta permissão na caixa de texto:

     <AppPermissionRequests AllowAppOnlyPolicy="true">
         <AppPermissionRequest Scope="http://sharepoint/content/sitecollection" Right="FullControl" />
     </AppPermissionRequests>
     

     Para mais informações sobre permissões de suplementos, consulte a documentação da Microsoft sobre Permissões de suplementos no SharePoint e Fluxo OAuth de código de autorização para Suplementos do SharePoint.