Conectar-se às APIs protegidas pelo Azure AD em soluções da Estrutura do SharePoint

Artigo
04/08/2023

Ao criar soluções da Estrutura do SharePoint, convém conectar-se a uma API protegida usando o Azure Active Directory (Azure AD). A Estrutura do SharePoint permite especificar quais aplicativos e permissões do Microsoft Azure Active Directory sua solução requer, e um administrador global ou um Administrador de serviços do SharePoint pode conceder as permissões necessárias caso ainda não tenha sido concedido. Ao usar o AadHttpClient, você pode conectar-se facilmente às APIs protegidas pelo Azure AD, sem ter que implementar o fluxo do OAuth por conta própria.

Visão geral de permissões de API Web

O Azure AD protege vários recursos, do Office 365 aos aplicativos de linha de negócios personalizados criados pela organização. Para se conectar a esses recursos, os aplicativos devem obter um token de acesso válido que conceda a eles acesso aos recursos. Os aplicativos podem obter um token de acesso como parte do fluxo de autorização do OAuth.

Os aplicativos do lado do cliente não conseguem armazenar um segredo, como soluções da Estrutura do SharePoint, usam um tipo específico de fluxo do OAuth chamado Fluxo implícito do OAuth.

Os desenvolvedores que criam soluções do lado do cliente são responsáveis por implementar a autorização no aplicativo usando o fluxo implícito do OAuth. Isso já foi feito nas soluções da Estrutura do SharePoint como parte da estrutura utilizando o MSGraphClient e o AadHttpClient, que foram introduzidos na Estrutura do SharePoint v1.4.1.

Observação

Se você compilar soluções em uma versão da Estrutura do SharePoint mais antiga que a versão 1.4.1, ainda será possível se conectar aos recursos protegidos pelo Azure AD. Nesse caso, você precisa implementar o fluxo implícito OAuth usando diretamente bibliotecas de autenticação de platfomr de identidade da Microsoft. Para saber mais, confira Conectar-se às APIs protegidas pelo Azure Active Directory.

Como parte da Estrutura do SharePoint, um processo específico é definido sobre a forma como os desenvolvedores podem solicitar permissões e os administradores podem gerenciar permissões para recursos protegidos pelo Azure Active Directory. O esquema a seguir ilustra esse processo.

Esquema ilustrando o fluxo de solicitação, concedendo e usando permissões em aplicativos do Azure AD

Os desenvolvedores que criam uma solução da Estrutura do SharePoint que exige acesso a recursos específicos protegidos pelo Azure AD, listam esses recursos juntamente com os escopos de permissão necessários no manifesto da solução. Ao implantar o pacote de soluções no catálogo de aplicativos, o SharePoint cria solicitações de permissão e solicita que o administrador gerencie as permissões solicitadas. Para cada permissão solicitada, um administrador global ou um Administrador de serviços do SharePoint pode decidir se deseja conceder ou negar a permissão específica.

Todas as permissões são concedidas ao locatário inteiro e não a um aplicativo específico que as solicitou. Quando o administrador concede determinada permissão, ela é adicionada ao aplicativo do Azure Active Directory da Extensibilidade do Cliente do SharePoint Online, que é provisionado pela Microsoft em cada Azure Active Directory e usado pela Estrutura do SharePoint no fluxo do OAuth para fornecer soluções com tokens de acesso válidos.

Descobrir os aplicativos e permissões disponíveis

O destino do Azure Active Directory que protege o locatário do Office 365 é que determina os aplicativos para os quais você pode solicitar permissões na solução. A lista de aplicativos disponíveis depende da licença do Office 365 que a organização está usando e dos aplicativos de linha de negócios registrados no Azure AD. Se você tiver permissões suficientes, haverá várias maneiras de ver quais aplicativos e escopos de permissão estão disponíveis em seu locatário.

Usar o portal do Azure ou o centro de administração do Azure AD

Uma maneira de ver os aplicativos disponíveis no Azure AD é navegar até o portal do Azure ou o centro de administração do Azure AD.

No centro de administração do Microsoft Azure AD, na navegação à esquerda, escolha o link Aplicativos empresariais.
Na folha Aplicativos corporativos, no grupo Gerenciar, escolha o link Todos os aplicativos.
Para localizar rapidamente o aplicativo ao qual você deseja se conectar, filtre a visão geral por tipo de aplicativo (Aplicativos da Microsoft ou Aplicativos empresariais) ou pesquise usando o nome ou ID do aplicativo.

