Compartilhar via


Conceder permissões RSC à sua aplicação

O consentimento específico do recurso (RSC) é uma integração do Microsoft Teams e da Microsoft Graph API que permite que a sua aplicação utilize pontos finais de API para gerir recursos específicos, equipas, chats ou utilizadores numa organização.

Nesta secção, irá aprender a:

  1. Adicionar permissões RSC à sua aplicação Teams
  2. Instalar a sua aplicação numa equipa, chat ou utilizador
  3. Verificar a permissão RSC da aplicação concedida à sua aplicação

Adicionar permissões RSC à sua aplicação Teams

Para adicionar permissões RSC à sua aplicação, siga estes passos:

  1. Registe a sua aplicação na plataforma de identidades da Microsoft através do centro de administração do Microsoft Entra.
  2. Atualize o manifesto da sua aplicação (anteriormente denominado manifesto de aplicação do Teams).

Registar a sua aplicação na plataforma de identidades da Microsoft através do centro de administração do Microsoft Entra

O centro de administração do Microsoft Entra fornece uma plataforma central para registar e configurar as suas aplicações. Tem de registar a sua aplicação no centro de administração do Microsoft Entra para se integrar na plataforma de identidade e chamar as Graph APIs. Para obter mais informações, veja Registar uma aplicação na plataforma de identidade.

Aviso

Não tem de partilhar o ID da aplicação Microsoft Entra em várias aplicações do Teams. Tem de existir um mapeamento 1:1 entre uma aplicação teams e uma aplicação Microsoft Entra. A instalação de várias aplicações do Teams associadas ao mesmo ID da aplicação Microsoft Entra causará falhas de instalação ou de tempo de execução.

Atualizar seu manifesto do aplicativo

Tem de declarar permissões RSC no ficheiro de manifest.json da aplicação. Não precisa de adicionar as permissões não RSC ao manifesto da aplicação, uma vez que o centro de administração do Microsoft Entra as armazena.

Pedir permissões RSC para a aplicação Teams

Para pedir permissões RSC para uma aplicação, liste as permissões necessárias para a aplicação na secção de autorização do manifesto da aplicação. As instruções podem variar com base na versão do manifesto da aplicação.

Observação

Para permissões delegadas, utilize o manifesto de aplicação v1.12 ou posterior.

Sempre que um utilizador autorizado instala a sua aplicação no Teams, as permissões RSC pedidas no manifesto da aplicação são apresentadas ao utilizador. As permissões são concedidas como parte do processo de instalação da aplicação.


Permissões RSC para o manifesto da aplicação v1.12 ou posterior

Para adicionar a permissão RSC no manifesto da aplicação:

  1. Adicione a chave webApplicationInfo ao manifesto da aplicação com os seguintes valores:

    Nome Tipo Descrição
    id Cadeia de caracteres O seu ID da aplicação Microsoft Entra. Para obter mais informações, consulte Registar a sua aplicação no centro de administração do Microsoft Entra.
    resource Cadeia de caracteres Este campo não tem nenhuma operação no RSC, mas tem de adicionar um valor para evitar uma resposta de erro. Pode adicionar qualquer cadeia como valor.
  2. Adicione as permissões necessárias para a sua aplicação.

    Nome Tipo Descrição
    authorization Objeto Lista de permissões que o aplicativo precisa para funcionar. Para obter mais informações, veja autorização no manifesto da aplicação.

    Se uma aplicação se destinar a suportar a instalação nos âmbitos da equipa e do chat, as permissões de equipa e de chat podem ser especificadas no mesmo manifesto authorizationde aplicação em .

Exemplo de permissões RSC numa equipa:

"webApplicationInfo": {
    "id": "XXxxXXXXX-XxXX-xXXX-XXxx-XXXXXXXxxxXX",
    "resource": "https://RscBasedStoreApp"
    },
