Use esse componente para obter um token de acesso do OAuth2 do tipo de concessão Credenciais do Cliente. Ou seja, você o utiliza para obter um token de acesso com base nas credenciais do cliente, e não no nome do usuário e na senha. Você pode usar esse componente para obter um token que permita o acesso aos recursos do cliente protegidos pelo Oracle Identity Cloud Service ou Oracle Access Manager (OAM).

Se for necessário acessar recursos em nome de um usuário, consulte System.OAuth2AccountLink e System.OAuthAccountLink.

Para poder usar esse componente em uma habilidade, execute as seguintes tarefas:

1. Caso ele ainda não esteja registrado, registre o cliente no provedor de identidades, conforme descrito em Registro do Provedor de Identidades.
2. Adicione um serviço de autenticação de credenciais do cliente para o provedor de identidades, conforme descrito em Serviços de Autenticação.

Esse componente não tem qualquer ação. Para tratar os problemas do sistema que possam ocorrer, adicione uma próxima transição que vá para um estado que possa tratar esses erros.

Este é um exemplo de estado que utiliza esse componente:

  getAccessToken:
    component: "System.OAuth2Client"
    properties:
      authenticationService: "myAuthenticationService"
      accessTokenVariableName: "myAuthServiceToken"
    transitions:
      next: "next"
      error: "error" # handle auth service issues

Use esse componente para obter um token de acesso do usuário OAuth2 (tipo de concessão Código de Autorização) para recursos protegidos pelo OCI IAM, Oracle Access Manager (OAM), plataforma de identidade da Microsoft ou autorização do Google OAuth 2.0. Esse componente conclui todas as etapas do fluxo de 3 fases do OAuth2 e retorna o token de acesso do OAuth2.

Você pode usar a definição requiresAuthorization para indicar quais estados exigem autorização para que eles possam ser chamados. Para os estados que exigem autorização, se o usuário não estiver autorizado ainda, o estado System.OAuth2AccountLink será chamado e, em seguida, o fluxo chamará o estado que exigiu a autorização. Você pode aprender a usar esse recurso em Autorização do Usuário em Chats de Grupo (ele funciona para todos os tipos de chats, não apenas para chats de grupo).

Se você precisar obter um token de acesso do tipo de concessão Credenciais do Cliente para acessar recursos do cliente, consulte System.OAuth2Client.

Para poder usar esse componente em uma habilidade, execute as seguintes tarefas:

1. Caso ele ainda não esteja registrado, registre o cliente no provedor de identidades, conforme descrito em Registro do Provedor de Identidades.
2. Adicione um serviço de autenticação para o provedor de identidades, conforme descrito em Serviços de Autenticação.

Alguns provedores de identidade emitem tokens de atualização. Quando você usa esse componente, o Digital Assistant armazena o token de atualização durante o período de retenção especificado para o serviço de autenticação. O backend do Digital Assistant pode usar o token de atualização, se disponível, para obter um novo token de acesso sem que o usuário tenha de acessar novamente.

Dica:

Em habilidades com a versão 21.04 e posterior da plataforma, os valores padrão das propriedades cancelLabel, linkLabel e prompt são armazenados no pacote de recursos da habilidade. Para alterar um padrão, abra a página Pacote de Recursos da habilidade, clique em , selecione a guia Configuração e altere a mensagem da chave OAuth2AccountLink - <nome da propriedade>. Se você usar o pacote de recursos da habilidade para alterar o padrão, não será necessário incluir a propriedade no componente, a menos que queira substituir o padrão.

Você também pode alterar as mensagens Outro - oauthCancelPrompt e Outro - oauthSuccessPrompt no pacote de configuração.

${(system.message.channelConversation.channelType=='twilio')?then('true','false')}

${(system.message.channelConversation.channelType=='twilio')?then('false','true')}

Esse componente pode retornar as seguintes ações:

Quando o mecanismo de caixa de diálogo encontra o componente, o bot de habilidades solicita ao usuário dois links: Obter um Token de Acesso e Cancelar (você pode usar linkLabel e cancelLabel para alterar o texto do link).

Se o usuário clicar no link para obter um token de acesso, ele exibirá a página de log-in do provedor de identidades ou a caixa de diálogo de autenticação, conforme especificado pelo serviço de autenticação. Após o log-in bem-sucedido, ele obtém o token de acesso, define os valores das variáveis identificadas por accessTokenVariableName e authenticatedUserVariableName e, em seguida, vai para o estado denominado pela ação pass (ou para o próximo estado, se não houver uma ação pass). Se o usuário cancelar, a ação de postback será definida como fail. Se o usuário digitar texto, ele retornará a ação textReceived.

Como mencionado anteriormente, você pode definir requiresAuthorization para um estado para garantir que o usuário esteja autorizado antes de chamar o componente do estado. Se o usuário ainda não tiver autorização, a caixa de diálogo chamará a ação system.authorizeUser em defaultTransitions. Veja aqui um exemplo:

main: true
name: RequiresAuthorizationExample
context:
  variables:
    iResult: "nlpresult"

defaultTransitions:
  actions:
    system.authorizeUser: "login"

