Ativar o SSO para extensões de mensagens baseadas em API

Artigo
10/28/2024

O método de autenticação de início de sessão único (SSO) para a extensão de mensagens baseada em API utiliza a identidade do Teams de um utilizador da aplicação para lhes fornecer acesso à sua aplicação. Um utilizador que tenha sessão iniciada no Teams não precisa de iniciar sessão novamente na sua aplicação no ambiente do Teams. Microsoft Entra SSO permite que a aplicação obtenha automaticamente um token de utilizador que é emitido para o respetivo recurso por Microsoft Entra. Em seguida, a aplicação pode autenticar este token e obter as informações do perfil de utilizador sem o consentimento do utilizador.

Pré-requisitos

Antes de começar, certifique-se de que tem o seguinte:

Uma conta do Azure com uma subscrição ativa.
Conhecimentos básicos sobre Microsoft Entra ID e desenvolvimento de aplicações do Teams.

A imagem seguinte mostra como o SSO funciona quando um utilizador da aplicação Teams tenta aceder à aplicação de extensão de mensagens baseada em API:

O utilizador invoca a aplicação de extensão de mensagens baseada em API no Teams e invoca um comando que requer autenticação.
A aplicação envia um pedido para o serviço de back-end do Teams com o ID da aplicação e o âmbito necessário (access_as_user).
O serviço de back-end do Teams verifica se o utilizador deu consentimento à aplicação e ao âmbito. Caso contrário, mostra um ecrã de consentimento ao utilizador.
Se o utilizador consentir, Microsoft Entra gera um token de acesso para o utilizador e a aplicação e envia-o para a aplicação no cabeçalho de autorização do pedido.
A aplicação valida o token e extrai as informações do utilizador do token, como o nome, o e-mail e o ID do objeto.
Após a autenticação bem-sucedida, é concedido ao utilizador acesso à extensão de mensagens baseada em API.

Para ativar a autenticação SSO para a extensão de mensagens baseada em API, siga estes passos:

Registe uma nova aplicação no Microsoft Entra ID.
Configurar o âmbito do token de acesso.
Autenticar token.
Atualize o manifesto da aplicação.

Registar uma nova aplicação no Microsoft Entra ID

No navegador da Web, vá para o Portal do Azure.
Selecione o ícone Registros de aplicativo.

A página Registros de aplicativo é exibida.
Selecione o ícone + Novo registro.

A página Registrar um aplicativo é exibida.
Insira o nome do aplicativo que você deseja exibir para o usuário do aplicativo. Se quiser, pode alterar o nome numa fase posterior.

Selecione o tipo de conta de usuário que pode acessar seu aplicativo. Pode selecionar a partir de opções individuais ou multi-inquilinos em diretórios organizacionais ou restringir o acesso apenas a contas Microsoft pessoais.

Opções para tipos de conta suportados

Opção	Selecione essa opção para...
Contas apenas neste diretório organizacional (apenas Microsoft - Inquilino único)	Crie um aplicativo para uso somente por usuários (ou convidados) em seu locatário. Muitas vezes denominada aplicação personalizada criada para a sua organização (aplicação LOB), esta aplicação é uma aplicação de inquilino único no plataforma de identidade da Microsoft.
Contas em qualquer diretório organizacional (qualquer inquilino Microsoft Entra ID - Multi-inquilino)	Permitir que os utilizadores em qualquer inquilino Microsoft Entra utilizem a sua aplicação. Esta opção é adequada se, por exemplo, estiver a criar uma aplicação SaaS e pretender disponibilizá-la a várias organizações. Este tipo de aplicação é conhecido como uma aplicação multi-inquilino na plataforma de identidade da Microsoft.
Contas em qualquer diretório organizacional (qualquer Microsoft Entra ID inquilino - Multi-inquilino) e contas Microsoft pessoais (por exemplo, Skype, Xbox)	Destina-se ao conjunto mais amplo de clientes. Ao selecionar esta opção, está a registar uma aplicação multi-inquilino que também pode suportar utilizadores de aplicações que tenham contas Microsoft pessoais.
Contas pessoais da Microsoft	Crie um aplicativo somente para usuários que têm contas pessoais da Microsoft.

Observação

Não precisa de introduzir o URI de Redirecionamento para ativar o SSO para uma aplicação de extensão de mensagens baseada em API.

Selecione Registrar. Uma mensagem é exibida no navegador informando que o aplicativo foi criado.

