Habilitar o SSO para extensões de mensagem baseadas em API

O método de autenticação de logon único (SSO) para extensão de mensagem baseada em API usa a identidade do Teams de um usuário do aplicativo para fornecer acesso ao seu aplicativo. Um usuário que entrou no Teams não precisa entrar novamente no seu aplicativo dentro do ambiente do Teams. O SSO do Microsoft Entra permite que o aplicativo obtenha silenciosamente um token de usuário emitido para seu recurso pelo Microsoft Entra. Em seguida, o aplicativo pode autenticar esse token e recuperar as informações de perfil do usuário sem o consentimento do usuário.

Pré-requisitos

Antes de começar, verifique se você tem o seguinte:

  • Uma conta do Azure com uma assinatura ativa.
  • Familiaridade básica com o Microsoft Entra ID e o desenvolvimento de aplicativos do Teams.

A imagem a seguir mostra como o SSO funciona quando um usuário do aplicativo Teams tenta acessar o aplicativo de extensão de mensagem baseado em API:

A captura de tela mostra como a autorização SSO do Microsoft Entra funciona para autenticar a extensão de mensagem baseada em API.

  • O usuário invoca o aplicativo de extensão de mensagem baseado em API no Teams e invoca um comando que requer autenticação.
  • O aplicativo envia uma solicitação ao serviço de back-end do Teams com a ID do aplicativo e o escopo necessário (access_as_user).
  • O serviço de back-end do Teams verifica se o usuário consentiu com o aplicativo e com o escopo. Caso contrário, ele mostra uma tela de consentimento para o usuário.
  • Se o usuário consentir, o Microsoft Entra gerará um token de acesso para o usuário e o aplicativo e o enviará ao aplicativo no cabeçalho de autorização da solicitação.
  • O aplicativo valida o token e extrai as informações do usuário do token, como nome, email e ID do objeto.
  • Após a autenticação bem-sucedida, o usuário recebe acesso à extensão de mensagem baseada em API.

Para habilitar a autenticação SSO para extensão de mensagem baseada em API, siga estas etapas:

Registrar um novo aplicativo no Microsoft Entra ID

  1. No navegador da Web, vá para o Portal do Azure.

  2. Selecione o ícone Registros de aplicativo.

    A captura de tela mostra a página do centro de administração do Microsoft Entra.

    A página Registros de aplicativo é exibida.

  3. Selecione o ícone + Novo registro.

    A captura de tela mostra a nova página de registro no centro de administração do Microsoft Entra.

    A página Registrar um aplicativo é exibida.

  4. Insira o nome do aplicativo que você deseja exibir para o usuário do aplicativo. Você pode alterar o nome posteriormente, se desejar.

    A captura de tela mostra a página de registro do aplicativo no centro de administração do Microsoft Entra.

  5. Selecione o tipo de conta de usuário que pode acessar seu aplicativo. Você pode selecionar entre opções de locatário único ou multilocatário em diretórios organizacionais ou restringir o acesso apenas a contas pessoais da Microsoft.

    Opções para tipos de conta com suporte
    Opção Selecione essa opção para...
    Contas somente neste diretório organizacional (somente Microsoft - locatário único) Crie um aplicativo para uso somente por usuários (ou convidados) em seu locatário.
    Muitas vezes chamado de aplicativo personalizado criado para sua organização (aplicativo LOB), esse aplicativo é um aplicativo de locatário único na plataforma de identidade da Microsoft.
    Contas em qualquer diretório organizacional (qualquer locatário do Microsoft Entra ID - multilocatário) Permita que os usuários em qualquer locatário do Microsoft Entra usem seu aplicativo. Essa opção é apropriada se, por exemplo, você estiver criando um aplicativo SaaS e pretende disponibilizá-lo para várias organizações.
    Esse tipo de aplicativo é conhecido como um aplicativo multilocatário na plataforma de identidade da Microsoft.
    Contas em qualquer diretório organizacional (qualquer locatário do Microsoft Entra ID - multilocatário) e contas pessoais da Microsoft (por exemplo, Skype, Xbox) Destina-se ao conjunto mais amplo de clientes.
    Ao selecionar essa opção, você está registrando um aplicativo multilocatário que pode dar suporte a usuários de aplicativos que também têm contas pessoais da Microsoft.
    Contas pessoais da Microsoft Crie um aplicativo somente para usuários que têm contas pessoais da Microsoft.

    Observação

    Você não precisa inserir o URI de redirecionamento para habilitar o SSO para um aplicativo de extensão de mensagem baseado em API.

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

    A captura de tela mostra um exemplo da notificação após o registro do aplicativo ser bem-sucedido no portal do Azure.

    A página com a ID do aplicativo e outros detalhes do aplicativo é exibida.

    A captura de tela mostra a página de detalhes do aplicativo no portal do Azure.

  7. Anote e salve a ID do aplicativo da ID do aplicativo (cliente) para atualizar o manifesto do aplicativo mais tarde.

    Seu aplicativo está registrado no Microsoft Entra ID. Agora você tem a ID do aplicativo para seu aplicativo de extensão de mensagem baseado em API.

