このコンポーネントを使用して、権限付与タイプがクライアント資格証明のOAuth2アクセス・トークンを取得します。つまり、これを使用して、ユーザーの名前やパスワードではなく、クライアントの資格証明に基づいたアクセス・トークンを取得します。このコンポーネントを使用して、Oracle Identity Cloud ServiceまたはOracle Access Manager (OAM)によって保護されているクライアント・リソースへのアクセスを可能にするトークンを取得できます。

ユーザーのかわりにリソースにアクセスする必要がある場合は、System.OAuth2AccountLinkおよびSystem.OAuthAccountLinkを参照してください。

このコンポーネントをスキルで使用する前に、次のタスクを実行する必要があります:

1. まだ登録されていない場合は、アイデンティティ・プロバイダ登録の説明に従って、クライアントをアイデンティティ・プロバイダに登録します。
2. 認証サービスの説明に従って、アイデンティティ・プロバイダのクライアント資格証明認証サービスを追加します。

このコンポーネントにはアクションはありません。発生する可能性のあるシステムの問題に対処するには、そのようなエラーを処理できる状態に移行する次の遷移を追加します。

次に、このコンポーネントを使用する状態の例を示します:

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

このコンポーネントを使用して、OCI IAM、Oracle Access Manager (OAM)、Microsoft IDプラットフォームまたはGoogle OAuth 2.0認可によって保護されているリソース用のOAuth2ユーザー・アクセス・トークン(権限付与タイプが認可コード)を取得します。このコンポーネントは、3-legged OAuth2フローのすべてのステップを完了し、OAuth2アクセス・トークンを返します。

requiresAuthorization設定を使用すると、起動する前に認可が必要なのはどの状態かを指定することができます。認可が必要な状態では、ユーザーがまだ認可されていない場合、System.OAuth2AccountLink状態が起動され、その後、認可が必要な状態がフローによって起動されます。この機能の使用方法は、グループ・チャットでのユーザー認証を参照してください(これは、グループ・チャットだけでなく、すべてのタイプのチャットで機能します)。

クライアント・リソースにアクセスするために権限付与タイプがクライアント資格証明のアクセス・トークンを取得する必要がある場合は、System.OAuth2Clientを参照してください。

このコンポーネントをスキルで使用する前に、次のタスクを実行する必要があります:

1. まだ登録されていない場合は、アイデンティティ・プロバイダ登録の説明に従って、クライアントをアイデンティティ・プロバイダに登録します。
2. 認証サービスの説明に従って、アイデンティティ・プロバイダの認証サービスを追加します。

一部のアイデンティティ・プロバイダは、リフレッシュ・トークンを発行します。このコンポーネントを使用すると、デジタル・アシスタントにより、認証サービスに対して指定されている保持期間の間、リフレッシュ・トークンが格納されます。デジタル・アシスタント・バックエンドはリフレッシュ・トークンを使用して(使用可能な場合)、ユーザーが再度サインインしなくても新しいアクセス・トークンを取得できます。

ヒント:

プラットフォーム・バージョンが21.04以降のスキルでは、cancelLabel、linkLabelおよびpromptプロパティのデフォルト値はスキルのリソース・バンドルに格納されます。デフォルトを変更するには、スキルの「リソース・バンドル」ページを開き、をクリックして「構成」タブを選択し、OAuth2AccountLink - <property name>キーのメッセージを変更します。スキルのリソース・バンドルを使用してデフォルトを変更する場合は、コンポーネントにプロパティを含める必要はありません(デフォルトをオーバーライドする場合を除きます)。

構成バンドルの「その他 - oauthCancelPrompt」および「その他 - oauthSuccessPrompt」のメッセージも変更できます。

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

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

このコンポーネントは、次のアクションを返すことができます:

ダイアログ・エンジンがコンポーネントを検出すると、スキル・ボットによって「アクセス・トークンの取得」と「取消」という2つのリンクがユーザーに表示されます(linkLabelとcancelLabelを使用してリンク・テキストを変更できます)。

アクセス・トークンを取得するリンクをユーザーがクリックした場合は、認証サービスで指定されたアイデンティティ・プロバイダのログイン・ページまたは認証ダイアログを表示します。ログインが成功すると、アクセス・トークンを取得し、accessTokenVariableNameおよびauthenticatedUserVariableNameで指定された変数の値を設定し、passアクションによって指定された状態(またはpassアクションがない場合は次の状態)に移行します。ユーザーが取り消した場合、ポストバック・アクションはfailに設定されます。ユーザーがテキストを入力した場合、textReceivedアクションを返します。

