機械翻訳について

セキュリティ

これらは、YAMLベースのダイアログ・フロー・エディタの「セキュリティ」カテゴリで使用可能なコンポーネントです。

System.OAuth2Client

ノート:

このトピックでは、このコンポーネントをYAMLモードで使用する方法について説明します。 ビジュアル・フロー・デザイナでの使用方法の詳細は、「OAuth 2.0クライアント」を参照してください。

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

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

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

  1. クライアントがまだ登録されていない場合は、「アイデンティティ・プロバイダ登録」で説明されているように、アイデンティティ・プロバイダに登録します。
  2. 「認証サービス」の説明に従って、アイデンティティ・プロバイダにクライアント資格証明認証サービスを追加します。
プロパティ 説明 必須かどうか
authenticationService OAuth2アイデンティティ・プロバイダの「認証サービス」 UIで作成したクライアント資格証明サービスの名前。 はい
accessTokenVariableName アクセス・トークンを格納する変数を指定します。 contextノードで変数、文字列またはサポートされている別の変数タイプとして宣言できます。 ユーザー・スコープの変数にすることもできます。 たとえば: user.accessToken。 はい

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

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

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

System.OAuth2AccountLink

ノート:

このトピックでは、このコンポーネントをYAMLモードで使用する方法について説明します。 ビジュアル・フロー・デザイナでの使用方法の詳細は、「OAuth 2.0アカウント・リンク」を参照してください。

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

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

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

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

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

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

ヒント:

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

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

プロパティ 説明 必須かどうか
accessTokenVariableName アクセス・トークンを格納する変数を指定します。 変数がuser.accessTokenなどのユーザー・スコープの場合は、スキル間で共有できます。

デフォルトはaccessTokenです。

いいえ
authenticatedUserVariableName 認証されたユーザー名(アイデンティティ・プロバイダが認識する名前)を格納する変数を指定します。 変数がuser.authenticatedUserなどのユーザー・スコープの場合は、スキル間で共有できます。

デフォルトはauthenticatedUserです。

いいえ
authenticationService OAuth2アイデンティティ・プロバイダの「認証サービス」 UIで作成した認証コード・サービスの名前。 はい
autoNumberPostbackActions trueに設定すると、このオプションによって、サーバー側のポストバック・アクションである取消オプションに数値のプレフィクスが追加されます。 アクセス・トークンを取得するためのオプションの番号(つまり、先頭にシーケンス番号を付けることができないクライアント側のURLアクション)であるため、アクセス・トークンを取得するためのプレフィクスに数字が付加されません。

このオプションをtrueに設定していない場合でも、デジタル・アシスタントの「ポストバック処理で自動採番の有効化」構成がtrueに設定されている場合、自動採番はポストバック・アクションで強制されます。 チャネル固有の自動採番は、デジタル・アシスタントに登録されているスキルのボットに適用できます: 

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

「YAMLダイアログ・フローでのテキストのみのチャネルの自動採番」を参照してください

Digital Assistantsの自動採番

いいえ
cancelLabel ユーザーが認証ダイアログを起動せずに状態を残すためにクリックできるボタンのラベルをオーバーライドする場合に使用します。 デフォルトのラベルはCancelです。 いいえ
enableSingleSignOn (MS Teamsのみ) Microsoft Teamsシングル・サインオン(SSO)を設定した場合は、MS Teamsにすでにサインインしているユーザーがスキルにサインインする必要がないように、これをtrueに設定できます。 デフォルトはfalseです。 「Microsoft TeamsチャネルのSSO構成」を参照してください。

SSOはカレンダ・コンポーネントでの使用がサポートされていません。

 いいえ
footerText ログイン・オプションおよび取消オプションの下にテキストを追加して、ログイン・ダイアログを強化します。 「フッター」で説明しているように、FreeMarker式を使用して、テキストのみのチャネルのフッター・テキストを条件付けできます。 いいえ
linkLabel ユーザーがクリックして認証ダイアログを起動できるボタンのラベルをオーバーライドする場合に使用します。 デフォルトのラベルはGet an access tokenです。 いいえ
prompt デフォルトPlease sign inではなくユーザーにプロンプトを表示するために使用する文字列。 いいえ
showCancelOption (オプション) 「取消」ボタンを表示するかどうかを指定できます。 デフォルトでは、このオプションはtrueに設定されています。つまり、「取消」ボタンが表示されます。 SMSチャネルなどで、このボタンを表示しない場合もあります。 このような動作は、次のような式を使用して構成できます: 
${(system.message.channelConversation.channelType=='twilio')?then('false','true')}
 いいえ
