署名付き埋め込み

署名付き埋め込みは、Looker の独立したログインを必要とせずに、埋め込みまれたプライベートの Look、可視化、Explore、ダッシュボード、LookML ダッシュボードをユーザーに提供する手段です。代わりに、ユーザーは自社のアプリケーションを介して認証されます。

署名付き埋め込みは、iframe で使用される特別な Looker URL を作成することで機能します。この URL には、共有したい情報、システムにおけるユーザーの ID、そのユーザーに付与する権限を含めます。その後、URLに、Lookerから提供されたシークレットキーを使用して署名します。

公開埋め込みについては、Look のパブリック共有、インポート、組み込みのドキュメント ページの iframe タグを使用した公開埋め込みをご覧ください。

Looker インスタンスで署名付き埋め込みを使用するには、Looker 管理者が Looker 管理パネルで署名付き埋め込みを有効にし、埋め込みシークレット鍵を作成する必要があります。手順については、埋め込みのスタートガイド - 署名付き埋め込みを有効にするのドキュメント ページをご覧ください。

署名付き埋め込みのための適切なホスティング

一部のブラウザ(Safari や、広告やトラッキング Cookie をブロックする拡張機能がインストールされているブラウザ)では、デフォルトでサードパーティの Cookie をブロックします。Cookieless Embed 機能を有効にすると、サードパーティ Cookie をブロックするブラウザで、複数のドメインにわたる埋め込み iframe 内のユーザーを認証できます。Cookieless Embed 認証には、サーバー側の構成が必要です。設定例については、Cookie を使用しない埋め込みのドキュメント ページをご覧ください。

Cookieless Embed 機能が有効になっていない場合、Looker はユーザー認証に Cookie を使用します。この場合、サードパーティの Cookie をブロックするブラウザでは、ドメインをまたいだ組み込み iFrame の認証の試みは失敗します(ただし、ユーザーがブラウザの Cookie プライバシー設定を変更している場合はその限りではありません)。たとえば、https://mycompany.com に情報を埋め込む場合、Looker が同じドメイン(https://analytics.mycompany.com など)を共有するように設定する必要があります。この場合、インスタンスが Looker によってホストされている場合は、Looker サポートに問い合わせて、カスタム ドメインの使用を有効にするために必要な DNS 構成の設定を依頼してください。これにより、Lookerは組み込まれたアプリケーションと同じドメインを共有し、すべてのブラウザでデフォルトで許可されるファーストパーティのCookieを利用できるようになります。

お客様がホストする Looker インスタンスがある場合、署名付き組み込みを使用するアプリケーションがその Looker インスタンスと同じドメインを使用していることを確認してください。

クローズドシステムを使用したクライアント可視性の制御

署名付き埋め込み構成では、Looker ユーザーが自分の顧客にデータを提示し、互いを知らなくても異なる企業やグループのクライアントにデータを提供することがよくあります。このようなシナリオでは、顧客の個人情報を保護するため、Looker をクローズドシステム(マルチテナント インストールとも呼ばれる)として設定することを強くお勧めします。クローズドシステムでは、コンテンツがサイロ化されるので、異なるグループのユーザーが相互を認識することができなくなります。このため、外部ユーザーにインスタンスへのアクセスを許可する前に、クローズド システム オプションを有効にすることをおすすめします。

詳細については、アクセスレベルのシステムの設計と構成と、埋め込み分析向けのセキュリティに関するベスト プラクティスのドキュメント ページをご覧ください。

署名付き埋め込み URL の生成

署名付き埋め込み URL を生成するには、いくつかの方法があります。次のいずれかの方法を使用できます。

署名付き埋め込み URL の手動コーディング

署名付き埋め込み URL を直接記述するには、まず必要な Looker 情報を収集してから、署名付き埋め込み URL を作成します。

必要なLooker情報の収集

URLを構築する際には、まず、含める必要があるすべての情報を決定します。次のものが必要になります。

組み込みURL

埋め込む Look、Explore、クエリ ビジュアリゼーション、ダッシュボードの URL を取得します。その後、次のようにドメインを削除し、パスの前に /embed を追加します。

項目 通常のURLパターン 組み込みURL
Look https://instance_name.looker.com/looks/4 /embed/looks/4
探索 https://instance_name.looker.com/explore/my_model/my_explore /embed/explore/my_model/my_explore
クエリ ビジュアリゼーション https://instance_name.looker.com/explore/my_model/my_explore?qid=1234567890abcdefghij12

