署名付き埋め込み

署名付き埋め込みは、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 の生成は、ダッシュボードの三点メニューか、Explore のアクション（歯車）メニューで [埋め込み URL を取得する] オプションを使用することにより行う。

• Looker API Create Signed Embed Url エンドポイントを使用する（詳細はこのドキュメントの後半をご覧ください）。

• Looker Embed SDK を使用します。

• 署名付き埋め込み URL を直接記述する。適切なURLを構築するには、秘密鍵で URL を適切にエンコードし、他のセキュリティ関連項目を生成できるようにコードを記述する必要があります。Looker 埋め込みサンプルの GitHub リポジトリには、いくつかのサンプル スクリプトがあります。以降のセクションでは、これらのスクリプトで提供する必要がある情報と、スクリプトを使用せずに署名付き埋め込み URL を構築する方法について説明します。

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

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

必要なLooker情報の収集

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

組み込みURL

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

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

権限

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

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

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

モデルアクセス

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

ユーザー属性

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

グループ

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

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

埋め込みのロール

permissions パラメータと models パラメータは、埋め込みユーザーのロールを作成します。このロールは、Looker の [管理者] セクションの [ユーザー] ページに「埋め込みのロール」として表示されます。埋め込み URL で permissions、models、group_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://ホスト/login/embed/埋め込み URL?パラメータ&signature=署名

ホスト

ホストは、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_domain は埋め込み URL の後、任意のパラメータの前に追加されます。したがって、nonce=626 のような既存のパラメータがある場合、embed_domain の追加は次のようになります。

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

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

パラメータ

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

署名

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 を貼り付けます。このオプションは、想定したデータや権限が正しく設定されているかどうかを判別するためのものではなく、認証が正しく機能するかどうかを検証するためのものです。