Compartilhar via

Adicionar código para ativar o SSO para Ações Universais de Cartões Ajustáveis

  • Artigo

Os passos de autenticação para o início de sessão único (SSO) são semelhantes aos de um bot no Teams. Seguem-se os passos para alcançar o SSO na Ação Universal de Cartões Ajustáveis.

Observação

Para implementar o fluxo de SSO, tem de ter uma conversa individual declarada para o bot no manifesto da aplicação. Quando um utilizador da aplicação invoca o fluxo de SSO através do protocolo Cartão Action.Execute Ajustável, é apresentado um pedido para permitir que o utilizador da aplicação instale a aplicação num âmbito pessoal, caso não a tenha instalado.

Adicionar código para processar um token de acesso

Certifique-se de que configurou o bot no Microsoft Entra ID para obter o token de acesso. Pode atualizar o código para processar o token de acesso das Ações Universais de Cartões Ajustáveis no bot.

Se existir um token em cache, o bot utiliza o mesmo token. Se não existir nenhum token disponível, o Cartão Ajustável envia uma resposta de invocação para o serviço de bot, que envia um card OAuth com os seguintes valores que incluem um tokenExchangeResource para designar uma operação de SSO:

{
"statusCode": 401,
"type": "application/vnd.microsoft.activity.loginRequest",
"value": {
   "text": "Please sign-in",
   "connectionName": "<configured-connection-name>",
   "tokenExchangeResource": {
      "id": "<unique-indentifier>",
      "uri": "<application-or-resource-identifier>",
      "providerId": "<optional-provider-identifier>"
   },
   "buttons": [
      {
      "title": "Sign-In",
         "text": "Sign-In",
         "type": "signin",
         "value": "<sign-in-URL>"
      }
   ]
}
}

O serviço de bot fornece a resposta de invocação ao cliente do Teams, que utiliza o tokenExchangeResource valor e o token de cliente do Teams para obter um token em nome ou token permutável de Microsoft Entra ID.

O SSO falha quando o cliente do Teams ignora o tokenExchangeResource valor por qualquer motivo, incluindo valores inválidos, erros ao obter tokens permutáveis ou se Microsoft Entra ID não suportar o valor. Em seguida, o cliente do Teams aciona o início de sessão nominal ou o fluxo OAuth. Recomendamos que forneça um URL de início de sessão na resposta para que o fluxo OAuth funcione.

Se o utilizador da aplicação estiver a utilizar um Cartão Ajustável pela primeira vez, terá de dar consentimento para que a aplicação utilize a respetiva identidade. É apresentada a seguinte caixa de diálogo:

Captura de ecrã a mostrar a caixa de diálogo de consentimento.

Quando o utilizador da aplicação seleciona Ver e aceita, a vista de consentimento de permissão de Microsoft Entra existente é apresentada para mostrar todas as permissões. O utilizador da aplicação pode continuar com o fluxo de autenticação.

Adicionar código para receber o token

  1. O cliente do Teams envia o original adaptiveCard/action novamente para o bot juntamente com o token da seguinte forma:

    {
"type": "invoke",
"name": "adaptiveCard/action"
"value": {
"action": {
   "id": "abc123",
   "type": "Action.Execute",
   "verb": "saveCommand",
   "data": {
      "firstName": "Jeff",
      "lastName": "Derstadt"
   }
},
"authentication": {
   "id": "8769-xyz",
   "connectionName": "oauthConnection",
   "token": "...single sign-on token..."
}
}
}

    O fragmento de código seguinte mostra como receber a atividade de invocação no serviço de bot:

            protected override async Task<InvokeResponse> OnInvokeActivityAsync(ITurnContext<IInvokeActivity> turnContext, 
     CancellationToken cancellationToken)
        {
          JObject value = JsonConvert.DeserializeObject<JObject>
          (turnContext.Activity.Value.ToString());
          JObject authentication = null;
          if (value["authentication"] != null)
          {
          authentication = JsonConvert.DeserializeObject<JObject>(value["authentication"].ToString());
          }
        }

  2. O cliente do Teams envia um pedido de invocação para o bot. O bot recebe o consentimento dos utilizadores da aplicação e utiliza a respetiva identidade para ajudar o processo de troca de tokens com o serviço de tokens do bot framework e Microsoft Entra ID. O serviço de tokens do bot framework fornece aos utilizadores da aplicação o token de acesso ao bot.

    • O serviço de bot ignora o token de acesso se o valor estiver incorreto.

    • O serviço de bot que apresenta um erro ao realizar a troca de tokens tem de responder com um erro ou um segundo pedido de início de sessão que não inclua informações de SSO. Se o serviço de bot responder com um erro, o erro tem de ser:

       {
  "statusCode" = 412,
  "type" = "application/vnd.microsoft.error.preconditionFailed",
  "value" = {
    "code" = "412",
    "message" = "authentication token expired"    }
    }

    • Quando o SSO falha, o cliente do Teams mostra um botão de início de sessão no rodapé card para iniciar o fluxo de início de sessão nominal.

  3. O bot utiliza o token de acesso em nome do utilizador da aplicação para realizar as ações.

  4. O bot devolve uma resposta sem erros ao cliente do Teams através de uma card ou mensagem.

Observação

Para processar o token de acesso caso o utilizador da aplicação termine sessão, veja Processar o início de sessão do utilizador da aplicação.

Exemplo de código

Nome de exemplo Descrição .NET Node.js Manifesto
SSO para as Suas Ações Universais de Cartões Ajustáveis Este código de exemplo demonstra como ativar a autenticação SSO para as Suas Ações Universais de Cartões Ajustáveis no bot. View View Exibir

Confira também