translate このオプションのブール・プロパティを使用して、autoTranslateコンテキスト変数のブール値をオーバーライドします。 autoTranslateは、コンテキスト変数が明示的にtrueに設定されていないかぎり、false (autotranslationから除外)になることに注意してください。 いいえ
updateUserProfile アイデンティティ・プロバイダがOCI IAMアイデンティティ・ドメインで、セッション中にIAMからユーザーのプロファイルを格納する場合は、このプロパティをtrueに設定します。 ユーザーが認証を要求されたときに、このプロパティがtrueに設定されている場合、コンポーネントはアイデンティティ・プロバイダからユーザー・プロファイル・データをフェッチし、その結果をuserProfile.<authorization service>マップに設定しようとします。 デフォルトでは、値はfalseです。 「セッション期間のユーザー・プロファイルの格納」を参照してください。 いいえ

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

アクション 説明
fail ユーザーは取消ボタンをクリックしました。
pass アクセス・トークンが正常に取得されました。
textReceived 取消ボタンまたは認証成功のかわりにユーザーが入力したテキストです。

ダイアログ・エンジンがコンポーネントに遭遇すると、スキル・ボットはユーザーに2つのリンクを要求: アクセス・トークンを取得および取消 (linkLabelおよびcancelLabelを使用してリンク・テキストを変更できます)。


oauth2accountlinksignin1.pngの説明は以下のとおりです
「図oauth2accountlinksignin1.pngの説明」

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


oauth2accountlinksignin2.pngの説明は以下のとおりです
「図oauth2accountlinksignin2.pngの説明」

前述のように、状態コンポーネントを起動する前にユーザーが認可されるように、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"

セッション期間のユーザー・プロファイルの格納

スキルでユーザーのOCI IAMアイデンティティ・ドメイン・プロファイルに基づいてダイアログ・フローを制御する必要がある場合は、System.OAuth2AccountLinkコンポーネントのupdateUserProfileプロパティをtrueに設定します。 これにより、IAMユーザーのプロファイル情報をuserProfile.<authorization service>マップから取得できます。

updateUserProfileがtrueに設定されている場合、System.OAuth2AccountLinkコンポーネントはIAMからユーザー・プロファイルをフェッチし、データをuserProfile.<authorization service>マップのオブジェクトに格納します。

たとえば、ダイアログ・フローの状態が次のようになっているとします:

  oauth2AccountLink:
    component: "System.OAuth2AccountLink"
    properties:
      authenticationService: "myIAMProvider"
      authenticatedUserVariableName: "user.authuser"
      accessTokenVariableName: "user.accessToken"
      updateUserProfile: true
    transitions:
      actions:
        pass: "askGreeting"
        fail: "fail"
        textReceived: "authTextReceived"

ユーザーがサインインすると、次の例に示すように、userProfile.myIAMProviderオブジェクトがIAMからユーザーのプロファイルでシードされます: 

"userProfile.myIAMProvider": {
  "sub": "myUsername",
  "website": "",
  "birthdate": "",
  "email_verified": false,
  "gender": "",
  "updated_at": 1584561296,
  "name": "First Last",
  "preferred_username": "myUsername",
  "given_name": "First",
  "family_name": "Last",
  "email": "first.last@oracle.com",
  "appRoles": [
    {
      "appName": "some-instance-1_APPID",
      "displayName": "RoleName",
      "appID": "1234567abcd12345",
      "name": "some-instance-1_APPID",
      "adminRole": false,
      "legacyName": "some-instance-1.RoleName",
      "id": "1234567abcdefg",
      "$ref": "http://some/path/v1/AppRoles/a111234567abcdefg"
    }
  ]
}

複数の認証サービスの処理

スキル・ボットが複数の認証サービスからアクセス・トークンが必要な場合は、次の例に示すように、このコンポーネントの使用ごとに一意のアクセス・トークンと認証ユーザー変数名を指定できます:

...
states:
# First Authentication Service
  getAccessToken1:
    component: "System.OAuth2AccountLink"
    properties:
      authenticationService: "AuthService1"
      accessTokenVariableName: "user.accessToken1"
      authenticatedUserVariableName: "user.authenticatedUser1"
    transitions:
      actions:
        pass: "getAccessToken2"
        textReceived: "handleAuthTextResponse"
        fail: "authCancelled"
# Second Authentication Service
  getAccessToken2:
    component: "System.OAuth2AccountLink"
    properties:
      authenticationService: "AuthService2"
      accessTokenVariableName: "user.accessToken2"
      authenticatedUserVariableName: "user.authenticatedUser2"
    transitions:
      actions:
        pass:  "getBankUserProfile"
        textReceived: "handleAuthTextResponse"
        fail: "authCancelled"
...

System.OAuth2ResetTokens

ノート:

このトピックでは、このコンポーネントをYAMLモードで使用する方法について説明します。 ビジュアル・フロー・デザイナでの使用方法の詳細は、「OAuth 2.0トークンのリセット」を参照してください。

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

スキルには、同じ認証サービスに対してOAuth2AccountLinkコンポーネントを使用する状態が含まれている必要があり、System.OAuth2ResetTokensコンポーネントを使用する状態よりも前に起動する必要があります。