Por exemplo, se você quiser solicitar outras permissões para o Microsoft Graph, procure graph na caixa de pesquisa.
Depois de encontrar o aplicativo, selecione-o para obter informações adicionais. Na folha do aplicativo, no grupo Gerenciar, selecione Propriedades para abrir as propriedades do aplicativo.
Na lista de propriedades, copie o valor da propriedade ID do Objeto que será necessário para solicitar mais escopos de permissão ao Microsoft Graph. Em vez disso, você pode copiar o Nome do aplicativo e usá-lo na solicitação da permissão.

Observação

A ID do Objeto é exclusiva para cada locatário, mas o Nome do aplicativo é o mesmo em todos os locatários. Se quiser criar sua solução apenas uma vez e implantá-la em vários locatários, use o Nome do aplicativo ao solicitar mais permissões em uma solução.

Usar o Azure PowerShell

Observação

Antes de poder executar as etapas a seguir, você precisa instalar o Microsoft Azure PowerShell. Como alternativa, você pode executar os cmdlets mencionados nesta seção no Azure Cloud Shell PowerShell.

Entre com sua assinatura do Azure executando no Windows PowerShell (isso não é necessário se você estiver usando o Azure Cloud Shell):
```
Login-AzureRmAccount
```
Digite o seguinte na lista de aplicativos disponíveis em seu locatário:
```
Get-AzureRmADServicePrincipal | sort DisplayName | ft DisplayName, Id
```
A execução desse cmdlet gera uma lista de todos os aplicativos disponíveis em seu locatário. Para cada aplicativo, o nome de exibição e a ID do objeto são exibidos, o que você pode usar em sua solução da Estrutura do SharePoint para solicitar permissões do aplicativo.

Usar a CLI do Azure

Observação

Antes de poder executar as etapas a seguir, você precisa instalar a CLI do Azure. Como alternativa, você pode executar a CLI do Azure no Azure Cloud Shell ou como um contêiner do Docker.

Se você estiver executando a CLI no computador ou em um contêiner do Docker, comece por se conectar à sua assinatura do Azure executando:
```
azure login
```
Após se conectar, execute o seguinte comando para listar todos os aplicativos disponíveis do Azure AD:
```
azure ad sp list --query "sort_by([*].{displayName: displayName, objectId: objectId}, &displayName)" -o table
```
A execução desse comando gera uma lista de todos os aplicativos do Azure AD disponíveis em seu locatário, classificados por displayName. Para cada aplicativo, o comando exibe seu displayName e objectId. Além disso, o resultado é formatado como uma tabela.

Abrir a lista de escopos de permissão expostos pelo aplicativo

Cada aplicativo do Azure AD expõe diversos escopos de permissão. Esses escopos de permissão frequentemente se relacionam com operações ou recursos específicos dentro do aplicativo. Para obter a lista de permissões disponíveis para o aplicativo ao qual você gostaria de se conectar, consulte a documentação. Confira a lista de escopos de permissão disponíveis no Microsoft Graph em Referência de permissões do Microsoft Graph.

Solicitar permissões para um aplicativo do Azure AD

Se sua solução da Estrutura do SharePoint exigir permissões para recursos específicos protegidos pelo Azure AD, como o Microsoft Graph ou aplicativos empresariais, especifique esses recursos juntamente com as permissões necessárias na configuração da solução.

No seu projeto da Estrutura do SharePoint, abra o arquivo config/package-solution.json.
Para a propriedadesolution, adicione a propriedade webApiPermissionRequests listando todos os recursos e permissões correspondentes que sua solução precisa.

Veja a seguir um exemplo de uma solução da Estrutura do SharePoint solicitando acesso para ler os calendários de usuário usando o Microsoft Graph:
```
{
  "$schema": "https://developer.microsoft.com/json-schemas/spfx-build/package-solution.schema.json",
  "solution": {
    "name": "spfx-graph-client-side-solution",
    "id": "5d16587c-5e87-44d7-b658-1148988f212a",
    "version": "1.0.0.0",
    "includeClientSideAssets": true,
    "skipFeatureDeployment": true,
    "webApiPermissionRequests": [
      {
        "resource": "Microsoft Graph",
        "scope": "Calendars.Read"
      }
    ]
  },
  "paths": {
    "zippedPackage": "solution/spfx-graph.sppkg"
  }
}
```
Observação

Para o valor da propriedade resource, você precisa especificar o displayName do aplicativo para o qual deseja solicitar permissões. Se você especificar o recurso usando seus objectId, receberá um erro ao tentar aprovar a solicitação de permissão.