"authorization": {
    "permissions": {
        "resourceSpecific": [
            {
                "name": "TeamSettings.Read.Group",
                "type": "Application"
            },
            {
                "name": "TeamSettings.ReadWrite.Group",
                "type": "Application"
            },
            {
                "name": "ChannelSettings.Read.Group",
                "type": "Application"
            },
            {
                "name": "ChannelSettings.ReadWrite.Group",
                "type": "Application"
            },
            {
                "name": "Channel.Create.Group",
                "type": "Application"
            },
            {
                "name": "Channel.Delete.Group",
                "type": "Application"
            },
            {
                "name": "ChannelMessage.Read.Group",
                "type": "Application"
            },
            {
                "name": "TeamsAppInstallation.Read.Group",
                "type": "Application"
            },
            {
                "name": "TeamsTab.Read.Group",
                "type": "Application"
            },
            {
                "name": "TeamsTab.Create.Group",
                "type": "Application"
            },
            {
                "name": "TeamsTab.ReadWrite.Group",
                "type": "Application"
            },
            {
                "name": "TeamsTab.Delete.Group",
                "type": "Application"
            },
            {
                "name": "TeamMember.Read.Group",
                "type": "Application"
            },
            {
                "name": "TeamsActivity.Send.Group",
                "type": "Application"
            },
            {
              "name": "ChannelMeeting.ReadBasic.Group",
              "type": "Delegated"
            },
            {
              "name": "ChannelMeetingParticipant.Read.Group",
              "type": "Delegated"
            },
            {
              "name": "ChannelMeetingStage.Write.Group",
              "type": "Delegated"
            }
        ]
    }
}

Exemplo de permissões RSC numa conversa:

"webApplicationInfo": {
    "id": "XXxxXXXXX-XxXX-xXXX-XXxx-XXXXXXXxxxXX",
    "resource": "https://RscBasedStoreApp"
    },
"authorization": {
    "permissions": {
        "resourceSpecific": [
            {
                "name": "ChatSettings.Read.Chat",
                "type": "Application"
            },
            {
                "name": "ChatSettings.ReadWrite.Chat",
                "type": "Application"
            },
            {
                "name": "ChatMessage.Read.Chat",
                "type": "Application"
            },
            {
                "name": "ChatMember.Read.Chat",
                "type": "Application"
            },
            {
                "name": "Chat.Manage.Chat",
                "type": "Application"
            },
            {
                "name": "TeamsTab.Read.Chat",
                "type": "Application"
            },
            {
                "name": "TeamsTab.Create.Chat",
                "type": "Application"
            },
            {
                "name": "TeamsTab.Delete.Chat",
                "type": "Application"
            },
            {
                "name": "TeamsTab.ReadWrite.Chat",
                "type": "Application"
            },
            {
                "name": "TeamsAppInstallation.Read.Chat",
                "type": "Application"
            },
            {
                "name": "OnlineMeeting.ReadBasic.Chat",
                "type": "Application"
            },
            {
                "name": "Calls.AccessMedia.Chat",
                "type": "Application"
            },
            {
                "name": "Calls.JoinGroupCalls.Chat",
                "type": "Application"
            },
            {
                "name": "TeamsActivity.Send.Chat",
                "type": "Application"
            },
            {
                "name": "MeetingStage.Write.Chat",
                "type": "Delegated"
            }
        ]
    }
}

Exemplo de permissões RSC para o utilizador:

"webApplicationInfo": {
    "id": "XXxxXXXXX-XxXX-xXXX-XXxx-XXXXXXXxxxXX",
    "resource": "https://RscBasedStoreApp"
    },
"authorization": {
    "permissions": {
        "orgWide": []
        "resourceSpecific": [
            {
                "name": "InAppPurchase.Allow.User",
                "type": "Delegated"
            },
            {
                "name": "TeamsActivity.Send.User",
                "type": "Application"
            },
        ]
    }
}


Permissões RSC para o manifesto da aplicação v1.11 ou anterior

Observação

É recomendado utilizar o manifesto da aplicação v1.12 ou posterior.

Adicione a chave webApplicationInfo ao manifesto da aplicação com os seguintes valores:

Nome Tipo Descrição
id Cadeia de caracteres O seu ID da aplicação Microsoft Entra. Para obter mais informações, consulte Registar a sua aplicação no centro de administração do Microsoft Entra.
resource Cadeia de caracteres Este campo não tem nenhuma operação no RSC, mas tem de adicionar um valor para evitar uma resposta de erro. Pode adicionar qualquer cadeia como valor.
applicationPermissions Matriz de cadeias de caracteres Permissões RSC para a sua aplicação. Para obter mais informações, veja Permissões de RSC suportadas.

Se uma aplicação se destinar a suportar a instalação nos âmbitos da equipa e do chat, as permissões de equipa e de chat podem ser especificadas no mesmo manifesto applicationPermissionsde aplicação em .

Exemplo de permissões RSC numa equipa:

"webApplicationInfo": {
    "id": "XXxxXXXXX-XxXX-xXXX-XXxx-XXXXXXXxxxXX",
    "resource": "https://RscBasedStoreApp",
    "applicationPermissions": [
        "TeamSettings.Read.Group",
        "TeamSettings.ReadWrite.Group",
        "ChannelSettings.Read.Group",
        "ChannelSettings.ReadWrite.Group",
        "Channel.Create.Group",
        "Channel.Delete.Group",
        "ChannelMessage.Read.Group",
        "TeamsAppInstallation.Read.Group",
        "TeamsTab.Read.Group",
        "TeamsTab.Create.Group",
        "TeamsTab.ReadWrite.Group",
        "TeamsTab.Delete.Group",
        "TeamMember.Read.Group",
        "TeamsActivity.Send.Group"
    ]
  }

Exemplo de permissões RSC numa conversa:

"webApplicationInfo": {
    "id": "XXxxXXXXX-XxXX-xXXX-XXxx-XXXXXXXxxxXX",
    "resource": "https://RscBasedStoreApp",
    "applicationPermissions": [
        "ChatSettings.Read.Chat",
        "ChatSettings.ReadWrite.Chat",
        "ChatMessage.Read.Chat",
        "ChatMember.Read.Chat",
        "Chat.Manage.Chat",
        "TeamsTab.Read.Chat",
        "TeamsTab.Create.Chat",
        "TeamsTab.Delete.Chat",
        "TeamsTab.ReadWrite.Chat",
        "TeamsAppInstallation.Read.Chat",
        "OnlineMeeting.ReadBasic.Chat",
        "Calls.AccessMedia.Chat",
        "Calls.JoinGroupCalls.Chat",
        "TeamsActivity.Send.Chat"
    ]
  }

Exemplo de permissões RSC para um utilizador:

"webApplicationInfo": {
    "id": "XXxxXXXXX-XxXX-xXXX-XXxx-XXXXXXXxxxXX",
    "resource": "https://RscBasedStoreApp",
    "applicationPermissions": [
        "TeamsActivity.Send.User"
    ]
  }

Instalar a sua aplicação numa equipa, chat ou utilizador

Para instalar a sua aplicação na qual ativou a permissão RSC numa equipa, chat ou utilizador, siga estes passos:

  1. Certifique-se de que configurou as definições de consentimento para a equipa, o chat ou o utilizador.
  2. Carregue a sua aplicação personalizada no Teams.

Observação

Para ver as definições de RSC para a equipa ou o chat, os utilizadores têm de ter uma destas funções do Microsoft 365:

  • Administrador global
  • Leitor global
  • Administrador do Teams
  • Administrador de Função Privilegiada

Os controlos ao nível do inquilino das permissões RSC da aplicação variam com base no tipo de recurso.

Para permissões delegadas, qualquer utilizador autorizado pode consentir as permissões pedidas pela aplicação.

Aviso

A forma como gere as definições de permissão RSC de chat e equipa está a ser atualizada. O período de pré-seleção para clouds governamentais começou e continua até 14 de maio de 2024. Durante este período, as organizações governamentais da cloud podem continuar a utilizar o Consentimento do Proprietário do Grupo. Para todas as outras organizações, seguem-se as instruções para modificar as definições de consentimento no PowerShell.

Para organizações em clouds governamentais, pode gerir as definições de consentimento com as definições de consentimento do proprietário do grupo no centro de administração do Microsoft Entra até 14 de maio de 2024.

As definições de RSC ao nível do inquilino são geridas pelo PowerShell e pela Graph API. Para obter mais informações sobre como gerir as definições do Microsoft Graph com o PowerShell, veja Introdução ao SDK do PowerShell do Microsoft Graph.

Pode utilizar o Connect-MgGraph cmdlet e ligar-se com as seguintes permissões:

  1. TeamworkAppSettings.ReadWrite.All
  2. Policy.ReadWrite.Authorization
  3. Policy.ReadWrite.PermissionGrant
  4. AppCatalog.Read.All

Seguem-se os estados disponíveis para as definições do PowerShell e cada secção mostra exemplos de como utilizar estes estados para ajustar as suas definições:

Estado do PowerShell Descrição
ManagedByMicrosoft Este é o estado predefinido para todos os inquilinos. Permite que as permissões de chat e RSC de equipa sejam consentidas para todos os utilizadores, mas podem ser alteradas a qualquer momento, a critério da Microsoft.
EnabledForAllApps Qualquer aplicação que solicite permissões RSC pode ser consentida pelos utilizadores (proprietários de recursos) no seu inquilino.
DisabledForAllApps Os utilizadores não podem consentir permissões RSC.

