Utilizzare questo componente per ottenere un token di accesso OAuth2 del tipo di privilegio Credenziali client. Cioè, lo usi per ottenere un token di accesso basato sulle credenziali del client, e non sul nome e sulla password dell'utente. È possibile utilizzare questo componente per ottenere un token che abilita l'accesso alle risorse client protette da Oracle Identity Cloud Service o Oracle Access Manager (OAM).

Se è necessario accedere alle risorse per conto di un utente, vedere System.OAuth2AccountLink e System.OAuthAccountLink.

Per poter utilizzare questo componente in uno skill, è necessario eseguire i task riportati di seguito.

1. Se non è già registrato, registrare il client con il provider di identità come descritto nella sezione Registrazione provider di identità.
2. Aggiungere un servizio di autenticazione client-credenziali per il provider di identità, come descritto in Authentication Services.

Questo componente non ha azioni. Per gestire i problemi di sistema che potrebbero verificarsi, aggiungere una transizione successiva che passa a uno stato in grado di gestire tali errori.

Di seguito è riportato un esempio di stato che utilizza questo componente.

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

Utilizzare questo componente per ottenere un token di accesso utente OAuth2 (codice autorizzazione tipo di concessione) per le risorse protette da OCI IAM, Oracle Access Manager (OAM), dalla piattaforma di identità Microsoft o dall'autorizzazione Google OAuth 2.0. Questo componente completa tutti i passi per il flusso OAuth2 a 3 fasi e restituisce il token di accesso OAuth2.

È possibile utilizzare l'impostazione requiresAuthorization per indicare gli stati che richiedono l'autorizzazione prima di poter essere richiamati. Per gli stati che richiedono l'autorizzazione, se l'utente non ha ancora effettuato l'autorizzazione, viene richiamato lo stato System.OAuth2AccountLink, quindi il flusso richiama lo stato che richiede l'autorizzazione. È possibile imparare a utilizzare questa funzione in Autorizzazione utente nelle chat di gruppo (funziona per tutti i tipi di chat, non solo per le chat di gruppo).

Se è necessario ottenere un token di accesso di tipo Credenziali client di tipo grant per accedere alle risorse client, vedere System.OAuth2Client.

Per poter utilizzare questo componente in uno skill, è necessario eseguire i task riportati di seguito.

1. Se non è già stata registrata, registrare il client con il provider di identità come descritto nella sezione Registrazione provider di identità.
2. Aggiungere un servizio di autenticazione per il provider di identità, come descritto in Servizi di autenticazione.

Alcuni provider di identità emettono token di aggiornamento. Quando si utilizza questo componente, Digital Assistant memorizza il token di aggiornamento per il periodo di conservazione specificato per il servizio di autenticazione. Il backend di Digital Assistant può utilizzare il token di aggiornamento, se disponibile, per ottenere un nuovo token di accesso senza che l'utente debba eseguire di nuovo l'accesso.

Suggerimento

Negli skill con versione piattaforma 21.04 e successive, i valori predefiniti per le proprietà cancelLabel, linkLabel e prompt vengono memorizzati nel bundle di risorse dello skill. Per modificare un'impostazione predefinita, aprire la pagina Bundle delle risorse della competenza, fare clic su , selezionare la scheda Configurazione e modificare il messaggio per la chiave OAuth2AccountLink - <property name>. Se si utilizza il bundle di risorse dello skill per modificare l'impostazione predefinita, non è necessario includere la proprietà nel componente a meno che non si desideri sostituire l'impostazione predefinita.

È inoltre possibile modificare i messaggi Altro - oauthCancelPrompt e Altro - oauthSuccessPrompt nel bundle di configurazione.

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

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

Questo componente può restituire le seguenti azioni:

Quando il motore della finestra di dialogo incontra il componente, il bot skill richiede all'utente due collegamenti: Ottieni un token di accesso e Annulla (è possibile utilizzare linkLabel e cancelLabel per modificare il testo del collegamento).

Se l'utente fa clic sul collegamento per ottenere un token di accesso, visualizza la pagina di login o la finestra di dialogo di autenticazione del provider di identità, come specificato dal servizio di autenticazione. Dopo aver eseguito correttamente il login, ottiene il token di accesso, imposta i valori per le variabili identificate da accessTokenVariableName e authenticatedUserVariableName, quindi passa allo stato denominato dall'azione pass o allo stato successivo se non esiste un'azione pass. Se l'utente annulla l'operazione di postback viene impostata su fail. Se l'utente immette testo, restituisce l'azione textReceived.