Explore URL の qid= パラメータに続く 22 文字の英数字が Query.client_id を構成します。Query.client_id 値は、クエリと可視化の設定を表す一意の文字列です。

クエリの可視化を埋め込むには、クエリの可視化 Query.client_id 値を取得し、埋め込み URL に Query.client_id をコピーします。

Looker の Explore UI を使用して、サポートされている可視化でクエリを作成し、qid= パラメータから Query.client_id 値をコピーします。または、Get Query メソッドなどを使用して、Looker API で Query.client_id を取得できます。
/embed/query-visualization/Query.client_id
ユーザー定義ダッシュボード https://instance_name.looker.com/dashboards/1

ダッシュボードのフィルタ値を含めるか、フィルタ値を非表示にする場合、ダッシュボードの URL に hide_filter パラメータを含めます。
ユーザー定義のレガシーダッシュボード https://instance_name.looker.com/dashboards-legacy/1 /embed/dashboards-legacy/1
LookML ダッシュボード https://instance_name.looker.com/dashboards/my_model::my_dashboard /embed/dashboards/my_model::my_dashboard
レガシー LookMLダッシュボード https://instance_name.looker.com/dashboards-legacy/my_model::my_dashboard /embed/dashboards-legacy/my_model::my_dashboard

埋め込まれたコンテンツは、常にコンテンツの実働バージョンを反映します。コンテンツに影響を与えるものの、プロダクションにまだデプロイされていない、開発モードで加えられた変更すべては、埋め込みでは表示されません。

権限

権限セットは、ユーザーまたはグループが行えることを定義します。権限は、次の 2 つの方法のいずれかで適用できます。

  • モデル固有: このタイプの権限は、同じロールに含まれるモデルセットにのみ適用されます。
  • インスタンス全体: このタイプの権限は、Looker インスタンス全体に適用されます。インスタンス全体の権限を持つ埋め込みユーザーは、Lookerインスタンス全体で特定の機能を実行できますが、そのロールのモデルセットに含まれていないモデルをベースにしたコンテンツにはアクセスできません。

ユーザーに付与する権限を決定します。次のリストでは、署名付き埋め込みに使用できるすべての権限を示します。署名付き埋め込みで、次のリストに記載されていない権限はサポートされていません。