Se você quiser solicitar vários escopos de permissão para determinado recurso, especifique cada escopo em uma entrada separada, por exemplo:

{
  "$schema": "https://developer.microsoft.com/json-schemas/spfx-build/package-solution.schema.json",
  "solution": {
    "name": "spfx-graph-client-side-solution",
    "id": "5d16587c-5e87-44d7-b658-1148988f212a",
    "version": "1.0.0.0",
    "includeClientSideAssets": true,
    "skipFeatureDeployment": true,
    "webApiPermissionRequests": [
      {
        "resource": "Microsoft Graph",
        "scope": "Calendars.Read"
      },
      {
        "resource": "Microsoft Graph",
        "scope": "User.ReadBasic.All"
      }
    ]
  },
  "paths": {
    "zippedPackage": "solution/spfx-graph.sppkg"
  }
}

Quando essa solução for implantada no catálogo de aplicativos do SharePoint, será pedido que o administrador verifique as permissões solicitadas e se elas serão concedidas ou recusadas.

Observação

Independentemente de o administrador negar ou aprovar as permissões solicitadas, a solução poderá ser implantada e usada em sites. Durante a criação de soluções que exigem permissões adicionais, jamais pressuponha que as permissões solicitadas já foram concedidas.

Gerenciar solicitações de permissão

Ao implantar soluções da Estrutura do SharePoint que solicitam permissões aos aplicativos do Azure Active Directory, os administradores serão solicitados a gerenciar a solicitação de permissão fornecida pela solução. As solicitações de permissão podem ser gerenciadas de várias maneiras.

Gerenciar sites no novo Centro de Administração do SharePoint Online

Para saber como usar a página de acesso à API no novo Centro de Administração do SharePoint Online, confira Gerenciar o acesso às APIs protegidas pelo Azure Active Directory.

Gerenciar permissões com o Windows PowerShell

Os administradores globais e do SharePoint também podem usar o Shell de gerenciamento do SharePoint Online para gerenciar permissões e solicitações de permissão no SharePoint Online.

Para visualizar todas as solicitações de permissão pendentes, use o cmdlet Get-SPOTenantServicePrincipalPermissionRequests. Para cada solicitação de permissão, o cmdlet lista a ID (necessária para aprovar ou negar a solicitação), o recurso para o qual as permissões foram solicitadas e as permissões solicitadas.

Observação

O SharePoint não verifica se as permissões solicitadas já foram concedidas ou não, portanto, antes de aprovar ou rejeitar uma solicitação de permissão, verifique quais permissões já foram concedidas em seu locatário.
Para aprovar a solicitação de permissão específica, use o cmdlet Approve-SPOTenantServicePrincipalPermissionRequest -RequestId <Guid> , especificando a ID da solicitação de permissão que você deseja aprovar.

Observação

Se tentar aprovar a solicitação de uma permissão que já tenha sido concedida, você receberá um erro.
Para negar uma solicitação de permissão (se a permissão solicitada já tiver sido concedida ou a solicitação for contra suas políticas organizacionais), use o cmdlet Deny-SPOTenantServicePrincipalPermissionRequest -RequestId <Guid> , especificando a ID da solicitação de permissão que você deseja negar.

Observação

Recusar uma solicitação de permissão emitida por um aplicativo da Estrutura do SharePoint não impede que o aplicativo seja implantado no catálogo de aplicativos e instalado em sites.
Para visualizar quais permissões foram concedidas em seu locatário, use o cmdlet Get-SPOTenantServicePrincipalPermissionGrants. Para cada concessão, o cmdlet exibe as seguintes informações:
- ClientId: a objectId do consentimento concedido da entidade de serviço que representa o usuário durante o acesso ao recurso (representado pelo resourceId).
- ConsentType: Se o consentimento foi fornecido pelo administrador para a organização ou se o consentimento foi fornecido por um indivíduo. Os valores possíveis são "AllPrincipals" ou "Principal".
- ObjectId: o identificador exclusivo da concessão de permissão.
- Resource: o recurso ao qual o acesso foi concedido.
- ResourceId: o objectId da entidade de serviço do recurso ao qual o acesso foi concedido.
- Scope: o valor da declaração do escopo que o aplicativo de recursos deve esperar no token de acesso do OAuth 2.0.
Para revogar uma permissão concedida anteriormente, use o cmdlet Revoke-SPOTenantServicePrincipalPermission -ObjectId <String> . No parâmetro ObjectId, você deve especificar o objectId da concessão que deseja revogar, que pode ser obtido usando o cmdlet Get-SPOTenantServicePrincipalPermissionGrants.