É apresentada a página com o ID da aplicação e outros detalhes da aplicação.
Anote e guarde o ID da aplicação do ID da Aplicação (cliente) para atualizar o manifesto da aplicação mais tarde.

A sua aplicação está registada no Microsoft Entra ID. Tem agora o ID da aplicação para a sua aplicação de extensão de mensagens baseada em API.

Configurar o escopo para o token de acesso

Depois de criar um novo registo de aplicações, configure as opções de âmbito (permissão) para enviar o token de acesso para o cliente do Teams e autorizar aplicações cliente fidedignas para ativar o SSO.

Para configurar o âmbito e autorizar aplicações cliente fidedignas, tem de:

Adicionar URI do ID da Aplicação: configure as opções de âmbito (permissão) para a sua aplicação. Expor uma API Web e configurar o URI do ID da aplicação.
Configurar o âmbito da API: defina o âmbito da API e os utilizadores que podem consentir um âmbito. Você pode permitir que somente administradores forneçam consentimento para permissões com privilégios mais altos.
Configurar a aplicação cliente autorizada: crie IDs de cliente autorizados para aplicações que pretende pré-autorizar. Isso permite que o usuário do aplicativo acesse os escopos do aplicativo (permissões) que você configurou, sem a necessidade de qualquer consentimento adicional. Pré-autorizar apenas as aplicações cliente nas quais confia, uma vez que os utilizadores da sua aplicação não têm a oportunidade de recusar o consentimento.

URI da ID do Aplicativo

Selecione Gerenciar>Expor uma API no painel esquerdo.

A página Expor uma API é exibida.
Selecione Adicionar para gerar o URI do ID da aplicação sob a forma de api://{AppID}.

É apresentada a secção para definir o URI do ID da aplicação.
Introduza o URI do ID da Aplicação no formato explicado aqui.
- O URI do ID da Aplicação está pré-preenchido com o ID da aplicação (GUID) no formato api://{AppID}.
- O formato URI do ID da aplicação tem de ser: api://fully-qualified-domain-name.com/{AppID}.
- Insira fully-qualified-domain-name.com entre api:// e {AppID} (ou seja, a GUID). Por exemplo, api://example.com/{AppID}.
Importante
- Se estiver a criar um bot autónomo, introduza o URI do ID da aplicação como api://botid-{YourBotId}. Aqui, {YourBotId} é o seu ID de aplicação Microsoft Entra.
- Se estiver a criar uma aplicação com um bot, uma extensão de mensagem e um separador, introduza o URI do ID da aplicação como api://fully-qualified-domain-name.com/botid-{YourClientId}, em que {YourClientId} é o ID da aplicação de bot.
- Se estiver a criar uma aplicação com uma extensão de mensagem ou capacidades de separador sem o bot, introduza o URI do ID da aplicação como api://fully-qualified-domain-name.com/{YourClientId}, em que {YourClientId} é o seu ID de aplicação Microsoft Entra.
- URI do ID da Aplicação para a aplicação com múltiplas capacidades: se estiver a criar uma extensão de mensagem baseada em API, introduza o URI do ID da aplicação como api://fully-qualified-domain-name.com/{YourClientId}, em que {YourClientId} é o seu ID de aplicação Microsoft Entra.
- Formato do nome de domínio: utilize apenas letras minúsculas para o nome de domínio.
Selecione Salvar.

É apresentada uma mensagem no browser a indicar que o URI do ID da aplicação foi atualizado.

O URI do ID da aplicação é apresentado na página.
Anote e guarde o URI do ID da aplicação para atualizar o manifesto da aplicação mais tarde.

Configurar o âmbito da API

Observação

A extensão de mensagens baseada em API suporta apenas o âmbito de access_as_user .
A API recebe um token de acesso Microsoft Entra com o âmbito definido access_as_user como registado no portal do Azure. No entanto, o token não está autorizado a chamar outras APIs a jusante, como o Microsoft Graph.

Selecione + Adicionar um escopo nos Escopos definidos por esta seção de API.

A página Adicionar um escopo é exibida.
Insira os detalhes para configurar o escopo.
1. Insira o nome do escopo. Este campo é obrigatório.
2. Selecione o usuário que pode dar consentimento para este escopo. A opção padrão é Somente administradores.
3. Insira o Nome de exibição de consentimento do administrador. Este campo é obrigatório.
4. Insira a descrição do consentimento do administrador. Este campo é obrigatório.
5. Insira o Nome de exibição do consentimento do usuário.
6. Insira a descrição para o consentimento do usuário.
7. Selecione a opção Habilitado para o estado.
8. Selecione Adicionar escopo.
Uma mensagem é exibida no navegador informando que o escopo foi adicionado.