権限 依存関係 Type 定義
access_data なし モデルに固有 データにアクセスすることをユーザーに許可します(Look、ダッシュボード、Exploreを閲覧するために必要です)。
see_lookml_dashboards access_data モデルに固有 ユーザーは、LookML ダッシュボードを表示できる
see_looks access_data モデルに固有 ユーザーは、Look を表示できる
see_user_dashboards see_looks モデルに固有 ユーザーは、ユーザー定義のダッシュボードを表示し、埋め込みからフォルダを参照できる
explore see_looks モデルに固有 Exploreページを閲覧することをユーザーに許可します
create_table_calculations explore インスタンス全体 Explore から表計算を作成するために必要
create_custom_fields explore インスタンス全体 22.4 で追加 Explore でカスタム フィールドを作成する必要がある
can_create_forecast explore インスタンス全体 22.12 で追加 ユーザーがビジュアリゼーションでの予測を作成または編集できる。
save_content see_looks インスタンス全体 ユーザーが Look とダッシュボードに変更を加えて保存できるようにする
send_outgoing_webhook see_looks モデルに固有 ユーザーが任意の Webhook への Looker コンテンツ配信をスケジュールできるようにする
send_to_s3 see_looks モデルに固有 ユーザーが Amazon S3 バケットへの Looker コンテンツ配信をスケジュールできるようにする
send_to_sftp see_looks モデルに固有 ユーザーが SFTP サーバーへの Looker コンテンツ配信をスケジュールできるようにする
schedule_look_emails see_looks モデルに固有 ユーザーが Looker コンテンツ配信を自分のメール(「email」というユーザー属性で設定した場合)またはメールドメイン許可リストによって設定された制限内のメールアドレスに対してスケジュールできる。create_alerts 権限を持つユーザーは、メールドメインの許可リストで設定された制限内のメールアドレスにアラート通知を送信できる。
schedule_external_look_emails schedule_look_emails モデルに固有 ユーザーは任意のメールドメインに対して Looker コンテンツの配信をスケジュールできる。create_alerts 権限を持つユーザーは、任意のメールドメインにアラート通知を送信できます。
send_to_integration see_looks モデルに固有 ユーザーは、Looker Action Hub を介して Looker と統合されたサードパーティのサービスLooker コンテンツを配信できます。この権限はデータ アクションとは無関係です。
create_alerts see_looks インスタンス全体 指ユーザーは、ダッシュボード タイルにアラートを作成して、指定された条件が満たされるか超過したときに通知を受信するようにできます。ユーザーは、自分自身のアラートとその他のユーザーの一般公開アラートを編集、複製、削除できます。ユーザーの Slack ワークスペースが Looker インスタンスに接続されていない場合、ユーザーは Slack に通知を送信するアラートを作成できません。
download_with_limit see_looks インスタンス全体 クエリの結果を制限付きでダウンロードすることをユーザーに許可します。
download_without_limit see_looks インスタンス全体 クエリの結果を制限なしでダウンロードすることをユーザーに許可します。
see_sql see_looks モデルに固有 クエリ用のSQL、およびクエリの実行で発生したSQLエラーを見ることをユーザーに許可します。
clear_cache_refresh access_data モデルに固有 21.14 で追加 ユーザーは、キャッシュを消去し、埋め込みダッシュボード、以前のダッシュボード、ダッシュボード タイル、Look、Explore を更新できます。
see_drill_overlay access_data モデルに固有 完全なExploreページに移動することなくドリルダウンすることをユーザーに許可します。
embed_browse_spaces なし インスタンス全体 コンテンツブラウザを有効にして、ユーザーが埋め込みからフォルダを参照できるようにします。embed_browse_spaces 権限を付与された埋め込みユーザーは、個人用の埋め込みフォルダと、所属組織の [共有] フォルダ(存在する場合)にアクセスできます。

embed_browse_spaces権限は、save_content 権限を持つユーザーに付与することをおすすめします。そうすると、コンテンツの保存先を選択するときにフォルダを参照できるようになります。

フォルダ内のコンテンツを表示するには、see_lookssee_user_dashboardssee_lookml_dashboards の各権限も必要になります。
embed_save_shared_space なし インスタンス全体 21.4 で追加 save_content 権限も持つユーザーが、組織の [共有] フォルダがある場合に、[保存] ダイアログ ボックスからアクセスできます。save_content 権限はあるものの embed_save_shared_space 権限はないユーザーは、個人用埋め込みフォルダにのみコンテンツを保存できます。

embed_save_shared_space 権限でコンテンツ アクセス権限はオーバーライドされません。たとえば、ユーザーが [共有] フォルダに保存できるようにするには、[共有] フォルダに対する [アクセスの管理、編集] 権限が必要です。さらに、embed_save_shared_space 権限がなくても、save_content 権限と [共有] フォルダに対する [アクセスの管理、編集] 権限を持つユーザーは、埋め込みダッシュボードの [ここから探索] オプションを使用するなどして [共有] フォルダに移動する代替手段があれば、そこにコンテンツを保存することができます。

モデルアクセス

ユーザーにアクセス権限を付与するLookMLモデルを決定します。これは単にモデル名のリストになります。

ユーザー属性

ユーザーが設定する必要があるユーザー属性を決定します(存在する場合)。Lookerからのユーザー属性の名前と、ユーザーがその属性に対して設定する必要がある値が必要になります。

グループ

ユーザーが属している必要があるグループを決定します(存在する場合)。グループ名ではなくグループIDが必要になります。署名付き埋め込みユーザーを Looker グループに追加することによって、Looker のフォルダへのユーザー アクセスを管理できるようになります。署名付き埋め込みユーザーは、Looker グループのメンバーと共有されている任意のフォルダにアクセスできます

external_group_id パラメータを使用して、通常の Looker グループの外部にあるグループを作成することもできます。その場合、同じ external_group_id を持つ署名付き組み込みユーザーは、外部グループに固有の共有フォルダにアクセスできるようになります

埋め込みのロール