Configurar a versão do token de acesso

Você deve garantir a versão do token de acesso para seu aplicativo. Você pode encontrar essa configuração no manifesto do aplicativo do aplicativo do Microsoft Entra.

Para configurar a versão do token de acesso

  1. Selecione Gerenciar>Manifesto no painel esquerdo.

    O manifesto do aplicativo do aplicativo Microsoft Entra é exibido.

  2. Defina a requestedAccessTokenVersion propriedade como 2.

    A imagem mostra como configurar a versão do token de acesso.

    Observação

    Se você selecionou Somente contas pessoais da Microsoft ou Contas em qualquer diretório organizacional (qualquer diretório do Microsoft Entra – multilocatário) e contas pessoais da Microsoft (por exemplo, Skype e Xbox) durante o registro do aplicativo, atualize o valor da requestedAccessTokenVersion propriedade como 2.

  3. Selecione Salvar.

    Uma mensagem aparece no navegador informando que o manifesto do aplicativo foi atualizado com êxito.

Depois de verificar e configurar a versão do token de acesso, você deve configurar seu escopo.

Configurar o escopo para o token de acesso

Depois de configurar a versão do token de acesso, configure as opções de escopo (permissão) para enviar o token de acesso ao cliente do Teams e autorizar aplicativos cliente confiáveis a habilitar o SSO.

Para configurar o escopo e autorizar aplicativos cliente confiáveis, você deve:

  • Adicionar URI da ID do aplicativo: configure as opções de escopo (permissão) para seu aplicativo. Exponha uma API Web e configure o URI da ID do aplicativo.
  • Configurar o escopo da API: defina o escopo da API e os usuários que podem consentir com um escopo. Você pode permitir que somente administradores forneçam consentimento para permissões com privilégios mais altos.
  • Configurar aplicativo cliente autorizado: crie IDs de cliente autorizadas para aplicativos que você deseja 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é-autorize apenas os aplicativos cliente em que você confia, pois os usuários do aplicativo não têm a oportunidade de recusar o consentimento.

URI da ID do Aplicativo

  1. Selecione Gerenciar>Expor uma API no painel esquerdo.

    A página Expor uma API é exibida.

  2. Selecione Adicionar para gerar o URI da ID do aplicativo na forma de api://{AppID}.

    A captura de tela mostra como definir o URI da ID do aplicativo.

    A seção para definir o URI da ID do aplicativo é exibida.

  3. Insira o URI da ID do aplicativo no formato explicado aqui.

    A captura de tela mostra o URI da ID do Aplicativo no Microsoft Entra ID.

    • O URI da ID do aplicativo é pré-preenchido com a ID do aplicativo (GUID) no formato api://{AppID}.
    • O formato do URI da ID do aplicativo deve 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 você estiver criando um bot autônomo, insira o URI da ID do aplicativo como api://botid-{YourBotId}. Aqui, {YourBotId} é a ID do seu aplicativo Microsoft Entra.
    • Se você estiver criando um aplicativo com um bot, uma extensão de mensagem e uma guia, insira o URI da ID do aplicativo como api://fully-qualified-domain-name.com/botid-{YourClientId}, em que {YourClientId} é a ID do aplicativo bot.
    • Se você estiver criando um aplicativo com uma extensão de mensagem ou recursos de guia sem o bot, insira o URI da ID do aplicativo como api://fully-qualified-domain-name.com/{YourClientId}, em que {YourClientId} é a ID do aplicativo Microsoft Entra.
    • URI da ID do aplicativo para aplicativo com vários recursos: se você estiver criando uma extensão de mensagem baseada em API, insira o URI da ID do aplicativo como api://fully-qualified-domain-name.com/{YourClientId}, em que {YourClientId} é sua ID do aplicativo Microsoft Entra.
    • Formato para nome de domínio: Use apenas letras minúsculas para nome de domínio.

  4. Selecione Salvar.

    Uma mensagem aparece no navegador informando que o URI da ID do aplicativo foi atualizado.

    A captura de tela mostra a mensagem URI da ID do aplicativo.

    O URI da ID do aplicativo é exibido na página.

    A captura de tela mostra o URI da ID do aplicativo atualizado.

  5. Observe e salve o URI da ID do aplicativo para atualizar o manifesto do aplicativo mais tarde.

Tive um problema

Configurar escopo da API

Observação

  • A extensão de mensagem baseada em API dá suporte apenas ao escopo access_as_user .
  • A API recebe um token de acesso do Microsoft Entra com o escopo definido access_as_user como registrado no portal do Azure. No entanto, o token não está autorizado a chamar nenhuma outra API downstream, como o Microsoft Graph.

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

    A captura de tela mostra a opção selecionar escopo.

    A página Adicionar um escopo é exibida.

  2. Insira os detalhes para configurar o escopo.

    A captura de tela mostra como adicionar detalhes de escopo no Azure.

    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.

    A captura de tela mostra a mensagem de escopo adicionado.

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

    A captura de tela mostra um exemplo do escopo adicionado ao aplicativo no portal do Azure.

