Configurar um aplicativo com Multi-Geo de exemplo

Ao desenvolver para um locatário multi-geográfico, é importante entender o modelo de segurança. Felizmente, o modelo usado para um locatário multi-geo é o mesmo que o modelo usado para um locatário regular.

Este artigo mostra como configurar os seguintes aplicativos de exemplo:

• Um aplicativo que pode ler e atualizar perfis para todos os usuários usando o API do Graph
• Um aplicativo que pode ler e atualizar perfis para todos os usuários usando a API de Perfil de Usuário do CSOM
• Um aplicativo que pode descobrir a configuração multi-geo
• Um aplicativo que pode criar e excluir coleções de sites e definir propriedades de coleção de sites de locatário

Ler e atualizar perfis para todos os usuários usando o API do Graph

Conforme explicado no artigo Trabalhar com perfis de usuário em um locatário multi-geográfico, o modelo preferido a ser usado para ler e atualizar as propriedades do perfil de usuário é o API do Graph. Esta seção explica as permissões que você deve conceder ao seu aplicativo para realizar leituras e atualizações de perfil de usuário em todo o locatário.

Há uma longa lista de possíveis permissões que você pode conceder a um aplicativo definido em Azure AD, mas para manipular perfis, você pode limitar as permissões a seguir.

Permissão	Tipo	Descrição	Administração consentimento necessário
User.ReadWrite.All	Permissão do aplicativo	Permite que o aplicativo leia e escreva o conjunto completo de propriedades de perfil, associação de grupo, relatórios e gerentes de outros usuários em sua organização, sem um usuário conectado. Também permite que o aplicativo crie e exclua usuários não administrativos. Não permite a redefinição de senhas de usuário.	Sim
Sites.ReadWrite.All	Permissão do aplicativo	Permite que o aplicativo leia/escreva documentos e liste itens em todas as coleções de sites sem um usuário conectado. Essa permissão só será necessária se o aplicativo estiver recuperando o local do site pessoal do usuário (por exemplo, https://graph.microsoft.com/v1.0/users/UserB@contoso.onmicrosoft.com?$select=mySite).	Sim

Os exemplos multigráficos baseados no Microsoft Graph usam a MSAL (Biblioteca de Autenticação da Microsoft) para se conectar com o Microsoft Graph no ponto de extremidade v2. Comparado ao ADAL, que se conecta usando o ponto de extremidade v1, o MSAL permite a conexão com o Microsoft Graph usando contas da Microsoft, Azure AD e Azure AD B2C. As instruções a seguir ajudarão você a configurar seu aplicativo para o ponto de extremidade v2, mas você também pode usar a abordagem "mais antiga" com base nos pontos de extremidade v1.

Registre seu aplicativo

1. Para usar permissões de aplicativo no Microsoft Graph, registre seu aplicativo em https://apps.dev.microsoft.com.

2. Depois de entrar, escolha Adicionar um aplicativo e escolha Adicionar um aplicativo convergido.

3. Dê um nome ao aplicativo e escolha Criar aplicativo.

4. A tela de configuração do aplicativo é exibida.

5. Gere uma nova senha e anote-a junto com a ID do aplicativo.

6. Escolha Adicionar Plataforma e escolha Aplicativo nativo como o destino da plataforma porque o aplicativo não tem uma página de destino.

7. Adicione as permissões de aplicativo necessárias. Neste aplicativo de exemplo, adicionamos as permissões de aplicativo Sites.ReadWrite.All e User.ReadWrite.All.

8. Desmarque a caixa de suporte Live SDK marcar.

9. Salve suas alterações.

Consentimento para o aplicativo

1. Neste exemplo, as permissões de aplicativo User.ReadWrite.All e Sites.ReadWrite.All exigem o consentimento do administrador em um locatário antes de poderem ser usadas. Crie uma URL de consentimento como a seguinte:

https://login.microsoftonline.com/<tenant>/adminconsent?client_id=<clientid>&state=<something>

2. Use a ID do cliente do aplicativo registrado e consenta com o aplicativo do meu locatário contoso.onmicrosoft.com; a URL se parece com esta:

https://login.microsoftonline.com/contoso.onmicrosoft.com/adminconsent?client_id=6e4433ca-7011-4a11-85b6-1195b0114fea&state=12345

3. Navegue até a URL criada e entre como administrador de locatário e consenta com o aplicativo. Você pode ver que a tela de consentimento mostra o nome do aplicativo, bem como os escopos de permissão configurados.

Ler e atualizar perfis para todos os usuários usando a API de Perfil de Usuário do CSOM

Ao usar a API do CSOM para manipular propriedades de perfil, você faz isso apenas para as propriedades criadas personalizadas porque as propriedades fora da caixa são melhor tratadas por meio do Microsoft API do Graph. Para obter mais informações, consulte o artigo Trabalhar com perfis de usuário em um locatário multi-geográfico.

Do ponto de vista de permissão, há dois modos:

• Usando credenciais de usuário

  Isso requer a configuração de um ClientContext objeto usando a URL de administrador do locatário e as credenciais de administrador do SharePoint Online. Como há apenas uma instância Azure AD que contém usuários, isso implica que um administrador do SharePoint Online é o administrador de todos os locais geográficos.

  string tenantAdminSiteForMyGeoLocation = "https://contoso-europe-admin.sharepoint.com";
  
  using (ClientContext cc = new ClientContext(tenantAdminSiteForMyGeoLocation))
  {
      SecureString securePassword = GetSecurePassword("password");
      cc.Credentials = new SharePointOnlineCredentials("admin@contoso.onmicrosoft.com", securePassword);
  
      // user profile logic
  }
  
  static SecureString GetSecurePassword(string Password)
  {
      SecureString sPassword = new SecureString();
      foreach (char c in Password.ToCharArray()) sPassword.AppendChar(c);
      return sPassword;
  }
  

• Usando uma entidade de segurança somente aplicativo

  Ao usar somente aplicativo, você deve conceder o controle completo da entidade de aplicativo criada para o escopo de http://sharepoint/social/tenant permissão.

As instruções a seguir mostram como usar appregnew.aspx e appinv.aspx para registrar uma entidade de aplicativo e consentir com ela.

Criar a entidade de segurança

1. Vá para um site em seu locatário (por exemplo, https://contoso.sharepoint.com), e chame a página appregnew.aspx (por exemplo, https://contoso.sharepoint.com/_layouts/15/appregnew.aspx).

2. Nesta página, escolha o botão Gerar para gerar uma ID do cliente e um segredo do cliente.

3. Conclua os campos restantes da seguinte maneira:

• Título: Multi-Geo demo
• Domínio do Aplicativo: www.localhost.com
• URI de redirecionamento: https://www.localhost.com

Observação

Armazene as informações recuperadas (ID do cliente e segredo do cliente) porque você precisará delas na próxima etapa.

Importante

O uso do Azure ACS (Controle de Acesso Services) para o SharePoint Online foi desativado a partir de 27 de novembro de 2023, confira o comunicado completo de aposentadoria para saber mais. O uso do ACS do Azure fora do contexto do SharePoint já foi desativado em 7 de novembro de 2018 e agora é o fim da vida útil.

A aposentadoria significa que o recurso não receberá novos investimentos, mas ainda tem suporte. O fim da vida útil significa que o recurso será descontinuado e não está mais disponível para uso.

Conceder permissões à entidade de segurança criada

A próxima etapa é conceder permissões à entidade de segurança recém-criada. Como estamos concedendo permissões com escopo de locatário, essa concessão só pode ser feita por meio da página appinv.aspx no site de administração do locatário.

1. Você pode acessar este site por meio de https://contoso-admin.sharepoint.com/_layouts/15/appinv.aspx.

2. Depois que a página for carregada, adicione a ID do cliente e procure a entidade criada.

3. Para conceder permissões, você deve fornecer a permissão XML que descreve as permissões necessárias. Como o scanner de experiência da interface do usuário precisa ser capaz de acessar todos os sites e usa a pesquisa somente com aplicativo, ele requer as seguintes permissões:

<AppPermissionRequests AllowAppOnlyPolicy="true">
  <AppPermissionRequest Scope="http://sharepoint/social/tenant" Right="FullControl" />
</AppPermissionRequests>

4. Quando você escolhe Criar, você recebe uma caixa de diálogo de consentimento de permissão. Escolha Confiar nele para conceder as permissões.

Use a entidade de segurança em seu código

Depois que a entidade de segurança for criada e consentida, você poderá usar a ID e o segredo da entidade para solicitar acesso. A TokenHelper.cs classe captura a ID e o segredo do arquivo de configuração do aplicativo.

string tenantAdminSiteForMyGeoLocation = "https://contoso-europe-admin.sharepoint.com";

//Get the realm for the URL.
string realm = TokenHelper.GetRealmFromTargetUrl(siteUri);

//Get the access token for the URL.  
string accessToken = TokenHelper.GetAppOnlyAccessToken(TokenHelper.SharePointPrincipal, siteUri.Authority, realm).AccessToken;

//Create a client context object based on the retrieved access token.
using (ClientContext cc = TokenHelper.GetClientContextWithAccessToken(tenantAdminSiteForMyGeoLocation, accessToken))
{
    // user profile logic
}

Um exemplo app.config se parece com este:

<?xml version="1.0" encoding="utf-8"?>
<configuration>
  <appSettings>
    <!-- Use AppRegNew.aspx and AppInv.aspx to register client id with proper secret -->
    <add key="ClientId" value="[Your Client ID]" />
    <add key="ClientSecret" value="[Your Client Secret]" />
  </appSettings>
</configuration>

Observação

Você pode inserir facilmente a TokenHelper.cs classe em seu projeto adicionando o pacote NuGet [AppForSharePointOnlineWebToolkit] àhttps://www.nuget.org/packages/AppForSharePointOnlineWebToolkit/ sua solução.

Descobrir a configuração multi-geográfica

A única API com suporte que você pode usar para descobrir os locais geográficos em um locatário multi-geográfico é o API do Graph. Esta seção explica as permissões que você deve conceder ao seu aplicativo para descobrir informações multi-geográficas.

Há uma longa lista de possíveis permissões que você pode conceder a um aplicativo definido em Azure AD, mas para ler informações de configuração de locatário multi-geo, você pode limitar as permissões a seguir.

Permissão	Tipo	Descrição	Administração consentimento necessário
Sites.ReadWrite.All	Permissão do aplicativo	Permite que o aplicativo leia/escreva documentos e liste itens em todas as coleções de sites sem um usuário conectado.	Sim

Use as etapas de criação do aplicativo Azure AD conforme descrito na seção Perfis de leitura/atualização para todos os usuários.

Criar e excluir coleções de sites e definir propriedades de coleção de sites de locatário

Usando o Microsoft API do Graph

O artigo Sites Multi-Geo fornece mais detalhes sobre como criar sites de grupo (também conhecidos como sites de equipe "modernos") usando o microsoft API do Graph. Nesta seção, estamos apenas abordando as permissões. A tabela a seguir lista as permissões necessárias.

Permissão	Tipo	Descrição	Administração consentimento necessário
Group.ReadWrite.All	Permissão do aplicativo	Permite que o aplicativo crie grupos, leia e atualize as associações do grupo e exclua grupos. Todas essas operações podem ser executadas pelo aplicativo sem um usuário conectado. Observe que nem todas as API de grupo suportam o acesso usando permissões somente de aplicativo.	Sim

Os exemplos multigráficos baseados no Microsoft Graph usam a MSAL (Biblioteca de Autenticação da Microsoft) para se conectar com o Microsoft Graph no ponto de extremidade v2. Comparado ao ADAL, que se conecta usando o ponto de extremidade v1, o MSAL permite a conexão com o Microsoft Graph usando contas da Microsoft, Azure AD e Azure AD B2C.

Use as etapas de criação do aplicativo Azure AD conforme descrito na seção Perfis de leitura/atualização para todos os usuários.

Usando a API de Locatário do CSOM

O uso da API de Locatário do CSOM é muito semelhante às diretrizes de CSOM descritas anteriormente; na verdade, as diretrizes para o uso de credenciais de usuário são idênticas. Para usar uma entidade de segurança somente aplicativo, as instruções são as mesmas, mas você deve conceder permissões diferentes (locatário e controle total).

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

Confira também

• Centro de Desenvolvedores do Microsoft Graph
• Obter tokens de acesso para chamar o Microsoft Graph
• Documentação do Microsoft Graph
• Explorador do Graph
• Privilégios elevados e somente aplicativo no modelo de suplemento do SharePoint
• OneDrive e SharePoint Online com Multi-Geo