プロパティ 説明 必須かどうか
authenticationService OAuth2 idプロバイダの認証サービスUIで作成したサービスの名前。 このサービスには、有効なリフレッシュ取消トークンURLが必要です。 はい

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

アクション 説明
noRefreshTokenFound 認証サービスには、ユーザーのリフレッシュ・トークンがありません。

System.OAuthAccountLink

ノート:

このトピックでは、このコンポーネントをYAMLモードで使用する方法について説明します。 ビジュアル・フロー・デザイナでの使用方法の詳細は、「OAuthアカウント・リンク」を参照してください。

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

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

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

ヒント:

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

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

プロパティ 説明 必須かどうか
authorizeURL ログインURL。 「authorizeURLプロパティ」は、このURLの構成方法を説明しています。 はい
autoNumberPostbackActions trueに設定すると、このオプションによって取消オプションに数値の前に付けられます。 このオプションをtrueに設定しない場合でも、デジタル・アシスタントの「ポストバック処理で自動採番の有効化」構成がtrueに設定されている場合は、リスト・アイテムで自動採番を強制できます。 チャネル固有の自動採番は、デジタル・アシスタントに登録されているスキルのボットに適用できます: 
${(system.message.channelConversation.channelType=='twilio')?then('true','false')}
 いいえ
cancelLabel ユーザーが認証ダイアログを起動せずに状態を残すためにクリックできるボタンのラベルをオーバーライドする場合に使用します。 デフォルトのラベルはCancelです。 いいえ
footerText ログイン・オプションおよび取消オプションの下にテキストを追加して、ログイン・ダイアログを強化します。 「フッター」で説明しているように、FreeMarker式を使用して、テキストのみのチャネルのフッター・テキストを条件付けできます。 いいえ
linkLabel ユーザーがクリックして認証ダイアログを起動できるボタンのラベルをオーバーライドする場合に使用します。 デフォルトのラベルはLog Inです。 いいえ
prompt ユーザーにサイン・インを求めるために使用する文字列。 はい
showCancelOption (オプション) 「取消」ボタンを表示するかどうかを指定できます。 デフォルトでは、このオプションはtrueに設定されています。つまり、「取消」ボタンが表示されます。 SMSチャネルなどで、このボタンを表示しない場合もあります。 このような動作は、次のような式を使用して構成できます: 
${(system.message.channelConversation.channelType=='twilio')?then('false','true')}
 はい
translate このオプションのブール・プロパティを使用して、autoTranslateコンテキスト変数のブール値をオーバーライドします。 autoTranslateは、コンテキスト変数が明示的にtrueに設定されていないかぎり、false (autotranslationから除外)になることに注意してください。 いいえ
variable 認可コードを格納する変数を指定します。 コンテキスト・ノードで、変数、文字列または別のサポートされている変数タイプとして宣言できます。 ユーザー変数にすることもできます。 はい

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

アクション 説明
fail ユーザーは取消ボタンをクリックしました。
pass 認可コードが正常に取得されました。
textReceived 取消ボタンまたは認証成功のかわりにユーザーが入力したテキストです。

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

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つのリンクが要求されます。 - 「ログイン」および「取消」。


fb-oauth.pngの説明は以下のとおりです
「図fb-oauth.pngの説明」

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

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

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

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


webview-login.pngの説明は以下のとおりです
「図webview-login.pngの説明」

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

authorizeURLプロパティ

このプロパティを構成するには、例のhttps://www.linkedin.com/oauth/v2/authorizationなど、アイデンティティ・プロバイダのURLで開始します。 次に、このURLに次のOAuthパラメータを追加します:

  1. response_type: このスキル・ボットに認可コードが必要なため、codeに設定します。

  2. client_id: アイデンティティ・プロバイダにアプリケーションを登録したときに取得したAPIキー値。

  3. scope: ユーザーのかわりにリソースにアクセスする権限のリスト。 これらは、アプリをプロバイダに登録するときに設定する権限です。 プロバイダによって異なる場合があり、LinkedInではr_basicprofile (例に示されています)やr_emailadressなどであり、Microsoftではopenid emailおよびopenid profileを使用して定義されます。

  4. redirect_uri: これは、アイデンティティ・プロバイダへのアプリケーションの登録に使用したリダイレクトURIで、ユーザーのリダイレクト先をプロバイダに指示します。 connectors/v2/callbackを付加したDigital Assistantサービス・ホスト名であるこのパラメータは、認可コードを受信し、それをアクティブ・チャネルに関連付けるエンドポイントです。 redirect_uriプロパティは、チャネルを作成するときに生成されるWebフックURLに基づきます。 「チャネルとは」を参照してください

    redirect_uriに入力する値が、アプリケーションを正確に登録したときに指定したリダイレクトURIに一致することを確認してください。 どちらの場合も、URIにはconnectors/v2/callbackを付加する必要があります。

ノート:

インスタンスがOracle Cloud Platformにプロビジョニングされている場合(すべてのバージョンの19.4.1インスタンスが存在する場合)は、v2のかわりにv1を使用します。