Tive um problema

Configurar aplicativo cliente autorizado

  1. Mova-se pela página Expor uma API para a seção Aplicativo cliente autorizado e selecione + Adicionar um aplicativo cliente.

    A captura de tela mostra o aplicativo cliente autorizado.

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

  2. Insira a ID de cliente do Microsoft 365 apropriada para os aplicativos que você deseja autorizar para o aplicativo Web do seu aplicativo.

    A captura de tela mostra a opção ID do Cliente e Escopos Autorizados para adicionar um aplicativo cliente ao aplicativo no portal do Azure. Adicionar um aplicativo cliente

    Observação

    As IDs de cliente do Microsoft 365 para aplicativos móveis, de área de trabalho e Web para o Teams são as IDs reais que você deve adicionar.

    1. Selecione uma das seguintes IDs de cliente:

      Usar a ID do cliente Para autorizar...
      1fec8e78-bce4-4aaf-ab1b-5451cc387264 Aplicativo móvel ou da área de trabalho do Teams
      5e3ce6c0-2b1f-4285-8d4b-75ee78787346 Aplicativo web do Teams

    2. Selecione o URI da ID do aplicativo que você criou para seu aplicativo em Escopos autorizados para adicionar o escopo à API Web exposta.

    3. Selecione Adicionar aplicativo.

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

      A captura de tela mostra a mensagem adicionada ao aplicativo cliente.

      A ID do cliente do aplicativo autorizado é exibida na página.

      A captura de tela mostra o aplicativo cliente adicionado.

Observação

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

Você configurou com êxito o escopo, as permissões e os aplicativos cliente do aplicativo. Certifique-se de anotar e salvar o URI da ID do aplicativo. Em seguida, você atualiza o manifesto do aplicativo.

Tive um problema

Autenticar token

Quando a extensão de mensagem chama a API durante a autenticação, ela recebe uma solicitação com o token de acesso do usuário. Em seguida, a extensão de mensagem adiciona o token no cabeçalho de autorização da solicitação HTTP de saída. O formato do cabeçalho é Authorization: Bearer <token_value>. Por exemplo, quando uma extensão de mensagem faz uma chamada de API para um serviço que requer autenticação. A extensão constrói uma solicitação HTTP da seguinte maneira:

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

Depois que a extensão de mensagem baseada em API obtiver um cabeçalho de solicitação com token, execute as seguintes etapas:

  • Autenticar: verifique o token para as declarações de público-alvo, escopo, emissor e assinatura para marcar se o token é para seu aplicativo. Para obter mais declarações, consulte Declarações de token de ID.

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

    {
"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"
  }

  • Use o token: extraia as informações do usuário do token, como nome, email e ID do objeto, e use o token para chamar a própria API do aplicativo de extensão de mensagem. Para obter mais informações sobre a referência de declarações com detalhes sobre as declarações incluídas nos tokens de acesso, consulte as declarações de token de acesso. Em seguida, configure o escopo do token de acesso.

Atualizar manifesto do aplicativo

Atualize as seguintes propriedades no arquivo de manifesto do aplicativo:

  • webApplicationInfo: A webApplicationInfo propriedade é usada para habilitar o SSO para seu aplicativo para ajudar os usuários a acessar seu aplicativo de extensão de mensagem baseado em API sem problemas. O URI da ID do aplicativo que você registrou no Microsoft Entra ID é configurado com o escopo da API exposta. Para obter mais informações, consulte webApplicationInfo.

       A captura de tela mostra a configuração do manifesto do aplicativo.

  • microsoftEntraConfiguration: habilita a autenticação SSO para seu aplicativo. Configure a supportsSingleSignOn propriedade para true dar suporte ao SSO e reduzir a necessidade de várias autenticações. Se a propriedade estiver definida false como ou for deixada vazia, o usuário não poderá carregar o aplicativo no Teams e o aplicativo falhará na validação.

Para configurar o manifesto do aplicativo:

  1. Abra o aplicativo de extensão de mensagem baseado em API.

  2. Abra a pasta do manifesto do aplicativo.

    Observação

  3. Abra o arquivo manifest.json.

  4. Adicione o seguinte trecho de código à seção do arquivo de manifesto webApplicationInfo do aplicativo:

    "webApplicationInfo":
{
"id": "{Microsoft Entra AppId}",
"resource": "api://subdomain.example.com/{Microsoft Entra AppId}"
}

    Em que:

    • {Microsoft Entra AppId}é a ID do aplicativo que você criou quando registrou seu aplicativo no Microsoft Entra ID. É o GUID.
    • api://subdomain.example.com/{Microsoft Entra AppId}é o URI da ID do aplicativo que você registrou ao criar o escopo no Microsoft Entra ID.

  5. Adicione o seguinte trecho de código à seção do arquivo de manifesto composeExtensions do aplicativo:

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

  6. Salve o arquivo de manifesto do aplicativo.

Parabéns! Você habilitou o SSO para suas extensões de mensagens baseadas em API.

Tive um problema

Confira também

  • Last updated on