Observação

A revogação de uma permissão não aciona alterações no catálogo de aplicativos ou em qualquer um dos aplicativos implantados. A única consequência da revogação de uma permissão é que nenhum aplicativo usado no locatário não será capaz de se conectar aos recursos para o qual a permissão foi revogada.

Gerenciar permissões usando a CLI do Microsoft 365

Os administradores globais o do SharePoint podem usar a CLI do Microsoft 365 para gerenciar permissões e solicitações de permissão no SharePoint Online.

Observação

A CLI do Microsoft 365 é uma solução de software livre com uma comunidade ativa oferecendo suporte. Não há nenhuma SLA para o suporte da ferramenta de software livre por parte da Microsoft.

Para visualizar todas as solicitações de permissão pendentes, use o comando spo serviceprincipal permissionrequest list. Para cada solicitação de permissão, o comando lista a ID (necessária para aprovar ou negar a solicitação), o recurso para o qual as permissões foram solicitadas e as permissões solicitadas.

Observação

O SharePoint não verifica se as permissões solicitadas já foram concedidas ou não, portanto, antes de aprovar ou rejeitar uma solicitação de permissão, verifique quais permissões já foram concedidas em seu locatário.
Para aprovar uma solicitação de permissão específica, use o comando spo serviceprincipal permissionrequest approve, especificando o ID da solicitação de permissão que deseja aprovar.

Observação

Se tentar aprovar a solicitação de uma permissão que já tenha sido concedida, você receberá um erro.
Para negar uma solicitação de permissão (se a permissão solicitada já foi concedida ou a solicitação é contra suas políticas organizacionais), use o comando spo serviceprincipal permissionrequest deny, especificando o ID da solicitação de permissão que você deseja negar.

Observação

Recusar uma solicitação de permissão emitida por um aplicativo da Estrutura do SharePoint não impede que o aplicativo seja implantado no catálogo de aplicativos e instalado em sites.
Para visualizar quais permissões foram concedidas em seu locatário, use o comando spo serviceprincipal grant list. Para cada concessão, o comando exibe as seguintes informações:
- ObjectId: o identificador exclusivo da concessão de permissão.
- Resource: o recurso ao qual o acesso foi concedido.
- ResourceId: o objectId da entidade de serviço do recurso ao qual o acesso foi concedido.
- Scope: o valor da declaração do escopo que o aplicativo de recursos deve esperar no token de acesso do OAuth 2.0.
Para revogar uma permissão concedida anteriormente, use o comando spo serviceprincipal grant revoke. No parâmetro grantId, especifique o objectId da concessão que deseja revogar, que pode ser obtida usando o comando spo serviceprincipal grant list.

Observação

A revogação de uma permissão não aciona alterações no catálogo de aplicativos ou em qualquer um dos aplicativos implantados. A única consequência da revogação de uma permissão é que nenhum aplicativo usado no locatário não será capaz de se conectar aos recursos para o qual a permissão foi revogada.

Conectar-se aos aplicativos do Azure AD usando o AadHttpClient

Introduzido na v1.4.1, a Estrutura do SharePoint simplifica a conexão com APIs protegidas com o Microsoft Azure AD. Ao usar o novo AadHttpClient, você pode conectar-se facilmente às APIs protegidas pelo Azure AD, sem ter que implementar a autenticação e a autorização por conta própria.

Internamente, o AadHttpClient implementa o fluxo Azure AD OAuth aproveitando plataforma de identidade da Microsoft bibliotecas de autenticação usando a entidade de serviço extensibilidade do cliente do SharePoint Online para obter um token de acesso válido. A entidade de serviço da Extensibilidade do Cliente do SharePoint Online é provisionada pela Microsoft e está disponível no Azure AD de todos os locatários do Office 365.

Para usar o AadHttpClient em sua solução da Estrutura do SharePoint, adicione a seguinte cláusula import ao arquivo principal da Web Part:
```
import { AadHttpClient, HttpClientResponse } from '@microsoft/sp-http';
```

Obtenha uma nova instância do AadHttpClient passando o recurso ao qual você deseja se conectar como parâmetros:

export default class HelloWorldWebPart extends BaseClientSideWebPart<IHelloWorldWebPartProps> {
  public render(): void {
    // ...

    this.context.aadHttpClientFactory
      .getClient('https://contoso.azurewebsites.net')
      .then((client: AadHttpClient): void => {
        // connect to the API
      });
  }

  // ...
}

Observação

Cada instância do AadHttpClient está vinculada a determinado recurso e é por isso que você precisa criar uma nova instância do cliente para cada recurso ao qual você deseja se conectar.

