Adicionar início de sessão único

  • 6 minutos

Nesta unidade, irá aprender a adicionar o início de sessão único a uma extensão de mensagem com o Microsoft Entra.

Configurar a aplicação Teams com início de sessão único

A aplicação Microsoft Teams suporta o início de sessão único (SSO) com o Microsoft Entra. O SSO permite que os utilizadores iniciem sessão uma vez e acedam a várias aplicações sem terem de iniciar sessão novamente.

Para configurar o SSO, configure o registo da aplicação Microsoft Entra do recurso do Bot do Azure para fazer pedidos em nome do utilizador.

Captura de ecrã da página Expor API no registo da aplicação Microsoft Entra.

No registo da aplicação Microsoft Entra, configure as seguintes definições:

  • URI do ID da Aplicação, um identificador exclusivo para o registo de aplicações que é utilizado para identificar o recurso que o cliente deve utilizar ao iniciar um fluxo de início de sessão único na aplicação.
  • Âmbitos, a permissão concedida ao bot para aceder aos dados do utilizador.
  • Aplicações cliente autorizadas, as aplicações cliente que têm permissão para pedir tokens ao registo de aplicações.

No manifesto da aplicação, o objeto webApplicationInfo é configurado com o ID do bot e o URI do ID da Aplicação. Determinam o recurso que o cliente deve utilizar ao iniciar um fluxo de início de sessão único na aplicação.

O fragmento de código seguinte mostra como o objeto webApplicationInfo está configurado no ficheiro de manifesto da aplicação:

"webApplicationInfo": {
    "id": "dbeb8ea7-8ac3-4bb2-bcba-b210b087a73a",
    "resource": "api://grttxrk0-5130.uks1.devtunnels.ms/botid-dbeb8ea7-8ac3-4bb2-bcba-b210b087a73a"
}

Configurar a ligação OAuth

O recurso Azure Bot fornece acesso ao Bot Framework Token Service. O serviço de tokens é utilizado para obter um token de acesso para o utilizador através das definições de ligação OAuth que configurar. Os tokens são armazenados de forma segura no serviço e são obtidos quando necessário no código do bot.

Captura de ecrã a mostrar uma definição de ligação OAuth no portal do Azure.

Para criar uma definição de ligação, configure as seguintes definições:

  • Nome – o nome da definição de ligação.
  • Fornecedor de serviços – o fornecedor de identidade que a ligação utiliza para autenticar os utilizadores. As definições de ligação suportam vários fornecedores de identidade, incluindo o Microsoft Entra.
  • ID de Cliente – o ID de cliente de um registo da aplicação Microsoft Entra configurado com as permissões necessárias para aceder aos dados do utilizador.
  • Segredo do cliente – o segredo do cliente de um registo da aplicação Microsoft Entra configurado com as permissões necessárias para aceder aos dados do utilizador.
  • URL do Exchange de Tokens – o URL que o cliente deve utilizar ao iniciar um fluxo de início de sessão único na aplicação.
  • ID do inquilino – o ID do inquilino onde está localizado o registo da aplicação Microsoft Entra.
  • Âmbitos – a permissão concedida ao bot para aceder aos dados do utilizador.

O fragmento de código seguinte mostra como configurar uma definição de ligação OAuth num ficheiro Bicep:

resource botServiceProductsAPIConnection 'Microsoft.BotService/botServices/connections@2022-09-15' = {
    parent: botService
    name: 'Products API'
    location: 'global'
    properties: {
        serviceProviderDisplayName: 'Azure Active Directory v2'
        serviceProviderId: '30dd229c-58e3-4a48-bdfd-91ec48eb906c'
        clientId: productsApiEntraAppClientId
        clientSecret: productsApiEntraAppClientSecret
        scopes: 'api://${backendApiEntraAppClientId}/Product.Read'
        parameters: [
            {
                key: 'tenantID'
                value: 'common'
            }
            {
                key: 'tokenExchangeUrl'
                value: 'api://${botAppDomain}/botid-${botEntraAppClientId}'
            }
        ]
    }
}

Dica

Recomenda-se a criação de novos registos de aplicações do Microsoft Entra para a autenticação de serviço do utilizador. O registo de aplicações utilizado com o serviço Azure Bot deve permanecer separado e utilizado para autenticação de serviço a serviço entre o serviço Web e o serviço de bot.

O registo da aplicação Microsoft Entra utilizado com a definição de ligação tem de ser configurado para utilizar o URI https://token.botframework.com/.auth/web/redirect de redirecionamento para obter com êxito um token de acesso do Bot Framework Token Service. O URI de redirecionamento é utilizado para devolver o token de acesso ao serviço de tokens após a autenticação do utilizador.

Uma vez que o URI de redirecionamento do serviço de tokens está alojado num domínio externo, tem de ser incluído no ficheiro de manifesto da aplicação. A matriz validDomains indica ao cliente quais os domínios a utilizar pela aplicação. Garante que o cliente pode confiar no domínio ao iniciar um único fluxo de início de sessão.

O fragmento de código seguinte mostra como adicionar o domínio ao ficheiro de manifesto da aplicação:

"validDomains": [
    "token.botframework.com"
]

Autenticar consultas de utilizador

Para autenticar consultas de utilizador numa extensão de mensagem, utilize o SDK do Bot Framework para obter um token de acesso para o utilizador a partir do Bot Framework Token Service. Em seguida, o token de acesso pode ser utilizado para aceder a dados de um serviço externo.

Primeiro, verifique se existe um token para o utilizador no serviço de tokens.

O fragmento de código seguinte mostra como obter o UserTokenClient e utilizar o método GetUserTokenAsync para devolver um token de acesso para o utilizador através de uma definição de ligação OAuth denominada:

var userTokenClient = turnContext.TurnState.Get<UserTokenClient>();

var tokenResponse = await userTokenClient.GetUserTokenAsync(userId, connectionName, channelId, magicCode, cancellationToken);

Se não for devolvido um token, terá de pedir ao utilizador para iniciar sessão. Crie uma resposta que compõe uma ligação na interface de utilizador, que o utilizador pode seguir para iniciar o fluxo de início de sessão.

O fragmento de código seguinte mostra como o método GetSignInResourceAsync é utilizado para devolver uma ligação de início de sessão do serviço de tokens e incluí-la na resposta da extensão de mensagem:

var resource = await userTokenClient.GetSignInResourceAsync(connectionName, activity, null, cancellationToken);

return new MessagingExtensionResponse
{
    ComposeExtension = new MessagingExtensionResult
    {
        Type = "auth",
        SuggestedActions = new MessagingExtensionSuggestedAction
        {
            Actions = [
                new() {
                    Type = ActionTypes.OpenUrl,
                    Value = resource.SignInLink,
                    Title = "Sign In",
                },
            ],
        },
    },
};

Quando o utilizador segue a ligação de início de sessão, concorda com as permissões pedidas no campo Âmbitos na definição de ligação OAuth. Depois de o utilizador consentir as permissões, o serviço de tokens obtém um token de acesso e armazena-o de forma segura no serviço.

Da próxima vez que o utilizador iniciar uma pesquisa na extensão da mensagem, será encontrado um token de acesso no serviço de tokens. O token de acesso devolvido pode ser utilizado para aceder a dados de um serviço externo.