スキルでOAuth2Client、OAuth2AccountLinkまたはOAuthAccountLinkコンポーネントを使用するには、事前に管理者が機密アプリケーション(OAuthクライアントとも呼ばれる)をOCI IAMまたはOAMに登録する必要があります。

OCI IAMへのアプリケーションの登録方法を学習するには、Oracle Cloud Infrastructureドキュメントの機密アプリケーションの追加を参照してください。OAMへのアプリケーションの登録の詳細は、『Oracle Access Managementの管理』のOAuthサービスの構成を参照してください。

OCI IAMまたはOAMにアプリケーション(クライアント)を登録する際に、次の情報を指定する必要があります:

• 許可される権限付与タイプ: アプリケーションは、認可コード権限付与タイプまたはクライアント資格証明権限付与タイプのいずれかを使用する必要があります。

• スコープまたはロール: カスタム・コンポーネントがアクセスする必要があるリソースを含めます。リフレッシュ・トークン権限を付与する場合は、対応するスコープ(OCI IAMの場合はoffline_access)も追加する必要があります。

• リダイレクトまたはコールバックURL: IDPが認可コードの返信に使用するURLを指定する必要があります。一部のアイデンティティ・プロバイダでは、これはリダイレクトURLまたはコールバックURIと呼ばれます。リダイレクトURLに何を使用するかを調べるには、「チャネル」ページに移動して、FacebookまたはWebフック・チャネルを開きます(どちらもない場合は、架空のものを作成します)。チャネルのWebフックURL (たとえば、https://<domain>:<port>/connectors/v2/tenants/<tenantId>/listeners/facebook/channels/<channelId>)のドメインとポートを使用してリダイレクトURLを作成します。これは、https://<domain>:<port>/connectors/v2/callbackのフォーマットである必要があります。たとえば、https://example.com:443/connectors/v2/callbackです。

  インスタンスがOracle Cloud Platformにプロビジョニングされている場合(バージョン19.4.1のすべてのインスタンスと同様に)、v2ではなくv1を使用します。

IDPでの認証にOAuth2ClientまたはOAuth2AccountLinkを使用する場合は、アプリケーション(OAuthクライアント)の作成後、クライアント資格証明、IDPトークンおよび認可URLを書き留めます。この情報は、認証サービスの説明に従って認証サービスを作成するときに必要になります。

Microsoft IDプラットフォームにアプリケーションを登録するには、『Quickstart: Register an application with the Microsoft identity platform』のMicrosoft社の説明に従います。

アプリケーション・タイプを「Web」に設定します。

認可コードを送り返すためにプラットフォームで使用されるURLを指定する必要があります。URLに何を使用するかを調べるには、デジタル・アシスタントの「チャネル」ページに移動して、FacebookまたはWebフック・チャネルを開きます(どちらもない場合は、架空のものを作成します)。チャネルのWebフックURL (たとえば、https://<domain>:<port>/connectors/v2/tenants/<tenantId>/listeners/facebook/channels/<channelId>)のドメインとポートを使用してリダイレクトURLを作成します。これは、https://<domain>:<port>/connectors/v2/callbackのフォーマットである必要があります。たとえば、https://example.com:443/connectors/v2/callbackです。

アプリケーションを登録したら、Microsoftトピック『Create a new application secret』の説明に従ってクライアント・シークレットを作成する必要があります。このシークレットは、アプリケーションの認証サービスを作成するときに使用します。

Google OAuth2にアプリケーションを登録するには、Googleトピック『Enable APIs for your project』に示すように、プロジェクトを作成し、必要なAPIを有効にします。カレンダ・コンポーネントを使用する予定がある場合は、Google Calendar APIとCalDAV APIの両方を有効にしてください。

次に、Googleトピック『Create authorization credentials』の説明に従って、アプリケーションのクライアントIDおよびシークレットを取得します。

OAuth承認画面で、アプリケーションがアクセス権限を必要とするスコープを指定します。詳細は、Googleトピック『Identify access scopes』を参照してください。

OCI IAM、OAM、Microsoft IDプラットフォームおよびGoogle Identity Platformの「認可コード」権限付与タイプの認証サービスを作成する方法を次に示します。この権限付与タイプは、ユーザー名およびパスワードに対して認証します。

1. サイド・メニューを開き、「設定」→「認証サービス」をクリックします。
2. 「+サービス」をクリックします。
3. 「認可コード」権限付与タイプを選択します。
4. 次の値を入力します:

   • アイデンティティ・プロバイダ: 使用するアイデンティティ・プロバイダ(IDP)のタイプ。

   • 名前: 認証サービスを識別するための名前。

   • トークン・エンドポイントURL: アクセス・トークンをリクエストするためのIDPのURL。

     • OCI IAM: https://<IAM-Service-Instance>.identity.oraclecloud.com/oauth2/v1/tokenを使用します。

     • OAM: http://<Managed-Server-Host>:<Managed-Server-Port>/oauth2/rest/tokenを使用します。

     • Microsoft IDプラットフォーム: https://login.microsoftonline.com/<Azure-Active-Directory-TenantID>/oauth2/v2.0/tokenを使用します。

     • Google Identity Platform: https://www.googleapis.com/oauth2/v4/tokenを使用します。

   • 認可エンドポイント: ユーザーがユーザー名とパスワードを入力して認証するページのIDPのURL。

     • OCI IAM: https://<IAM-Service-Instance>.identity.oraclecloud.com/oauth2/v1/authorizeを使用します。

     • OAM: http://<host>:<port>/oauth2/rest/authzを使用します。

     • Microsoft IDプラットフォーム: https://login.microsoftonline.com/<Azure-Active-Directory-TenantID>/oauth2/v2.0/authorizeを使用します。

     • Google Identity Platform: https://accounts.google.com/o/oauth2/v2/authを使用します。

   • 短縮認可コード・リクエストURL: (オプション)認可URLの短縮バージョンであり、URL短縮サービス(問合せパラメータを送信できるサービス)から取得できます。これは、生成された認可コード・リクエストURLがSMSおよび古いスマートフォンには長すぎる可能性があるため、必要になることがあります。

     デフォルトでは、各プラットフォームの認可コード・リクエストURLは次のとおりです:

     • OCI IAMおよびOAM:

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

     • Microsoft IDプラットフォーム:

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

     • Google Identity Platform:

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

     テキスト・メッセージに表示されるURLの例を次に示します:

     
     図long-url.pngの説明

     たとえば、このURLの短縮バージョンを取得できます:

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

     「短縮認可コード・リクエストURL」を使用すると、Oracle Digital Assistantによって次のような認可コード・リクエストURLが作成されます:

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

   • トークン取消エンドポイントURL: (オプション)ダイアログ・フローからログイン・ユーザーのすべてのリフレッシュ・トークンおよびアクセス・トークンを取り消す場合、IDPのリフレッシュ・トークン取消URLが必要です。このURLを指定した場合は、OAuth 2.0トークンのリセット・コンポーネントを使用して、このサービスに対するユーザーのトークンを取り消すことができます。

     • OCI IAM: https://<IAM-Service-Instance>.identity.oraclecloud.com/oauth2/v1/revokeを使用します。

     • OAM: https://<host>:<port>/ms_oauth/oauth2/endpoints/<OAuth-Service-Name>/tokensを使用します。

     • Microsoft IDプラットフォーム: サポートされていません。

     • Google Identity Platform: https://oauth2.googleapis.com/revokeを使用します。

   • 「クライアントID」および「クライアント・シークレット」: アイデンティティ・プロバイダ登録での説明に従って登録された、IDPアプリケーション(OAuthクライアント)のクライアントIDおよびシークレット。Microsoft IDプラットフォームでは、アプリケーションIDおよびシークレットを使用します。

   • スコープ: デジタル・アシスタントがプロバイダからのアクセス・トークンをリクエストする際に含める必要があるスコープのスペース区切りリスト。リソースへのアクセスに必要なすべてのスコープを含めます。リフレッシュ・トークンが有効になっている場合は、リフレッシュ・トークンを取得するために必要なスコープを含めます(通常はoffline_access)。

     • OCI IAM:使用可能なスコープがすべて含まれるアクセス・トークンを取得する必要がある場合は、urn:opc:idm:__myscopes__スコープを使用します。特定のロールの適用可能なスコープが含まれるアクセス・トークンを取得する必要がある場合は、urn:opc:idm:role.<roll-name>スコープ(たとえば、urn:opc:idm:role.User%20Administrator)を使用します。

     • Microsoft IDプラットフォーム: openid email profile offline_accessを含める必要があります。カレンダ・コンポーネントを使用する予定がある場合は、https://graph.microsoft.com/Calendars.ReadWriteを含める必要があります。その他の権限の場合は、https://graph.microsoft.com/<permission>のフォーマットを使用します。<permission>を、『Microsoft Graph permissions reference』の有効な権限名に置き換えます。

     • Google Identity Platform: https://www.googleapis.com/auth/userinfo.emailを含める必要があり、これはユーザーのログインIDの取得に使用されます。カレンダ・コンポーネントを使用する予定がある場合は、 https://www.googleapis.com/auth/calendarを含める必要があります。他のスコープについては、『OAuth 2.0 Scopes for Google APIs』を参照してください。

   • サブジェクト要求: ユーザーの識別に使用するアクセス・トークン・プロファイル要求。

     • OCI IAMおよびOAM:通常、これはsub (サブジェクト)要求です。ただし、sub要求に内部ユーザーIDが含まれている場合、デジタル・アシスタントでは役に立ちません。これらの場合は、デジタル・アシスタントがユーザーを識別するために役立つプロファイル要求(emailやnameなど)を指定します。

     • Microsoft IDプラットフォーム: preferred_usernameを使用します。

     • Google Identity Platform: emailを使用します。

   • リフレッシュ・トークンの保持期間: デジタル・アシスタントのキャッシュにリフレッシュ・トークンを保持する日数。空白のままにすると、デフォルトで7に設定されます。

   
   図auth-service-ac.pngの説明
5. 「作成」をクリックします。

権限付与タイプが資格証明の認証サービスを作成する方法を次に示します。この権限付与タイプは、クライアントIDおよびクライアント・シークレットに対して認証します。

1. サイド・メニューを開き、「設定」→「認証サービス」をクリックします。
2. 「+サービス」をクリックします。
3. 「クライアント資格証明」権限付与タイプを選択します。
4. 次の値を入力します:

   • アイデンティティ・プロバイダ: 使用するアイデンティティ・プロバイダ(IDP)のタイプ。

   • 名前: 認証サービスを識別するための名前。

   • トークン・エンドポイントURL: アクセス・トークンをリクエストするためのIDPのURL。

   • 「クライアントID」および「クライアント・シークレット」: アイデンティティ・プロバイダ登録での説明に従って登録された、IDPアプリケーション(OAuthクライアント)のクライアントIDおよびシークレット。

   • スコープ: デジタル・アシスタントがプロバイダからのアクセス・トークンをリクエストする際に含める必要があるスコープ。リソースへのアクセスに必要なすべてのスコープを含めます。

   
   

   
   図auth-service-cc.pngの説明

   
   
5. 「作成」をクリックします。

次の一般的なステップを使用して、統合ユーザーIDのスキルを構成できます。

1. デジタル・アシスタント・インスタンスでチャネル・アカウント・リンクを有効化します。
2. デジタル・アシスタント・インスタンスに認可コード・サービスを追加します。
3. スキルのダイアログ・フローで、OAuth 2.0アカウント・リンク・コンポーネント(ビジュアル・ダイアログ・モードの場合)またはSystem.OAuth2AccountLink (YAMLモードの場合)を追加します。
4. コンポーネントで、統合ユーザー・アイデンティティ・データを格納するためのユーザー同意の処理を構成します。

特定のユーザーの統合ユーザーIDは、ユーザーがデジタル・アシスタントに初めてアクセスし、OAuth 2.0コンポーネントを使用して認可で認証されるときに設定されます。つまり、最初に認証されたアイデンティティが「真実の点」になります。同じOAuth 2.0認証済ユーザーのチャネル・アカウントIDはすべて、統合ユーザーIDに関連付けられます。

チャネル・アカウント・リンクを有効にして、スキルの複数のチャネルでユーザー・アイデンティティを認識できるようにします。たとえば、あるチャネルで会話を開始し、レスポンスを待機している場合、そのレスポンスの通知を他のチャネルで受信することもできます。

チャネル・リンクを有効にするには:

1. をクリックしてサイド・メニューを開き、「設定」→「統合アイデンティティ・サービス」を選択します。
2. 「チャネル・アカウント・リンク」スイッチを「オン」に設定します。

チャネル・アカウント・リンクをアクティブ化したら、スキルのOAuth 2.0アカウント・リンク・コンポーネントのrequiresAssociationConsentプロパティを使用して、各スキルのユーザー同意を個別に処理する方法を構成できます。オプションは次のとおりです。

• Yes: チャネル・アカウント・データを統合ユーザーIDに関連付けるための次の同意選択肢をユーザーに提示します。
  • アカウントの関連付け。ユーザーが現在のチャネル・アイデンティティと一元化された統合ユーザーIDのリンクを承認したことを確認します。
  • このアカウントをリンクしない。この特定のチャネル・アカウントを統合ユーザーIDに関連付けないことを示します。ユーザーは今後このアカウントをリンクするかどうかを尋ねられません(ただし、ユーザーは後でその決定を取り消すことができます)。
  • この時点では実行しません。現在のセッションのアカウントをリンクしませんが、後続のセッションでユーザーが承認を要求されるのを防ぐことはできません。同意プロンプトは、ユーザーがこのオプションを選択すると一時的に抑制されますが、ユーザーが24時間以上後に再度認証されると再表示される場合があります。
• No .ユーザー・チャネル・アカウントは、ユーザーが同意を求められることなく、統合ユーザーIDに自動的にリンクされます。
• Notify.ユーザー・チャネル・アカウントは統合ユーザーIDに自動的にリンクされ、その事実がユーザーに通知されます。

このプロパティのデフォルト値はYesです。

チャネル・アカウント・アイデンティティ情報が統合ユーザー・アイデンティティにリンクされていることをユーザーに通知したとき、または同意オプションが与えられている場合に、会話に表示されるプロンプトとメッセージのセットがあります。スキルのリソース・バンドルのメッセージでこれらのプロンプトのフレーズを調整できます。

リソース・バンドル内のこれらの特定のプロンプトとメッセージにアクセスするには:

1. スキルで、をクリックしてリソース・バンドルを開きます。
2. 「構成」タブを選択します。
3. 「フィルタ」フィールドにOAuthAccount2Link - consentと入力して、同意関連のバンドル・エントリを表示します。

統合ユーザー・アイデンティティ・データが格納される時間の長さは、インスタンス・レベルで設定されます。

そのようなデータが格納される時間を構成するには:

1. をクリックしてサイド・メニューを開き、「設定」→「統合アイデンティティ・サービス」を選択します。
2. 「指定した保存期間後にユーザーのチャネル・アカウント・データを削除」スイッチを「オン」に設定します。

   オンにしないと、ユーザーのチャネル・アカウント・データは無期限に保持されます。

3. チャネル・アカウント・ユーザー・データの保持期間(日数)に、データを格納する日数を入力します。

   最小値は7、最大値は1100です。

   ノート
   
   データをパージするジョブは、24時間から48時間ごとに1回のみ実行されます。そのため、ジョブの時間によっては、指定した保存期間より最大48時間長くデータが保持される場合があります。