permissions パラメータと models パラメータは、埋め込みユーザーのロールを作成します。このロールは、Looker の [管理者] セクションの [ユーザー] ページに「埋め込みのロール」として表示されます。埋め込み URL で permissionsmodelsgroup_ids のすべてのパラメータが指定されている場合、埋め込みのロールが、group_ids パラメータで一覧表示されているグループにすでに割り当てられているロールに追加されます。これは、Lookerですべてのロールが付加的であるという点で標準ロールと同じです。

たとえば、Looker にグループ ID 1 の既存のグループがあり、そのグループには model_one という名前のモデルに関して explore 権限がすでに与えられている場合に、以下のパラメータを使用して埋め込み URL を作成するとします。

  • group_ids = ["1"]
  • permissions = ["access_data","see_looks"]
  • models = ["model_two"]

この場合、埋め込みのユーザーは model_one のデータを表示および探索する権限を継承します。加えて、前述のパラメータを使用して作成された埋め込みのロールでは、model_two のデータを表示する権限も付与されます。

埋め込み URL の作成

署名付き埋め込み URL の形式は次のとおりです。

https://ホストhttps://埋め込み URLhttps://パラメータhttps://署名

Host(ホスト)

ホストは、Lookerインスタンスがホストされている場所です。例: analytics.mycompany.comポート転送をまだ有効にしていない場合は、analytics.mycompany.com:9999 のように、ポート番号を必ず含めてください。

組み込みURL

埋め込みURLは前述のとおり決定します。書式は次のようになります。

  • /embed/looks/4
  • /embed/explore/my_model/my_explore
  • /embed/query-visualization/Query.client_id
  • /embed/dashboards/1 または /embed/dashboards-legacy/1
  • /embed/dashboards/my_model::my_dashboard または /embed/dashboards-legacy/my_model::my_dashboard

したがって、最終的な URL にはパターン /embed//embed/ が含まれることになります(これは正しい表記です)。

埋め込み JavaScript イベントを使用する場合は、次のように埋め込み URL の末尾に必ず embed_domain(iFrame が使用されているドメイン)を追加してください。

/embed/looks/4
/embed/looks/4?embed_domain=https://mywebsite.com

embed_domain は埋め込み URL の後、任意のパラメータの前に追加されます。したがって、nonce=626 のような既存のパラメータがある場合、embed_domain の追加は次のようになります。

/embed/looks/4?nonce=626
/embed/looks/4?embed_domain=https://mywebsite.com?nonce=626

Embed SDK を使用している場合は、次のように embed_domain を追加して、埋め込み URL の末尾に sdk=2 を含めてください。

/embed/looks/4
/embed/looks/4?embed_domain=https://mywebsite.com&sdk=2

sdk=2 パラメータを指定することで、Looker に SDK の存在が認識され、SDK によって提供される追加機能を利用できるようになります。このパラメータは署名付き URL の一部であることから、SDK がこのパラメータ自体を追加することはできません。

パラメータ

次の URL パラメータを使用して、署名付き埋め込みに必要な情報を指定します。

パラメータ デフォルト値 説明 データ型
nonce 値は必須です 任意のランダムな文字列。ただし、255 文字未満で、1 時間以内に繰り返し使用することはできません。

これにより、攻撃者が正規ユーザーの URL を再送信して情報を不正に収集するのを防ぎます。
JSON文字列 "22b1ee700ef3dc2f500fb7"
time 値は必須です UNIXタイムスタンプとしての現在時刻。 Integer 1407876784
session_length 値は必須です ユーザーに許容されるLookerへの継続ログイン時間(0〜2,592,000秒(30日))。 Integer 86400
external_user_id 値は必須です Looker を埋め込んでいるアプリケーション内の各ユーザーの識別子。Looker では、署名付き埋め込みユーザーの区別に external_user_id が使用されるため、各ユーザーに一意の ID を割り当てる必要があります。

任意の文字列を持つユーザーの external_user_id は、そのユーザーに固有のものであれば作成できます。各IDは、権限、ユーザー属性、モデルのセットに関連付けられています。1 つのブラウザが一度にサポートできるのは、1 つの external_user_id またはユーザー セッションだけです。セッション内でユーザーの権限やユーザー属性を変更することはできません。

セキュリティ上の理由から、異なるインタラクティブ ユーザーの異なる埋め込みセッションで同じ external_user_id を使用していないことを確認します。また、異なる権限、ユーザー属性値、モデルアクセスを持つ単一のユーザーに同じ external_user_id を使用していないことを確認します。