O novo escopo que você definiu é exibido na página.

Configurar a aplicação cliente autorizada

Percorra a página Expor uma API para a secção Aplicação cliente autorizada e selecione + Adicionar uma aplicação cliente.

A página Adicionar um aplicativo cliente será exibida.

Introduza o ID de cliente do Microsoft 365 adequado para as aplicações que pretende autorizar para a aplicação Web da sua aplicação.

Captura de ecrã a mostrar a opção ID de Cliente e Âmbitos autorizados para adicionar uma aplicação cliente à aplicação no portal do Azure. Adicionar uma aplicação cliente

Observação

Os IDs de cliente do Microsoft 365 para aplicações móveis, de ambiente de trabalho e Web para o Teams são os IDs reais que tem de adicionar.

Selecione um dos seguintes IDs de cliente:

Usar a ID do cliente	Para autorizar...
1fec8e78-bce4-4aaf-ab1b-5451cc387264	Aplicação teams para dispositivos móveis ou de ambiente de trabalho
5e3ce6c0-2b1f-4285-8d4b-75ee78787346	Aplicativo web do Teams

Selecione o URI do ID da aplicação que criou para a sua aplicação em Âmbitos autorizados para adicionar o âmbito à API Web que expôs.
Selecione Adicionar aplicativo.

Uma mensagem é exibida no navegador informando que o aplicativo cliente autorizado foi adicionado.

O ID de cliente da aplicação autorizada é apresentado na página.

Observação

Você pode autorizar mais de um aplicativo cliente. Repita as etapas deste procedimento para configurar outro aplicativo cliente autorizado.

Configurou com êxito o âmbito da aplicação, as permissões e as aplicações cliente. Certifique-se de que anota e guarda o URI do ID da aplicação. Em seguida, configure a versão do token de acesso.

Autenticar token

Quando a extensão de mensagem chama a API durante a autenticação, recebe um pedido com o token de acesso do utilizador. Em seguida, a extensão da mensagem adiciona o token no cabeçalho de autorização do pedido HTTP de saída. O formato do cabeçalho é Authorization: Bearer <token_value>. Por exemplo, quando uma extensão de mensagem faz uma chamada à API para um serviço que requer autenticação. A extensão cria um pedido HTTP da seguinte forma:

GET /api/resource HTTP/1.1
Host: api.example.com
Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiaWF0IjoxNTE2MjM5MDIyfQ.SflKxwRJSMeKKF2QT4fwpMeJf36POk6yJV_adQssw5c

Depois de a extensão de mensagem baseada em API receber um cabeçalho de pedido com token, execute os seguintes passos:

Autenticar: verifique o token para a audiência, âmbito, emissor e afirmações de assinatura para marcar se o token for para a sua aplicação. Para obter mais afirmações, veja Afirmações de tokens de ID.

O exemplo seguinte mostra o JSON Web Token (JWT) com um cabeçalho e uma resposta:

Token V2
Token V1

{
"typ": "JWT",
"rh": "0.AhoAv4j5cvGGr0GRqy180BHbR6Rnn7s7iddIqxdA7UZsDxYaABY.",
"alg": "RS256",
"kid": "q-23falevZhhD3hm9CQbkP5MQyU"
}.{
  "aud": "00000002-0000-0000-c000-000000000000",
  "iss": "https://login.microsoftonline.com/72f988bf-86f1-41af-91ab-2d7cd011db47/v2.0",
  "iat": 1712509315,
  "nbf": 1712509315,
  "exp": 1712513961,
  "aio": "Y2NgYEjJqF0stqv73u41a6ZmxPEvBgA=",
  "azp": "1fec8e78-bce4-4aaf-ab1b-5451cc387264",
  "azpacr": "0",
  "name": "John Doe",
  "oid": "00000000-0000-0000-0000-000000000000",
  "preferred_username": "john.doe@contoso.com",
  "rh": "I",
  "scp": "access_as_user",
  "sub": "e4uM7JgAEm08GBuasSltQjvPuMX1fR5TqxopJpqZJB8",
  "tid": "12345678-aaaa-bbbb-cccc-9876543210ab",
  "uti": "h7DMQwSPAEeiEe62JJUGAA",
  "ver": "2.0"
  }