前述のように、状態にrequiresAuthorizationを設定すると、ユーザーが認可されてから状態のコンポーネントを起動するようになります。ユーザーがまだ認可されていない場合、ダイアログがdefaultTransitionsのsystem.authorizeUserアクションを起動します。次の例は、次のとおりです:

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"     

このコンポーネントを使用して、認証サービスが示すアイデンティティ・プロバイダから、ログイン・ユーザーのすべてのリフレッシュ・トークンおよびユーザー・アクセス・トークンを取り消します。また、リフレッシュ・トークンをデータベースから削除します。このコンポーネントを使用するには、認証サービスUIでアイデンティティ・プロバイダのリフレッシュ・トークンの取消URLを指定する必要があります。

スキルには、同じ認証サービスのOAuth2AccountLinkコンポーネントを使用する状態が含まれている必要があり、System.OAuth2ResetTokensコンポーネントを使用する状態の前に呼び出される必要があります。

このコンポーネントは、次のアクションを返すことができます:

このコンポーネントを使用して、LinkedIn、Twitter、Google、Microsoftなど、認可コード権限付与フローによって保護されているサービスの認可コードを取得します。スキルのカスタム・コンポーネントは、認可コードをアクセス・トークンと交換でき、これを使用して終了サービスを起動します。

最初に、コンポーネントによってアイデンティティ・プロバイダのログイン・ページがユーザーに表示されます。ログインの成功後、コンポーネントによって認可コードが変数で返され、それを使用して認可コードをカスタム・コンポーネントに渡します。カスタム・コンポーネントAPIによって、認可コード、クライアントIDおよびクライアント・シークレットがOAuth2ユーザー・アクセス・トークンと交換される必要があります。

requiresAuthorization設定を使用すると、起動する前に認可が必要なのはどの状態かを指定することができます。認可が必要な状態では、ユーザーがまだ認可されていない場合、System.OAuthAccountLink状態が起動され、その後、認可が必要な状態がフローによって起動されます。この機能の使用方法は、グループ・チャットでのユーザー認証を参照してください(これは、グループ・チャットだけでなく、すべてのタイプのチャットで機能します)。

ヒント:

プラットフォーム・バージョンが21.04以降のスキルでは、cancelLabel、linkLabelおよびpromptプロパティのデフォルト値はスキルのリソース・バンドルに格納されます。デフォルトを変更するには、スキルの「リソース・バンドル」ページを開き、をクリックして「構成」タブを選択し、OAuthAccountLink - <property name>キーのメッセージを変更します。スキルのリソース・バンドルを使用してデフォルトを変更する場合は、コンポーネントにプロパティを含める必要はありません(デフォルトをオーバーライドする場合を除きます)。

構成バンドルの「その他 - oauthCancelPrompt」および「その他 - oauthSuccessPrompt」のメッセージも変更できます。

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

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

このコンポーネントは、次のアクションを返すことができます:

この例は、System.OAuthAccountLinkコンポーネントに対して定義する必要のある必須プロパティを示しています: promptはログイン・メッセージを指定し、variableは認可コードの格納場所をコンポーネントに指示し、authorizeURLはプロバイダのOAuth URLと認可コードを受け取るリダイレクトURLの両方を定義します。

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

ダイアログ・エンジンがこのコンポーネントを検出すると、スキル・ボットが2つのリンク(LoginとCancel)を使用してユーザーに入力を求めます。

図fb-oauth.pngの説明

このコンポーネントから遷移する方法はいくつかあります:

• ユーザーが取消しボタンをクリックすると、コンポーネントはfailアクションによって指定された状態に遷移します。

• ユーザーはボタンをクリックしませんが、かわりにテキストを入力します。コンポーネントはtextReceivedアクションによって指定された状態に遷移します。

• ユーザーがログイン・リンクをクリックすると、次の例に示すように、チャネルによってアイデンティティ・プロバイダのログイン・ページまたは認証ダイアログがWebビューとしてレンダリングされます。認可が成功すると、コンポーネントはpassアクションによって指定された状態(または、passアクションがない場合は次の状態)に遷移します。これは通常、認可コードをアクセス・トークンと交換するカスタム・コンポーネントをコールします。

図webview-login.pngの説明

テスト・ウィンドウでWebビューがレンダリングされない場合は、リンク・テキストを切り取ってブラウザに貼り付けてください。