states:
  intent:
    component: "System.Intent"
    properties:
      variable: "iResult"
    transitions:
      actions:
        reg.general.showPasscode: "showPasscode"
        reg.general.showPhoneNumber: "showPhoneNumber"
        unresolvedIntent: "handleUnresolved"        

  showPasscode:
    component: "System.Output"
    requiresAuthorization: true
    properties:
      text: "XYZABC123"
    transitions:
      return: "done"          
       
  showPhoneNumber:
    component: "System.Output"
    requiresAuthorization: false
    properties:
      text: "555-1212"
    transitions:
      return: "done"
       
  handleUnresolved:
    component: "System.Output"
    requiresAuthorization: false
    properties:
      text: "You can ask for my phone number or ask for the passcode."
    transitions:
      return: "done"
         
  login:
    component: "System.OAuth2AccountLink"
    properties:
      prompt: "${profile.firstName}, please login"
      authenticationService: "MyAuthenticationService"
      accessTokenVariableName: "user.accessToken"
      authenticatedUserVariableName: "user.authenticatedUserId"
    transitions:
      actions:
        pass : "${system.requestedState}"
        fail : "handleFailedLogin"
        textReceived: "intent"       

  handleFailedLogin:
    component: "System.Output"
    requiresAuthorization: false
    properties:
      text: "Sorry, you aren't authorized to do that"
    transitions:
      return: "done"     

Use esse componente para revogar todos os tokens de atualização e de acesso do usuário conectado do provedor de identidades que o serviço de autenticação representa. Ele também remove os tokens de atualização do banco de dados. Para usar esse componente, informe o URL do token de atualização de revogação do provedor de identidades na IU do Serviço de Autenticação.

A habilidade deve incluir um estado que use o componente OAuth2AccountLink para o mesmo serviço de autenticação e deve ser chamada antes do estado que usa o componente System.OAuth2ResetTokens.

Este componente pode retornar a seguinte ação:

Use esse componente para obter o código de autorização para serviços protegidos pelo fluxo de concessão do código de autorização, como LinkedIn, Twitter, Google ou Microsoft. Os componentes personalizados da habilidade podem trocar o código de autorização por um token de acesso, que depois eles usam para chamar o serviço final.

O componente primeiro direciona o usuário para a página de log-in do provedor de identidades. Após um log-in bem-sucedido, o componente retorna o código de autorização em uma variável, que você usa para transmitir o código de autorização ao componente personalizado. A API do componente personalizado deve trocar o código de autorização, o ID do cliente e o segredo do cliente por um token de acesso do usuário do OAuth2.

Você pode usar a definição requiresAuthorization para indicar quais estados exigem autorização para que eles possam ser chamados. Para os estados que exigem autorização, se o usuário ainda não tiver autorização, o estado System.OAuthAccountLink será chamado e, em seguida, o fluxo chamará o estado que exigiu a autorização. Você pode aprender a usar esse recurso em Autorização do Usuário em Chats de Grupo (ele funciona para todos os tipos de chats, não apenas para chats de grupo).

Dica:

Em habilidades com a versão 21.04 e posterior da plataforma, os valores padrão das propriedades cancelLabel, linkLabel e prompt são armazenados no pacote de recursos da habilidade. Para alterar um padrão, abra a página Pacote de Recursos da habilidade, clique em , selecione a guia Configuração e altere a mensagem da chave OAuthAccountLink - <nome da propriedade>. Se você usar o pacote de recursos da habilidade para alterar o padrão, não será necessário incluir a propriedade no componente, a menos que queira substituir o padrão.

Você também pode alterar as mensagens Outro - oauthCancelPrompt e Outro - oauthSuccessPrompt no pacote de configuração.

${(system.message.channelConversation.channelType=='twilio')?then('true','false')}

${(system.message.channelConversation.channelType=='twilio')?then('false','true')}

Esse componente pode retornar as seguintes ações:

Este exemplo mostra as propriedades obrigatórias que você precisa definir para o componente System.OAuthAccountLink: prompt, que especifica a mensagem de log-in, variable, que informa ao componente onde armazenar o código de autorização e authorizeURL que define o URL do OAuth do provedor e o URL de redirecionamento que recebe o código de autorização.

login:
  component: "System.OAuthAccountLink"
  properties:
    prompt: "Please login now."
    linkLabel: "login"
    cancelLabel: "cancel"
    authorizeURL: "https://www.linkedin.com/oauth/v2/authorization?response_type=code&client_id=75k0vq4&scope=r_basicprofile&redirect_uri=https%3A%2F%2FmyBotsinstance%2Fconnectors%2Fv2%2Fcallback"
    variable: "authCode"
  transitions:
      next: getBankUserProfile
      actions:
        textReceived: handleAuthTextResponse
        fail: authCancelled

Quando o mecanismo de caixa de diálogo encontra esse componente, o bot de habilidades solicita ao usuário com dois links — Log-in e Cancelar.

Descrição da ilustração fb-oauth.png

Há várias formas de fazer a transição desse componente:

• O usuário clica no botão Cancelar e o componente muda para o estado denominado pela ação fail.

• O usuário não clica em qualquer botão, mas digita texto. O componente muda para o estado nomeado pela ação textReceived.

• O usuário clica no link de log-in e o canal renderiza a página de log-in do provedor de identidades ou sua caixa de diálogo de autenticação como webview, conforme mostrado no exemplo a seguir. Após a autorização bem-sucedida, o componente muda para o estado nomeado pela ação pass (ou para o próximo estado se não houver uma ação pass), que normalmente chamaria um componente personalizado que troca o código de autorização por um token de acesso.

Descrição da ilustração webview-login.png

Se a janela de teste não renderizar a webview, recorte e cole o texto do link no browser.