{
"typ": "JWT",
"rh": "0.AhoAv4j5cvGGr0GRqy180BHbR6Rnn7s7iddIqxdA7UZsDxYaABY.",
"alg": "RS256",
"kid": "q-23falevZhhD3hm9CQbkP5MQyU"
}.{
  "aud": "api://00000002-0000-0000-c000-000000000000",
  "iss": "https://sts.windows.net/{tenantid}/",
  "iat": 1537231048,
  "nbf": 1537231048,
  "exp": 1537234948,
  "acr": "1",
  "aio": "AXQAi/8IAAAA",
  "amr": ["pwd"],
  "appid": "c44b4083-3bb0-49c1-b47d-974e53cbdf3c",
  "appidacr": "0",
  "ipaddr": "192.168.1.1",
  "name": "John Doe",
  "oid": "00000000-0000-0000-0000-000000000000",
  "scp": "access_as_user",
  "sub": "AAAAAAAAAAAAAAAAAAAAAIkzqFVrSaSaFHy782bbtaQ",
  "tid": "12345678-aaaa-bbbb-cccc-9876543210ab",
  "uti": "fqiBqXLPj0eQa82S-IYFAA",
  }

Utilize o token: extraia as informações do utilizador do token, como o nome, o e-mail e o ID do objeto, e utilize o token para chamar a própria API da extensão de mensagem. Para obter mais informações sobre a referência de afirmações com detalhes sobre as afirmações incluídas nos tokens de acesso, veja Afirmações de tokens de acesso.

Atualizar manifesto do aplicativo

Atualize as seguintes propriedades no ficheiro de manifesto da aplicação:

webApplicationInfo: a webApplicationInfo propriedade é utilizada para ativar o SSO para a sua aplicação para ajudar os utilizadores da aplicação a acederem facilmente à sua aplicação de extensão de mensagens baseada em API. O URI do ID da aplicação que registou no Microsoft Entra ID está configurado com o âmbito da API que expôs. Para obter mais informações, consulte webApplicationInfo.
microsoftEntraConfiguration: ativa a autenticação SSO para a sua aplicação. Configure a supportsSingleSignOn propriedade para true para suportar o SSO e reduzir a necessidade de várias autenticações. Se a propriedade estiver definida como false ou ficar vazia, o utilizador não poderá carregar a aplicação para o Teams e a aplicação falhará a validação.

Para configurar o manifesto da aplicação:

Abra a aplicação de extensão de mensagens baseada em API.
Abra a pasta de manifesto da aplicação.
Observação
- A pasta de manifesto da aplicação deve estar na raiz da pasta da aplicação. Para obter mais informações, consulte Criar um pacote de aplicações do Microsoft Teams.
- Para obter mais informações sobre como criar um manifest.json, veja o esquema de manifesto da aplicação.
Abra o arquivo manifest.json.
Adicione o fragmento de código seguinte à webApplicationInfo secção do ficheiro de manifesto da aplicação:
```
"webApplicationInfo":
{
"id": "{Microsoft Entra AppId}",
"resource": "api://subdomain.example.com/{Microsoft Entra AppId}"
}
```
Em que:
- {Microsoft Entra AppId}é o ID da aplicação que criou quando registou a sua aplicação no Microsoft Entra ID. É o GUID.
- api://subdomain.example.com/{Microsoft Entra AppId}é o URI do ID da aplicação que registou ao criar o âmbito no Microsoft Entra ID.

Adicione o fragmento de código seguinte à composeExtensions secção do ficheiro de manifesto da aplicação:

"authorization": {
  "authType": "microsoftEntra",
  “microsoftEntraConfiguration”: {
    “supportsSingleSignOn”: true
  }
},

Guarde o ficheiro de manifesto da aplicação.

Parabéns! Ativou o SSO para as extensões de mensagens baseadas em API.

Compartilhar via

Ativar o SSO para extensões de mensagens baseadas em API

Pré-requisitos

Registar uma nova aplicação no Microsoft Entra ID

Configurar o escopo para o token de acesso

URI da ID do Aplicativo

Configurar o âmbito da API

Configurar a aplicação cliente autorizada

Autenticar token

Atualizar manifesto do aplicativo

Confira também

Recursos adicionais