Configurar um aplicativo com Multi-Geo de exemplo

Ao desenvolver para um inquilino Multi-Geo, é importante compreender o modelo de segurança. Felizmente, o modelo utilizado para um inquilino Multi-Geo é o mesmo que o modelo utilizado para um inquilino normal.

Este artigo mostra-lhe como configurar as seguintes aplicações de exemplo:

• Uma aplicação que pode ler e atualizar perfis para todos os utilizadores que utilizam o API do Graph
• Uma aplicação que pode ler e atualizar perfis para todos os utilizadores com a API de Perfil de Utilizador CSOM
• Uma aplicação que pode detetar a configuração Multi-Geo
• Uma aplicação que pode criar e eliminar coleções de sites e definir propriedades da coleção de sites do inquilino

Ler e atualizar perfis para todos os utilizadores que utilizam o API do Graph

Conforme explicado no artigo Trabalhar com perfis de utilizador num inquilino multigeográfico, o modelo preferencial a utilizar para ler e atualizar as propriedades do perfil de utilizador é o API do Graph. Esta secção explica as permissões que tem de conceder à sua aplicação para realizar leituras e atualizações do perfil de utilizador ao nível do inquilino.

Existe uma longa lista de permissões possíveis que pode conceder a uma aplicação definida no Azure AD, mas para manipular perfis, pode limitar as permissões ao seguinte.

Os exemplos multigeográficos baseados no Microsoft Graph utilizam a Biblioteca de Autenticação da Microsoft (MSAL) para ligar ao Microsoft Graph no ponto final v2. Em comparação com a ADAL, que se liga através do ponto final v1, a MSAL permite a ligação ao Microsoft Graph através de contas Microsoft, Azure AD e Azure AD B2C. As instruções seguintes irão ajudá-lo a configurar a sua aplicação para o ponto final v2, mas também pode utilizar a abordagem "mais antiga" com base nos pontos finais v1.

Registre seu aplicativo

1. Para utilizar permissões de aplicação no Microsoft Graph, registe a sua aplicação em https://apps.dev.microsoft.com.

2. Depois de iniciar sessão, selecione Adicionar uma aplicação e, em seguida, selecione Adicionar uma nova aplicação convergida.

3. Atribua um nome à sua aplicação e, em seguida, selecione Criar aplicação.

4. É apresentado o ecrã de configuração da aplicação.

5. Gere uma nova palavra-passe e tome nota da mesma juntamente com o ID da aplicação.

6. Selecione Adicionar Plataforma e, em seguida, escolha Aplicação nativa como o destino da plataforma porque a aplicação não tem uma página de destino.

7. Adicione as Permissões de Aplicação necessárias. Nesta aplicação de exemplo, adicionámos as permissões de aplicação Sites.ReadWrite.All e User.ReadWrite.All.

8. Desmarque a caixa de marcar de suporte do Live SDK.

9. Salve suas alterações.

Consentimento para a aplicação

1. Neste exemplo, as permissões User.ReadWrite.All e Sites.ReadWrite.Todas as aplicações requerem o consentimento do administrador num inquilino antes de poderem ser utilizadas. Crie um URL de consentimento da seguinte forma:

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

2. Utilizar o ID de cliente da aplicação registada e consentir a aplicação a partir do meu inquilino contoso.onmicrosoft.com; o URL tem o seguinte aspeto:

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

3. Navegue para o URL criado e inicie sessão como administrador de inquilinos e consoante a aplicação. Pode ver que o ecrã de consentimento mostra o nome da sua aplicação, bem como os âmbitos de permissão que configurou.

Ler e atualizar perfis para todos os utilizadores que utilizam a API de Perfil de Utilizador CSOM

Ao utilizar a API CSOM para manipular as propriedades do perfil, só o faz para as propriedades criadas personalizadas, uma vez que as propriedades fora da caixa são melhor processadas através do microsoft API do Graph. Para obter mais informações, veja o artigo Trabalhar com perfis de utilizador num inquilino Multi-Geo.

Do ponto de vista da permissão, existem dois modos:

• Utilizar credenciais de utilizador

  Isto requer a configuração de um ClientContext objeto através do URL de administrador inquilino e das credenciais de administrador do SharePoint Online. Uma vez que existe apenas uma instância Azure AD que contém utilizadores, tal implica que um administrador do SharePoint Online é o administrador de todas as localizações geográficas.

  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;
  }
  

• Utilizar um principal apenas de aplicação

  Ao utilizar apenas a aplicação, tem de conceder ao principal de aplicação criado controlo total para o http://sharepoint/social/tenant âmbito de permissão.

As instruções seguintes mostram-lhe como utilizar appregnew.aspx e appinv.aspx para registar um principal de aplicação e dar consentimento ao mesmo.

Criar o principal

1. Aceda a um site no seu inquilino (por exemplo, ) e, em seguida, https://contoso.sharepoint.comchame a página appregnew.aspx (por exemplo, https://contoso.sharepoint.com/_layouts/15/appregnew.aspx).

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

3. Preencha os restantes campos da seguinte forma:

• Título: Multi-Geo demo
• Domínio da Aplicação: www.localhost.com
• URI de Redirecionamento: https://www.localhost.com

Conceder permissões ao principal criado

O próximo passo é conceder permissões ao principal recém-criado. Uma vez que estamos a conceder permissões no âmbito do inquilino, esta concessão só pode ser feita através da página appinv.aspx no site de administração do inquilino.

1. Pode aceder a este site através de https://contoso-admin.sharepoint.com/_layouts/15/appinv.aspx.

2. Depois de carregar a página, adicione o ID de cliente e, em seguida, procure o principal criado.

3. Para conceder permissões, tem de fornecer o XML de permissão que descreve as permissões necessárias. Uma vez que o detetor de experiência de IU tem de conseguir aceder a todos os sites e utilizar a pesquisa apenas com aplicações, necessita das seguintes permissões:

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

4. Quando seleciona Criar, é-lhe apresentada uma caixa de diálogo de consentimento de permissão. Selecione Confiar para conceder as permissões.

Utilizar o principal no código

Depois de o principal ser criado e consentido, pode utilizar o ID e o segredo do principal para pedir acesso. A TokenHelper.cs classe captura o ID e o segredo do ficheiro de configuração da aplicação.

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
}

Uma app.config de exemplo tem o seguinte aspeto:

<?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>

Descobrir a configuração multigeográfico

A única API suportada que pode utilizar para detetar as localizações geográficas num inquilino multigeográfico é a API do Graph. Esta secção explica as permissões que tem de conceder à sua aplicação para detetar informações da Multi-Geo.

Existe uma longa lista de permissões possíveis que pode conceder a uma aplicação definida no Azure AD, mas para ler as informações de configuração do inquilino Multi-Geo, pode limitar as permissões ao seguinte.

Utilize os Azure AD passos de criação de aplicações, conforme descrito na secção Perfis de leitura/atualização para todos os utilizadores.

Criar e eliminar coleções de sites e definir propriedades da coleção de sites do inquilino

Utilizar 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 equipa "modernos") com o microsoft API do Graph. Nesta secção, estamos apenas a abordar as permissões. A tabela seguinte lista as permissões necessárias.

Os exemplos multigeográficos baseados no Microsoft Graph utilizam a Biblioteca de Autenticação da Microsoft (MSAL) para ligar ao Microsoft Graph no ponto final v2. Em comparação com a ADAL, que se liga através do ponto final v1, a MSAL permite a ligação ao Microsoft Graph através de contas Microsoft, Azure AD e Azure AD B2C.

Utilize os Azure AD passos de criação de aplicações, conforme descrito na secção Perfis de leitura/atualização para todos os utilizadores.

Utilizar a API de Inquilino CSOM

A utilização da API de Inquilino CSOM é muito semelhante à documentação de orientação da CSOM anteriormente descrita; na verdade, a documentação de orientação para utilizar credenciais de utilizador é idêntica. Para utilizar um principal apenas de aplicação, as instruções são as mesmas, mas tem de conceder permissões diferentes (inquilino e controlo total).

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

Confira também

• Centro de Programadores 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