Depois que você criar uma instância do AadHttpClient para o recurso, poderá emitir uma solicitação da Web para se comunicar com sua API. Neste exemplo, a API retorna uma lista de pedidos representada pela interface personalizada Order que foi definida em outra parte do projeto.

export default class HelloWorldWebPart extends BaseClientSideWebPart<IHelloWorldWebPartProps> {
  public render(): void {
    // ...

    this.context.aadHttpClientFactory
      .getClient('https://contoso.azurewebsites.net')
      .then((client: AadHttpClient): void => {
        client
          .get('https://contoso.azurewebsites.net/api/orders', AadHttpClient.configurations.v1)
          .then((response: HttpClientResponse): Promise<Order[]> => {
            return response.json();
          })
          .then((orders: Order[]): void => {
            // process data
          });
      });
  }

  // ...
}

Considerações

Veja a seguir algumas considerações que você deve avaliar ao trabalhar com permissões de API Web.

Solicitar permissões por meio de soluções da Estrutura do SharePoint

No momento, só é possível solicitar outras permissões por meio de uma solução da Estrutura do SharePoint. A solicitação será iniciada quando o pacote da solução (.sppkg) contendo uma solicitação de permissões for implantado no catálogo de aplicativos. Depois que a solicitação é iniciada, ela pode ser aprovada ou negada por um Administrador global ou Administrador de serviços do SharePoint.

As permissões concedidas se aplicam a todas as soluções

Embora as permissões para recursos do Azure AD estejam sendo solicitadas por uma solução da Estrutura do SharePoint, uma vez concedidas, elas se aplicarão ao locatário inteiro e poderão ser utilizadas por qualquer solução desse locatário.

Remover a solução não revogará permissões

Remover a solução que inicialmente solicitou a permissão específica não revogará a permissão concedida. Os administradores devem revogar manualmente as permissões concedidas nas solicitações de aplicativos da Estrutura do SharePoint.

Revogar permissões concedidas anteriormente não invalida tokens de acesso emitidos.

Revogar permissões concedidas anteriormente não invalida tokens de acesso emitidos para os usuários. Em vez disso, esses tokens de acesso permanecem válidos até expirarem.

A solicitação de permissões não afeta a implantação da solução

Independentemente de o administrador negar ou aprovar permissões solicitadas pela solução, a solução poderá ser implantada e usada em sites. Durante a criação de soluções que exigem permissões adicionais, jamais pressuponha que as permissões solicitadas já foram concedidas.

Controlar a entidade de serviço do Cliente do SharePoint Online

Todas as permissões concedidas pelas solicitações da API Web serão armazenadas no aplicativo do Azure AD da Extensibilidade do Cliente do SharePoint Online. Se os administradores não quiserem que os desenvolvedores usem o modelo de solicitação da API Web, o MSGraphClient e o AadHttpClient em suas soluções, eles poderão desativar o serviço principal de Extensibilidade do Cliente do SharePoint Online por meio do Windows PowerShell usando o cmdlet Disable-SPOTenantServicePrincipal.

A entidade de serviço pode ser reativada usando o cmdlet Enable-SPOTenantServicePrincipal. Em vez disso, também é possível habilitar e desabilitar a entidade de serviço Extensibilidade de Cliente do SharePoint Online por meio da CLI para Microsoft 365 usando o comando spo serviceprincipal set.

Conectar-se às APIs protegidas pelo Azure AD em soluções da Estrutura do SharePoint

Visão geral de permissões de API Web

Descobrir os aplicativos e permissões disponíveis

Usar o portal do Azure ou o centro de administração do Azure AD

Usar o Azure PowerShell

Usar a CLI do Azure

Abrir a lista de escopos de permissão expostos pelo aplicativo

Solicitar permissões para um aplicativo do Azure AD

Gerenciar solicitações de permissão

Gerenciar sites no novo Centro de Administração do SharePoint Online

Gerenciar permissões com o Windows PowerShell

Gerenciar permissões usando a CLI do Microsoft 365

Conectar-se aos aplicativos do Azure AD usando o AadHttpClient

Considerações

Solicitar permissões por meio de soluções da Estrutura do SharePoint

As permissões concedidas se aplicam a todas as soluções

Remover a solução não revogará permissões

Revogar permissões concedidas anteriormente não invalida tokens de acesso emitidos.

A solicitação de permissões não afeta a implantação da solução

Controlar a entidade de serviço do Cliente do SharePoint Online

Recursos adicionais