同じ external_user_id を複数のユーザーや、複数の権限、ユーザー属性、またはモデルセットを持つ同じユーザーに使用すると、本来アクセスできないユーザーがデータを見ることができるようになる可能性があります。
JSON文字列 "user-4"
permissions 値は必須です ユーザーが持つ必要のある権限の一覧

許可されている権限のリストについては、このページの権限セクションをご覧ください。
文字列の配列 [

  "access_data",

  "see_looks"

]
models 値は必須です ユーザーにアクセス権を付与するモデル名のリスト。 文字列の配列 [

  "model_one",

  "model_two"

]
group_ids [] ユーザーがメンバーとなっている必要のあるLookerグループのリスト(存在する場合)。グループ名ではなくグループIDを使用します。 文字列の配列 ["4", "3"]
external_group_id "" Looker を埋め込んでいるアプリケーションでユーザーが属するグループの一意の識別子(必要な場合)。

コンテンツの保存権限と外部グループ ID の共有権限を持つユーザーは、「Group」という Looker の共有フォルダにコンテンツを保存、編集できます。external_group_id パラメータは、埋め込みユーザーの外部グループを作成する唯一の方法です。Looker UI から外部の埋め込みユーザー グループを構成する方法はありません。
JSON文字列 "Accounting"
user_attributes {} ユーザーが設定する必要があるユーザー属性のリスト(存在する場合)。ユーザー属性の名前とそれに続く属性値のリストを指定します。

LookML モデルがローカライズされている場合は、埋め込み URL で locale ユーザー属性を使用して、埋め込みの言語を指定します。たとえば、パラメータ user_attributes { "locale" : "fr_FR" } を含めると、埋め込みではフランス語を言語としてロードします。
文字列のハッシュ {

  "vendor_id" : "17",

  "company" : "xactness"

}
access_filters 値は必須です Looker 3.10では、このパラメータは削除されますが、URLでは引き続き必要です。access_filters は、空のプレースホルダ(access_filters={} など)とともに使用します。 空のプレースホルダ {}
first_name "" ユーザーの名。空白のままにした場合、first_name には前回のリクエストからの値が保持されるか、過去に姓が設定されていない場合は「Embed」が挿入されます。 JSON文字列 "Alice"
last_name "" ユーザーの姓。空白のままにした場合、last_name には前回のリクエストからの値が保持されるか、過去に姓が設定されていない場合は「Embed」が挿入されます。 JSON文字列 "Jones"
user_timezone "" ユーザー固有のタイムゾーンを有効にしている場合は、埋め込み Look またはダッシュボードの [タイムゾーン] プルダウンで [閲覧者のタイムゾーン] オプションの値を設定します。このパラメータにより、コンテンツを表示するタイムゾーンが直接変更されることはありません。タイムゾーンは、ユーザーがプルダウンから選択する必要があります。

署名付き埋め込みのタイムゾーン リファレンス ドキュメント ページの有効な値をご覧ください。