Come accennato in precedenza, è possibile impostare requiresAuthorization per uno stato per assicurarsi che l'utente sia autorizzato prima di richiamare il componente dello stato. Se l'utente non ha ancora ricevuto l'autorizzazione, la finestra di dialogo richiama l'azione system.authorizeUser in defaultTransitions. Esempio:

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"     

Utilizzare questo componente per revocare tutti i token di aggiornamento e accesso utente dell'utente collegato dal provider di identità rappresentato dal servizio di autenticazione. Rimuove inoltre i token di aggiornamento dal database. Per utilizzare questo componente, è necessario fornire l'URL del token di aggiornamento di revoca del provider di identità nell'interfaccia utente del servizio di autenticazione.

La competenza deve includere uno stato che utilizza il componente OAuth2AccountLink per lo stesso servizio di autenticazione e deve essere richiamata prima dello stato che utilizza il componente System.OAuth2ResetTokens.

Questo componente può restituire l'azione seguente:

Utilizzare questo componente per ottenere il codice di autorizzazione per i servizi protetti dal flusso di concessione del codice di autorizzazione, ad esempio LinkedIn, Twitter, Google o Microsoft. I componenti personalizzati dello skill possono scambiare il codice di autorizzazione per un token di accesso, che vengono quindi utilizzati per richiamare il servizio finale.

Il componente indirizza innanzitutto l'utente alla pagina di login del provider di identità. Dopo un login riuscito, il componente restituisce il codice di autorizzazione in una variabile, utilizzato per passare il codice di autorizzazione al componente personalizzato. L'API del componente personalizzato deve scambiare il codice di autorizzazione, l'ID client e il segreto client per un token di accesso utente OAuth2.

È possibile utilizzare l'impostazione requiresAuthorization per indicare gli stati che richiedono l'autorizzazione prima di poter essere richiamati. Per gli stati che richiedono l'autorizzazione, se l'utente non ha ancora effettuato l'autorizzazione, viene richiamato lo stato System.OAuthAccountLink, quindi il flusso richiama lo stato che richiede l'autorizzazione. È possibile imparare a utilizzare questa funzione in Autorizzazione utente nelle chat di gruppo (funziona per tutti i tipi di chat, non solo per le chat di gruppo).

Suggerimento

Negli skill con versione piattaforma 21.04 e successive, i valori predefiniti per le proprietà cancelLabel, linkLabel e prompt vengono memorizzati nel bundle di risorse dello skill. Per modificare un'impostazione predefinita, aprire la pagina Bundle delle risorse della competenza, fare clic su , selezionare la scheda Configurazione e modificare il messaggio per la chiave OAuthAccountLink - <property name>. Se si utilizza il bundle di risorse dello skill per modificare l'impostazione predefinita, non è necessario includere la proprietà nel componente a meno che non si desideri sostituire l'impostazione predefinita.

È inoltre possibile modificare i messaggi Altro - oauthCancelPrompt e Altro - oauthSuccessPrompt nel bundle di configurazione.

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

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

Questo componente può restituire le seguenti azioni:

Questo esempio mostra le proprietà necessarie da definire per il componente System.OAuthAccountLink: prompt, che specifica il messaggio di login, variable, che indica al componente dove memorizzare il codice di autorizzazione, e authorizeURL che definisce sia l'URL OAuth del provider che l'URL di reindirizzamento che riceve il codice di autorizzazione.

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 il motore della finestra di dialogo rileva questo componente, il bot delle competenze richiede all'utente due collegamenti: Login e Annulla.

Descrizione dell'immagine fb-oauth.png

Esistono diversi modi per eseguire la transizione da questo componente:

• L'utente fa clic sul pulsante Annulla e il componente passa allo stato indicato dall'azione fail.

• L'utente non fa clic su alcun pulsante, ma immette testo. Il componente passa allo stato denominato dall'azione textReceived.

• L'utente fa clic sul collegamento di login e il canale visualizza la pagina di login del provider di identità o la relativa finestra di dialogo di autenticazione come vista Web, come mostrato nell'esempio riportato di seguito. Dopo l'autorizzazione riuscita, il componente passa allo stato denominato dall'azione pass (o allo stato successivo se non è presente un'azione pass), che in genere richiama un componente personalizzato che scambia il codice di autorizzazione per un token di accesso.

Descrizione dell'immagine webview-login.png

Se la finestra di test non visualizza la vista Web, tagliare e incollare il testo del collegamento nel browser.