Configurar o RSC da equipa através de cmdlets do PowerShell

Pode configurar os utilizadores que têm permissão para dar consentimento às aplicações que acedem aos dados das suas equipas através dos estados do PowerShell disponíveis, como ManagedByMicrosoft, EnabledForAllApps e DisabledForAllApps.

O exemplo seguinte mostra como ativar o RSC da equipa para todas as aplicações:

Set-MgBetaTeamRscConfiguration -State EnabledForAllApps

Configurar o RSC de chat através de cmdlets do PowerShell

Pode configurar os utilizadores que têm permissão para dar consentimento às aplicações que acedem aos dados das respetivas conversas através dos estados disponíveis do PowerShell, como ManagedByMicrosoft, EnabledForAllApps e DisabledForAllApps.

O exemplo seguinte mostra como ativar o chat RSC para todas as aplicações:

Set-MgBetaChatRscConfiguration -State EnabledForAllApps

Configurar as definições de consentimento do proprietário do utilizador para RSC para um utilizador com as Graph APIs

Pode ativar ou desativar o RSC para o utilizador com a Graph API. A isUserPersonalScopeResourceSpecificConsentEnabled propriedade no teamsAppSettings regula se o RSC do utilizador está ativado no inquilino.

A captura de ecrã mostra a configuração do utilizador do Graph RSC.

O valor predefinido da isUserPersonalScopeResourceSpecificConsentEnabled propriedade baseia-se se as definições de consentimento do utilizador estão ativadas ou desativadas no inquilino quando o RSC para utilizador é utilizado pela primeira vez. O valor predefinido é definido quando:

  • O TeamsAppSettings é obtido pela primeira vez.
  • A aplicação Teams com permissões RSC é instalada para um utilizador.

Observação

O controlo de administração é adicionado para permitir ou bloquear definições de consentimento RSC com base na confidencialidade dos dados acedidos. Não se baseia no comutador principal único que ativa ou desativa as definições de consentimento para permissões RSC da aplicação para todas as aplicações no inquilino.


Carregar a sua aplicação personalizada no Teams

Se o seu administrador do Teams permitir carregamentos de aplicações personalizados, pode carregar a sua aplicação personalizada diretamente para uma equipa, conversa ou utilizador específico.

Verificar a permissão RSC da aplicação concedida à sua aplicação

Para verificar as permissões RSC da aplicação, siga estes passos:

  1. Obtenha um token de acesso a partir da plataforma de identidades da Microsoft.
  2. Verifique as permissões RSC concedidas a um recurso específico.

Obter um token de acesso da plataforma de identidade da Microsoft

Para fazer API do Graph chamadas, você deve obter um token de acesso para seu aplicativo da plataforma de identidade. Para que a sua aplicação possa obter um token da plataforma de identidade, tem de registar a sua aplicação no centro de administração do Microsoft Entra. O token de acesso contém informações sobre a sua aplicação e as respetivas permissões para os recursos e APIs disponíveis através do Microsoft Graph.

Tem de ter os seguintes valores do processo de registo do Microsoft Entra para obter um token de acesso a partir da plataforma de identidade:

  • ID da Aplicação: o ID da aplicação atribuído pelo centro de administração do Microsoft Entra à sua aplicação. Se a sua aplicação suportar o início de sessão único (SSO), tem de utilizar o mesmo ID de aplicação para a sua aplicação e SSO.
  • Segredo do cliente ou Certificado: a palavra-passe da sua aplicação ou o par de chaves públicas ou privadas que é o certificado. O segredo ou certificado do cliente não é necessário para aplicações nativas.
  • URI de Redirecionamento: o URL para a sua aplicação receber respostas do Microsoft Entra ID.

Para obter mais informações, consulte Obter acesso em nome de um usuário e Obtenha acesso sem um usuário.

Verificar as permissões RSC concedidas a um recurso específico

Pode verificar o tipo de permissão RSC concedida a um recurso na aplicação:

  • Para permissões RSC da aplicação, chame as seguintes APIs para obter a lista de aplicações instaladas numa equipa, chat ou utilizador:

    Estas são todas as permissões RSC da aplicação concedidas neste recurso específico. Cada entrada na lista pode ser correlacionada com a aplicação Teams ao corresponder a clientAppId na lista de concessões de permissões com a webApplicationInfo.Id propriedade no manifesto da aplicação.

  • As permissões RSC delegadas são permissões apenas de cliente do Teams. Não pode obter a lista de aplicações instaladas numa equipa ou chat, uma vez que estas permissões são concedidas quando um utilizador interage com a aplicação.