Chat チームのヒント: 埋め込まれたコンテンツを閲覧者のデフォルトのタイムゾーンにするには、次のいずれかの方法を使用します。

  • パラメータ ?query_timezone=user_timezone埋め込み URL に追加します。例:

    /embed/dashboards/1?query_timezone=user_timezone
  • 埋め込みダッシュボードまたは Look デフォルト タイムゾーンを [ビューアのタイムゾーン] に設定して保存すると、埋め込みユーザーにも非埋め込みユーザーにもデフォルトでユーザーのタイムゾーンが使用されます。
  • JSON文字列またはnull "US/Pacific"

    または

    null
    force_logout_login 値は必須です 通常の Looker ユーザーがすでに Looker にログインし、署名付きの埋め込み項目を表示している場合は、次のいずれかを選択できます。

    1)現在の認証情報で項目を表示する

    または

    2)ログアウトして、署名付きの埋め込み認証情報で再度ログインする。
    Boolean(trueまたはfalse) true

    署名

    Looker は、署名を使用して、埋め込み URL の署名の生成に正しい埋め込みシークレットを使用していることと、埋め込み URL のパラメータが変更されていないことを確認します。埋め込みシークレットまたは URL パラメータが異なる場合、または変更された場合、署名が一致せず、認証が拒否されます。

    その結果、埋め込み URL の署名は、埋め込み URL が転送中に変更されていないことと、埋め込み URL が埋め込み秘密鍵を所有する信頼できる関係者によって作成されたという、暗号的に強力な証拠を提供します。

    署名を生成するには、次の手順に従います。

    1. 次のパラメータ値をこの順序で収集します。
      • ホストの後に login/embed/ を指定します(例: analytics.mycompany.com/login/embed/)。
      • 組み込みURL
      • ノンス
      • 現在時刻
      • セッションの長さ
      • 外部ユーザーID
      • 権限
      • モデル
      • グループID
      • 外部グループID
      • ユーザー属性
      • アクセスフィルタ(空のプレースホルダが必要です)
    2. ホストと埋め込みURL以外のすべての値をJSONとして書式設定します。
    3. 値を改行(\n)で連結します
    4. Looker 埋め込み秘密鍵を使用して連結文字列に HMAC-SHA1 署名を追加します。

    エンコード

    最後のステップはURLエンコーディングです。

    想定されるすべてのパラメータを使用して適切に書式設定したエンコーディング前の埋め込み URL は、次のようになります。

    https://analytics.mycompany.com/login/embed//embed/dashboards/1?
    nonce="22b1ee700ef3dc2f500fb7"&
    time=1407876784&
    session_length=86400&
    external_user_id="user-4"&
    permissions=["access_data","see_user_dashboards","see_looks"]&
    models=["model_one","model_two"]&
    group_ids=[4,3]&
    external_group_id="Allegra K"&
    user_attributes={"vendor_id":"17","company":"xactness"}&
    access_filters={}&
    first_name="Alice"&
    last_name="Jones"&
    user_timezone="US/Pacific"&
    force_logout_login=true&
    signature=123456789ABCDEFGHIJKL
    

    URL に /embed//embed/ が含まれていますが、前述のとおり、これは正しい表記です。

    URL をエンコーディングした後は、次のようになります。

    https://analytics.mycompany.com/login/embed/%2embed%2Fdashboards%2F1?
    nonce=%2222b1ee700ef3dc2f500fb7&%22&
    time=1407876784&
    session_length=86400&
    external_user_id=%22user-4%22&
    permissions=%5B%22access_data%22%2C%22see_user_dashboards%22%2C%22see_looks%22%5D&
    models=%5B%22model_one%22%2C%22model_two%22%5D&
    group_ids=%5B4%2C3%5D&
    external_group_id=%22Allegra%20K%22&
    user_attributes=%7B%22vendor_id%22%3A%2217%22%2C%22company%22%3A%22xactness%22%7D&
    access_filters%7B%7D%26%0A
    first_name=%22Alice%22&
    last_name=%22Jones%22&
    user_timezone=%22US%2FPacific%22&
    force_logout_login=true&
    signature=123456789ABCDEFGHIJKL
    

    Create Signed Embed Url API エンドポイントの使用

    Looker API には、Create Signed Embed Url エンドポイントが含まれています。このエンドポイントは、埋め込むコンテンツの URL を含む一連の署名付き埋め込みパラメータを取得し、エンコードされ暗号署名された URL 全体を返します。

    この API エンドポイントをウェブサーバーから使用するには、ウェブサーバーが管理者権限で Looker API に認証されるようにする必要があります。ウェブサーバー ドメインも [埋め込みドメイン許可リスト] に表示されている必要があります。

    API Explorer を使用して、このエンドポイントを使用する署名付き URL を生成することもできます。Looker インスタンスに API Explorer をインストールするには、Looker Marketplace を使用します。生成された署名付き URL は、正確にコピーする必要があり、一度だけ使用できます。そうでない場合はエラーになります。API Explorer は、トラブルシューティングを目的として、署名付き URL を生成し手動で作成した署名付き URL と比較できます。

    Looker API の詳細については、Looker API スタートガイドのドキュメント ページをご覧ください。

    埋め込み URL のテスト

    最終的な URL をテストする場合は、Looker の [管理] セクションの [埋め込み] ページにある [Embed URI Validator] に URL を貼り付けます。このオプションは、想定したデータや権限が正しく設定されているかどうかを判別するためのものではなく、認証が正しく機能するかどうかを検証するためのものです。