Para que você possa usar um componente OAuth2Client, OAuth2AccountLink ou OAuthAccountLink em uma habilidade, um administrador deve registrar um aplicativo confidencial (também conhecido como cliente OAuth) no OCI IAM ou no OAM.

Para saber como registrar um aplicativo no OCI IAM, consulte Adicionando um Aplicativo Confidencial na documentação do Oracle Cloud Infrastructure. Informações sobre como registrar um aplicativo no OAM podem ser encontradas em Configurando Serviços OAuth em Administrando o Oracle Access Management.

Ao registrar um aplicativo (cliente) no OCI IAM ou OAM, você precisará fornecer estas informações:

• Tipos de Concessão Permitidos: O aplicativo deve usar o tipo de concessão Código de Autorização ou Credenciais do Cliente.

• Escopos ou Atribuições: Inclua os recursos que seus componentes personalizados precisam acessar. Se você incluir o tipo de concessão de token de atualização, adicione também o escopo correspondente, que é offline_access para OCI IAM.

• URL de Redirecionamento ou Callback: Forneça o URL que o IDP utiliza para enviar de volta o código de autorização. Alguns provedores de identidade se referem a isso como URL de redirecionamento ou URI de callback. Para descobrir o que usar para o URL de redirecionamento, vá para a página Canais e abra qualquer canal do Facebook ou Webhook (se você não tiver um, crie um fictício). Use o domínio e a porta do URL do Webhook do canal (por exemplo, https://<domain>:<port>/connectors/v2/tenants/<tenantId>/listeners/facebook/channels/<channelId>) para criar o URL de redirecionamento, que deve estar no formato https://<domain>:<port>/connectors/v2/callback. Por exemplo, https://example.com:443/connectors/v2/callback.

  Se sua instância estiver provisionada no Oracle Cloud Platform (como todas as instâncias da versão 19.4.1), use v1 em vez de v2.

Se você estiver usando OAuth2Client ou OAuth2AccountLink para autenticação no IDP, depois de criar o aplicativo (cliente OAuth), anote as credenciais do cliente, o token do IDP e o URL de autorização. Você precisará dessas informações quando criar um serviço de autenticação conforme descrito em Serviços de Autenticação.

Para registrar um aplicativo na plataforma de identidade da Microsoft, siga as instruções da Microsoft no Início Rápido: Registrar um aplicativo na plataforma de identidade da Microsoft.

Defina o tipo de aplicativo como Web.

Será necessário fornecer o URL que a plataforma usa para enviar de volta o código de autorização. Para descobrir o que usar para o URL, vá para a página Canais do Digital Assistant e abra qualquer canal do Facebook ou Webhook (se você não tiver um, crie um fictício). Use o domínio e a porta do URL do Webhook do canal (por exemplo, https://<domain>:<port>/connectors/v2/tenants/<tenantId>/listeners/facebook/channels/<channelId>) para criar o URL de redirecionamento, que deve estar no formato https://<domain>:<port>/connectors/v2/callback. Por exemplo, https://example.com:443/connectors/v2/callback.

Depois de registrar o aplicativo, crie um segredo de cliente conforme descrito no tópico da Microsoft Criar um novo segredo de aplicativo. Você usará esse segredo quando criar um serviço de autenticação para o aplicativo.

Para registrar um aplicativo no Google OAuth2, você cria um projeto e ativa as APIs necessárias, conforme mostrado no tópico do Google Ativar APIs para seu projeto. Se você planeja usar os componentes do calendário, certifique-se de ativar as APIs do Google Calendar e do CalDAV.

Em seguida, obtenha o ID do cliente e o segredo do aplicativo conforme descrito no tópico do Google Criar credenciais de autorização.

Na tela de consentimento do OAuth, especifique os escopos que seu aplicativo precisará de permissão para acessar. Consulte o tópico do Google Identificar escopos de acesso para obter mais informações.

Veja como criar um serviço de autenticação para o tipo de concessão Código de Autorização para o OCI IAM, o OAM, a Plataforma de Identidade da Microsoft e a Plataforma de Identidade do Google. Esse tipo de concessão autentica o nome do usuário e a senha.

1. Abra o menu lateral e clique em Definições > Serviços de Autenticação.
2. Clique em + Serviço.
3. Selecione o tipo de concessão Código de Autorização.
4. Digite estes valores:

   • Provedor de Identidade: Que tipo de provedor de identidade (IDP) você está usando.

   • Nome: Um nome para identificar o serviço de autenticação.

   • URL do Ponto Final do Token: O URL do IDP para solicitar tokens de acesso.

     • OCI IAM: Use https://<IAM-Service-Instance>.identity.oraclecloud.com/oauth2/v1/token.

     • OAM: Use http://<Managed-Server-Host>:<Managed-Server-Port>/oauth2/rest/token.

     • Plataforma de Identidade da Microsoft: Use https://login.microsoftonline.com/<Azure-Active-Directory-TenantID>/oauth2/v2.0/token.

     • Plataforma de Identidade do Google: Use https://www.googleapis.com/oauth2/v4/token.

   • Ponto Final de Autorização: O URL do IDP da página na qual os usuários fazem a autenticação informando seus nomes de usuário e senhas.

     • OCI IAM: Use https://<IAM-Service-Instance>.identity.oraclecloud.com/oauth2/v1/authorize.

     • OAM: Use http://<host>:<port>/oauth2/rest/authz.

     • Plataforma de Identidade da Microsoft: Use https://login.microsoftonline.com/<Azure-Active-Directory-TenantID>/oauth2/v2.0/authorize.

     • Plataforma de Identidade do Google: Use https://accounts.google.com/o/oauth2/v2/auth.

   • URL Abreviado de Solicitação de Código de Autorização: (Opcional) Uma versão abreviada do URL de autorização, que você pode obter em um serviço de redução de URL (um que permite enviar parâmetros de consulta). Talvez você precise disso, porque o URL de solicitação de código de autorização gerado poderá ser muito grande para SMS e smartphones mais antigos.

     Por padrão, os URLs de solicitação de código de autorização para cada plataforma são:

     • OCI IAM e OAM:

       {Authorization Endpoint URL}?client_id={clientId}&response_type=code&scope={scope}&redirect_uri={redirectUri}&state={state}

     • Plataforma de Identidade da Microsoft:

       {Authorization Endpoint URL}?client_id={clientId}&response_type=code&scope={scope}&redirect_uri={redirectUri}&response_mode=query&state={state}

     • Plataforma de Identidade do Google:

       {Authorization Endpoint URL}?client_id={clientId}&response_type=code&scope={scope}&redirect_uri={redirectUri}&access_type=offline&prompt=consent&state={state}

     Veja um exemplo do URL exibido em uma mensagem de texto:

     
     Descrição da ilustração long-url.png

     Por exemplo, você pode obter uma versão abreviada deste URL:

     {Authorization Endpoint
           URL}?client_id={clientId}&response_type=code&scope={scope}&redirect_uri={redirectUri}&state={state}

     Usando o URL Abreviado de Solicitação de Código de Autorização, o Oracle Digital Assistant cria o URL de solicitação de código de autorização como este:

     {Short Authorization Code Request URL}?state={state}

   • Revogar URL do Ponto Final do Token: (Opcional) Se você quiser revogar todos os tokens de atualização e de acesso do usuário conectado de um fluxo de caixas de diálogo, será necessário o URL do token de revogação de atualização do IDP. Se você fornecer esse URL, poderá usar o componente Redefinir Tokens OAuth 2.0 para revogar os tokens do usuário para esse serviço.

     • OCI IAM: Use https://<IAM-Service-Instance>.identity.oraclecloud.com/oauth2/v1/revoke.

     • OAM: Use https://<host>:<port>/ms_oauth/oauth2/endpoints/<OAuth-Service-Name>/tokens.

     • Plataforma de Identidade da Microsoft: Não suportado.

     • Plataforma de Identidade do Google: Use https://oauth2.googleapis.com/revoke.

   • ID do Cliente e Segredo do Cliente: O ID e o segredo do cliente para o aplicativo IDP (Cliente OAuth) que foi registrado conforme descrito em Registro do Provedor de Identidade. Com a plataforma de identidade da Microsoft, use o ID e o segredo do aplicativo.

   • Escopos: Uma lista separada por espaços dos escopos que devem ser incluídos quando o Digital Assistant solicitar um token de acesso do provedor. Inclua todos os escopos necessários para acessar os recursos. Se os tokens de atualização estiverem ativados, inclua o escopo necessário para obter o token de atualização (normalmente, offline_access).

     • OCI IAM: Use o escopo urn:opc:idm:__myscopes__ quando precisar obter um token de acesso que contenha todos os escopes permitidos. Use o escopo urn:opc:idm:role.<roll-name> (por exemplo, urn:opc:idm:role.User%20Administrator) quando precisar obter um token de acesso que contenha os escopos aplicáveis de uma determinada atribuição.

     • Plataforma de Identidade da Microsoft: Inclua openid email profile offline_access. Se você planeja usar componentes de calendário, inclua https://graph.microsoft.com/Calendars.ReadWrite. Para outras permissões, use o formato https://graph.microsoft.com/<permission>. Substitua <permission> por um nome de permissão válido da referência de permissões do Microsoft Graph.

     • Plataforma de Identidade do Google: Você deve incluir https://www.googleapis.com/auth/userinfo.email, que é usado para obter o ID de log-in do usuário. Se você planeja usar componentes de calendário, inclua https://www.googleapis.com/auth/calendar. Para outros escopos, consulte Escopos do OAuth 2.0 para APIs do Google.

   • Reivindicação do Sujeito: A reivindicação do perfil de token de acesso a ser usada para identificar o usuário.

     • OCI IAM e OAM: Geralmente é a reivindicação sub (assunto). No entanto, se a reivindicação sub contiver um ID de usuário interno, isso não será útil para o Digital Assistant. Nesses casos, especifique uma reivindicação de perfil que possa ajudar o Digital Assistant a identificar o usuário, como email ou name.

     • Plataforma de Identidade da Microsoft: Use preferred_username.

     • Plataforma de Identidade do Google: Use email.

   • Período de Retenção do Token de Atualização: O número de dias para manter o token de atualização no cache do Digital Assistant. Se você deixar em branco, o padrão será 7.

   
   Descrição da ilustração auth-service-ac.png
5. Clique em Criar.

Veja como criar um serviço de autenticação para o tipo de concessão Credenciais. Esse tipo de concessão autentica o ID e o segredo do cliente.

1. Abra o menu lateral e clique em Definições > Serviços de Autenticação.
2. Clique em + Serviço.
3. Selecione o tipo de concessão Credenciais do Cliente.
4. Digite estes valores:

   • Provedor de Identidade: Que tipo de provedor de identidade (IDP) você está usando.

   • Nome: Um nome para identificar o serviço de autenticação.

   • URL do Ponto Final do Token: O URL do IDP para solicitar tokens de acesso.

   • ID do Cliente e Segredo do Cliente: O ID e o segredo do cliente para o aplicativo IDP (Cliente OAuth) que foi registrado conforme descrito em Registro do Provedor de Identidade.

   • Escopos: Os escopos que devem ser incluídos quando o Digital Assistant solicita um token de acesso do provedor. Inclua todos os escopos necessários para acessar os recursos.

   
   

   
   Descrição da ilustração auth-service-cc.png

   
   
5. Clique em Criar.

Você pode configurar habilidades para identidades de usuários unificados com as seguintes etapas gerais:

1. Ativar vinculação de conta de canal na instância do Digital Assistant.
2. Adicione um serviço de código de autorização na instância do Digital Assistant.
3. No fluxo de caixas de diálogo da habilidade, adicione um componente OAuth 2.0 Account Link (para o modo de caixa de diálogo Visual) ou System.OAuth2AccountLink (para o modo YAML).
4. No componente, configure o tratamento do consentimento do usuário para armazenar os dados de identidade do usuário unificado.

O ID de usuário unificado de um determinado usuário é definido na primeira vez que o usuário acessa o assistente digital e se autentica com uma Autorização usando o componente OAuth 2.0. Ou seja, a identidade autenticada inicial torna-se o "ponto da verdade". Todos os IDs de conta de canal para o mesmo usuário autenticado do OAuth 2.0 estão associados ao ID de usuário unificado.

Você pode ativar a vinculação da conta de canal para permitir que as identidades do usuário sejam reconhecidas em vários canais de uma habilidade. Por exemplo, se um usuário iniciar uma conversa em um canal e estiver aguardando uma resposta, ele também poderá receber uma notificação dessa resposta no outro canal.

Para ativar a vinculação de canal:

1. Clique em para abrir o menu lateral e selecione Definições > Serviços de Identidade Unificados.
2. Defina a chave Vinculação de Conta de Canal como Ativado.

Quando você tiver ativado o link da conta do canal, poderá configurar como tratar o consentimento do usuário para cada habilidade individualmente, usando a propriedade requiresAssociationConsent no componente Link da Conta OAuth 2.0 da habilidade. Estas são as opções:

• Yes: Apresenta o usuário com as seguintes opções de consentimento para associação dos dados da conta do canal com um ID de usuário unificado:
  • Conta Associada. Confirma que o usuário aprovou a vinculação da identidade do canal atual com o ID de usuário unificado centralizado.
  • Nunca Vincular Esta Conta. Indica que esta conta de canal específica não deve ser associada ao ID de usuário unificado. Posteriormente, o usuário não será perguntado se deseja vincular essa conta daqui para frente. (embora o usuário possa reverter essa decisão posteriormente).
  • Não Neste Momento. Não vincula as contas da sessão atual, mas não impede que o usuário seja solicitado a aprovação nas sessões subsequentes. O prompt de consentimento é temporariamente suprimido após o usuário selecionar essa opção, mas pode reaparecer quando o usuário fizer a autenticação novamente mais de 24 horas depois.
• No . A conta do canal do usuário é automaticamente vinculada ao ID de usuário unificado sem que o usuário seja solicitado a consentir.
• Notify. A conta do canal do usuário é automaticamente vinculada ao ID de usuário unificado, e o usuário é notificado desse fato.

O valor padrão da propriedade é Yes.

Há um conjunto de prompts e mensagens que são exibidos na conversa quando um usuário é notificado de que suas informações de identidade de conta de canal estão sendo vinculadas a uma identidade de usuário unificada ou se recebem opções de consentimento. Você pode ajustar a frase desses prompts em mensagens no pacote de recursos da habilidade.

Para acessar esses prompts e mensagens específicos no pacote de recursos:

1. Na habilidade, clique em para abrir o Pacote de Recursos.
2. Selecione a guia Configuração.
3. No campo Filtro, digite OAuthAccount2Link - consent para exibir as entradas do pacote relacionadas ao consentimento.

O tempo que os dados de identidade do usuário unificado são armazenados é definido no nível da instância.

Para configurar o tempo que esses dados são armazenados:

1. Clique em para abrir o menu lateral e selecione Definições > Serviços de Identidade Unificados.
2. Defina a opção Excluir dados da conta de canal do usuário após o período de retenção especificado como Ativado.

   Se não estiver ativado, os dados da conta de canal do usuário serão retidos indefinidamente.

3. Em Período de retenção para dados do usuário da conta do canal (em dias), digite o número de dias em que deseja que os dados sejam armazenados.

   O mínimo de 7 e o máximo é 1100.

   Observação
   
   Os jobs para expurgar os dados são executados apenas uma vez a cada 24 a 48 horas. Portanto, dependendo do tempo do job, os dados podem ser retidos por até 48 horas a mais do que o período de retenção designado.