Importante

As permissões RSC não são atribuídas a um utilizador. As chamadas são efetuadas com permissões de aplicação e não com permissões delegadas pelo utilizador. A aplicação pode ser autorizada a executar ações que o utilizador não consegue, como eliminar um separador. Tem de rever a intenção do proprietário da equipa ou do proprietário do chat para a sua utilização antes de efetuar chamadas à API RSC. Para obter mais informações, consulte Visão geral da API do Microsoft Teams.

Depois de a aplicação ter sido instalada num recurso, pode utilizar o Explorador do Microsoft Graph para ver as permissões que foram concedidas à aplicação no recurso.

Verifique seu aplicativo para obter permissões de RSC adicionadas em uma equipe

  1. Obtenha o groupId do Teams.

  2. No Teams, selecione Teams no painel esquerdo.

  3. Selecione a equipe em que o aplicativo deve ser instalado.

  4. Selecione as reticências ●●● para essa equipa.

  5. Selecione Obter ligação para a equipa na lista pendente.

  6. Copie e guarde o valor groupId na caixa de diálogo de pop-up Obter uma ligação para a equipa .

  7. Entre no Explorador do Graph.

  8. Faça uma chamada GET para este ponto de extremidade: https://graph.microsoft.com/beta/teams/{teamGroupId}/permissionGrants.

    O clientAppId campo na resposta tem de mapear para o webApplicationInfo.id especificado no manifesto da aplicação.

    Captura de ecrã a mostrar a resposta do explorador do Graph à chamada GET para permissões RSC de equipa.

Para obter mais informações sobre como obter detalhes dos aplicativos instalados em uma equipe específica, consulte obter os nomes e outros detalhes dos aplicativos instalados na equipe especificada.

Verifique seu aplicativo para obter permissões de RSC adicionadas em um chat

  1. Obtenha a ID do encadeamento de bate-papo do cliente Web do Teams.

  2. No cliente Web do Teams, selecione Chat no painel esquerdo.

  3. Selecione o chat onde instalou a aplicação a partir da lista pendente.

  4. Copie o URL da web e salve o ID do tópico de chat da string.

    Captura de ecrã a mostrar o ID do tópico de chat do URL da Web.

  5. Entre no Explorador do Graph.

  6. Faça uma chamada GET para o seguinte ponto de extremidade: https://graph.microsoft.com/beta/chats/{chatId}/permissionGrants.

    O clientAppId campo na resposta tem de mapear para o webApplicationInfo.id especificado no manifesto da aplicação.

    Captura de ecrã a mostrar a resposta do explorador do Graph à chamada GET para permissões RSC de chat.

Para obter mais informações sobre como obter detalhes de aplicativos instalados em um chat específico, consulte obter os nomes e outros detalhes dos aplicativos instalados no chat especificado.

Verificar se existem permissões RSC adicionadas à sua aplicação para um utilizador

  1. Utilize a API Obter utilizador. No URL do pedido, transmita o UPN do utilizador e, a partir do corpo da resposta, utilize o id campo como ID do utilizador.

  2. Entre no Explorador do Graph.

  3. Faça uma chamada GET para este ponto de extremidade: https://graph.microsoft.com/beta/users/{user-id}/permissionGrants.

    Em alternativa, pode transmitir o UPN do utilizador em vez do user-id.

    O clientAppId campo na resposta tem de ser mapeado para o webApplicationInfo.id especificado no manifesto da aplicação Teams.

    Captura de ecrã a mostrar a resposta do explorador do Graph à chamada GET para permissões RSC do utilizador.

Para obter mais informações sobre como obter detalhes sobre as aplicações instaladas para o utilizador, consulte Obter os nomes e outros detalhes das aplicações instaladas para o utilizador.

Exemplo de código

Nome de exemplo Descrição .NET Node.js Manifesto do aplicativo
RSC (Consentimento Específico do Recurso) Este código de exemplo descreve o processo de utilização do RSC para chamar Graph APIs. View View View
Configurar permissões RSC Este código de exemplo demonstra como configurar permissões RSC no manifesto da aplicação, utilizá-las para invocar o Microsoft Graph e observar a resposta real com o âmbito instalado. NA View NA

Confira também