Configurar um aplicativo com Multi-Geo de exemplo

Ao desenvolver para um locatário Multi-Geo, é 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:

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

Conforme explicado no artigo Trabalhar com perfis de usuário em um locatário Multi-Geo, o modelo preferencial a ser usado para ler e atualizar as propriedades do perfil do usuário é a 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 permissões possíveis que você pode conceder a um aplicativo definido no Azure AD, mas para manipular perfis, você pode limitar as permissões ao seguinte.

Permissão Tipo Descrição Consentimento do Administrador necessário
User.ReadWrite.All Permissão do aplicativo Permite que o aplicativo leia e grave o conjunto completo de propriedades de perfil, associação a 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/grave documentos e liste itens em todos os conjuntos 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

As amostras Multi-Geo baseadas no Microsoft Graph usam a MSAL (Biblioteca de Autenticação da Microsoft) para se conectar ao Microsoft Graph no ponto de extremidade v2. Em comparação com a ADAL, que se conecta usando o ponto de extremidade v1, a MSAL permite a conexão com o Microsoft Graph usando contas da Microsoft, o Azure AD e o 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 em relação ao Microsoft Graph, registre seu aplicativo em https://apps.dev.microsoft.com.

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

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

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

Registrar aplicativo no Azure AD

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

  2. Escolha Adicionar Plataforma e, em seguida, escolha Aplicativo nativo como o destino da plataforma porque o aplicativo não tem uma página de aterrissagem.

Configurar aplicativo no Azure AD parte 1

  1. 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.

  2. Desmarque a caixa de marca suporte ao Live SDK.

Configurar aplicativo no Azure AD parte 2

  1. Salve suas alterações.
  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>
  1. Usar a ID do cliente do aplicativo registrado e consentir com o aplicativo do meu locatário contoso.onmicrosoft.com; a URL tem esta aparência:
https://login.microsoftonline.com/contoso.onmicrosoft.com/adminconsent?client_id=6e4433ca-7011-4a11-85b6-1195b0114fea&state=12345
  1. Navegue até a URL criada, entre como administrador de locatários e concorde com o aplicativo. Você pode ver que a tela de consentimento mostra o nome do seu aplicativo, bem como os escopos de permissão que você configurou.

Consentimento do locatário para o aplicativo do Azure AD

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

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

Do ponto de vista da permissão, existem 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 do Azure AD contendo usuários, isso 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;
}

  • Usando uma entidade de segurança somente aplicativo

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

As instruções a seguir mostram como usar o appregnew.aspx e appinv.aspx 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, ) 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, escolha o botão Gerar para gerar uma ID do cliente e um segredo do cliente.

  3. Preencha os campos restantes da seguinte forma:

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

Registrar entidade de aplicativo ACS

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 (Serviços de Controle de Acesso) para SharePoint Online foi desativado a partir de 27 de novembro de 2023 e deixará de funcionar a partir de 2 de abril de 2026. Confira o anúncio completo de desativação 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 está no fim da vida útil.

A desativação significa que o recurso não receberá novos investimentos, mas ainda terá suporte. Fim da vida útil significa que o recurso será descontinuado e não estará mais disponível para uso.

Conceda 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 no escopo do 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 via https://contoso-admin.sharepoint.com/_layouts/15/appinv.aspx.

  2. Depois que a página for carregada, adicione a ID do cliente e pesquise a entidade de segurança criada.

Conceder permissões à entidade de segurança do aplicativo

  1. Para conceder permissões, você deve fornecer o XML de permissão que descreve as permissões necessárias. Como o verificador 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>
  1. Ao escolher Criar, você verá uma caixa de diálogo de consentimento de permissão. Escolha Confiar para conceder as permissões.

Autorizar a entidade de segurança do aplicativo

Usar 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 de segurança para solicitar acesso. A TokenHelper.cs classe obtém 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 de 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.

Descubra a configuração Multi-Geo

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

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

Permissão Tipo Descrição Consentimento do Administrador necessário
Sites.ReadWrite.All Permissão do aplicativo Permite que o aplicativo leia/grave documentos e liste itens em todos os conjuntos de sites sem um usuário conectado. Sim

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

Criar e excluir conjuntos de sites e definir propriedades de conjunto de sites de locatário

Usando a API do Graph

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

Permissão Tipo Descrição Consentimento do Administrador 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

As amostras Multi-Geo baseadas no Microsoft Graph usam a MSAL (Biblioteca de Autenticação da Microsoft) para se conectar ao Microsoft Graph no ponto de extremidade v2. Em comparação com a ADAL, que se conecta usando o ponto de extremidade v1, a MSAL permite a conexão com o Microsoft Graph usando contas da Microsoft, o Azure AD e o Azure AD B2C.

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

Usando a API de Locatário CSOM

O uso da API do Locatário do CSOM é muito semelhante às diretrizes do CSOM descritas anteriormente; Na verdade, as diretrizes para usar as credenciais do 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

  • Last updated on