SAML 属性プロパゲーションの構成

このページでは、SAML（Security Assertion Markup Language）属性のプロパゲーションを有効にして使用する方法について説明します。この機能を使用すると、ID プロバイダから SAML 属性を Identity-Aware Proxy（IAP）で保護されたアプリケーションにプロパゲートできます。SAML 属性をプロパゲートする場合、プロパゲートする属性と属性の提供方法を指定できます。

始める前に

SAML 属性のプロパゲーション機能を使用するには、Chrome Enterprise Premium ライセンスが必要です。

SAML V2.0 のアサーションとプロトコルの仕様に精通している必要があります。

データの処理方法について

SAML 属性のプロパゲーションを有効にする前に、Google Cloud がデータを管理する方法と、このチャネルを介して渡す必要がある情報と送信すべき情報の種類を理解してください。

保護されるアプリケーションに提供する情報に 1 つ以上の属性を含めるように IAP を構成できます。サードパーティの ID プロバイダを使用して SSO を設定していて、ID プロバイダが SAML アサーションに <AttributeStatement> を含める場合、Google Cloud はユーザーの Google アカウントセッションに関連付けられた属性を一時的に格納します。Google アカウントセッションの有効期限が切れると、非同期プロセスによって 1 週間以内に完全に削除されます。有効期限は構成できます。

アカウントの認証情報、政府発行の個人識別番号、カード所有者情報、金融口座データ、医療情報、機密情報などの個人情報（PII）に SAML 属性のプロパゲーションを使用しないでください。

SAML 属性のプロパゲーションを有効にする

Google Workspace で SSO プロファイルを作成して SAML 属性のプロパゲーションを有効にし、Google Cloud CLI または REST API を使用して IAP 設定を更新します。

Console

Google Cloud コンソールの [IAP] ページに移動します。
IAP に移動
リソースの設定を開き、[属性の伝播] までスクロールします。
[属性の伝播を有効にする] を選択し、[保存] をクリックします。
[SAML の属性] タブで、次の形式を使用して、伝播する属性を入力します。attribute1, attribute2, attribute3

カスタム式を使用して属性を入力することもできます。カスタム式の属性は [SAML の属性] タブに表示されます。属性を [SAML の属性] タブに表示する場合は、次の式形式を使用する必要があります。
attributes.saml_attributes.filter(attribute, attribute.name in ['attribute', 'attribute2', 'attribute1'])
[Credential types to pass] で、IdP からアプリケーションに渡す属性形式を 1 つ以上選択します。

gcloud

次の IAP gcloud CLI コマンドを実行して、SAML 属性のプロパゲーション設定を更新します。

gcloud iap settings set SETTING_FILE [--folder=FOLDER --organization=ORGANIZATION --project=PROJECT> --resource-type=RESOURCE_TYPE --service=SERVICE --version=VERSION] [GCLOUD_WIDE_FLAG …]

次のように置き換えます。

FOLDER: アプリケーションが存在するフォルダ。
ORGANIZATION: アプリケーションが存在する組織。
PROJECT: アプリケーションが存在するプロジェクト。
RESOURCE_TYPE: リソースタイプ。
SERVICE: サービス。
VERSION: バージョン番号。

YAML:

applicationSettings:
 attributePropagationSettings:
  expression: CEL_EXPRESSION
  outputCredentials: ARRAY[OUTPUT_CREDENTIALS]
  enable: BOOLEAN

JSON:

{
   "application_settings":{
      "attribute_propagation_settings": {
        "expression": CEL_EXPRESSION,
        "output_credentials": ARRAY[OUTPUT_CREDENTIALS]
        "enable": BOOLEAN
      }
   }
}

REST API

次の例に示すように、IapSettings の ApplicationSettings オブジェクトを使用して、伝播する SAML 属性を構成できます。

{
 "csmSettings": {
    object (CsmSettings)
  },
  "accessDeniedPageSettings": {
    object (AccessDeniedPageSettings)
  },
 "attributePropagationSettings": {
    object (AttributePropagationSettings)
  },
  "cookieDomain": string,
}

AttributePropagationSettings

{
 "expression": string,
 "output_credentials": array
 "enable": boolean
}

出力認証情報の設定

SAML 属性の伝播を使用する場合は、出力認証情報を設定することで、JSON Web Token（JWT）やヘッダーなどの複数のメディア間で属性を送信できます。API で認証情報を設定するには、次の例に示すように、カンマ区切りの文字列のリストを指定します。

"output_credentials": ["HEADER", "JWT", "RCTOKEN"]

Common Expression Language を使用した SAML 属性のフィルタリング

Common Expression Language（CEL）関数を使用して SAML 属性をフィルタリングできます。

SAML 属性のプロパゲーションで CEL 式を使用する場合、次の制限があります。

式は属性のリストを返す必要があります。
式では、最大 45 個の属性を選択できます。
式の文字列は 1,000 文字以内にする必要があります。

IAP SAML 属性の伝播機能を使用するときにサポートされる CEL 関数は次のとおりです。

関数では大文字と小文字が区別されるため、正確に使用する必要があります。関数呼び出しを連結する場合、strict 関数と emitAs 関数の順序は関係ありません。

関数	例	説明
フィールド選択	`a.b`	proto `a` からフィールド `b` を選択します。文字 `b` は、別の proto、リスト、または文字列などの単純な値の型です。
リストのフィルタリング	`list.Filter(iter_var, condition)`	アイテムが `condition` を満たす `list` のサブセットを返します。
リストのメンバーシップ	`a`（`b`）	値 `a` がリスト `b` のメンバーである場合、`true` を返します。
selectByName	`list.selectByName("name")`	リストから、`name = "name"` の属性を選択します。
append	`list.append(attribute)`	指定された属性を指定されたリストに追加します。
strict	`attribute.strict()`	出力認証情報として `HEADERS` を使用する場合、`x-goog-iap-attr-` 接頭辞なしで属性を出力します。
emitAs	`attribute.emitAs("new_name")`	選択したすべての出力認証情報に対して、`"new_name"` という名前の指定された属性を出力します。

CEL 式の例

SAML アサーションを想定しています。

<saml2:AttributeStatement xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
  <saml2:Attribute Name="my_saml_attr_1">
    <saml2:AttributeValue xsi:type="xsd:string">value_1</saml2:AttributeValue>
    <saml2:AttributeValue xsi:type="xsd:string">value_2</saml2:AttributeValue>
  </saml2:Attribute>
 <saml2:Attribute Name="my_saml_attr_2">
    <saml2:AttributeValue xsi:type="xsd:string">value_3</saml2:AttributeValue>
    <saml2:AttributeValue xsi:type="xsd:string">value_4</saml2:AttributeValue>
  </saml2:Attribute>
 <saml2:Attribute Name="my_saml_attr_3">
    <saml2:AttributeValue xsi:type="xsd:string">value_5</saml2:AttributeValue>
    <saml2:AttributeValue xsi:type="xsd:string">value_6</saml2:AttributeValue>
  </saml2:Attribute>
</saml2:AttributeStatement>

my_saml_attr_1 を選択するには、次の CEL 式を使用します。

attributes.saml_attributes.filter(attribute, attribute.name in ["my_saml_attr_1"])

my_saml_attr_1 と my_saml_attr_2 を選択するには、次の CEL 式を使用します。

attributes.saml_attributes.filter(attribute, attribute.name in ["my_saml_attr_1", "my_saml_attr_2"])

属性の形式

選択したすべての属性が、選択したすべての出力認証情報で完全に重複しています。

例: SAML アサーションを想定する

<saml2:AttributeStatement xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
  <saml2:Attribute Name="my_saml_attr_1">
    <saml2:AttributeValue xsi:type="xsd:string">value_1</saml2:AttributeValue>
    <saml2:AttributeValue xsi:type="xsd:string">value_2</saml2:AttributeValue>
  </saml2:Attribute>
</saml2:AttributeStatement>

JWT トークンと RC トークン

JWT トークンは、additional_claims フィールドを通じて属性を提供します。このフィールドはオブジェクトであり、属性名と属性値のリストのマッピングが含まれています。属性名は、提供された SAML アサーションから変更されません。

SAML アサーションの例の場合、IAP JWT には次の内容が含まれます。

{
  "additional_claims": {
    "my_saml_attr_1": ["value_1", "value_2"]
  }
}

SAML アサーション内のヘッダー

ヘッダーでは、属性、キー、名前の値が RFC 3986 に従って URL エスケープされ、カンマで結合されます。たとえば、header&name: header$value は x-goog-iap-attr-header%26name: header%24value になります。

IAP ヘッダーを一意に識別するため、各ヘッダーには IAP 接頭辞 x-goog-iap-attr- が含まれています。セキュリティ上の理由から、ロードバランサは接頭辞が x-goog-iap-attr のリクエストヘッダーをすべて削除します。これにより、アプリが受信するヘッダーが IAP によって生成されます。

SAML アサーションの例の場合、ヘッダーは次のようになります。

"x-goog-iap-attr-my_saml_attr_1": "value_1,value_2"

次の例は、IAP が value&1、value$2、value,3 などのヘッダー内の属性をプロパゲートするときに特殊文字をエスケープする方法を示しています。

"x-goog-iap-attr-my_saml_attr_1": "value%261,value%242,value%2C3"

ヘッダー名のエスケープ方法の例を次に示します。

ヘッダー名:

"iap,test,3": "iap_test3_value1,iap_test3_value2"

エスケープされたヘッダー名:

"X-Goog-IAP-Attr-iap%2Ctest%2C3": "iap_test3_value1,iap_test3_value2"

属性をカスタマイズする

selectByName、append、strict、emitas 関数を使用して、伝搬された属性名の変更、一部の属性にヘッダー接頭辞を使用するかどうかの指定、および IAP で提供された新しい属性を選択できます。

SAML 属性の伝搬は必要ないが、SM_USER フィールドにメールアドレス、デバイス ID、またはタイムスタンプが必要な場合は、iap_attributes list attributes.iap_attributes から、それらの属性を選択できます。

IAP には、user_email、device_id、timestamp の属性があります。

例

次の例は、selectByName、append、strict、emitas の関数を使用して属性をカスタマイズする方法を示しています。

SAML アサーションの例を想定しています。

selectByName

selectByName 関数を使用して、特定のリストから名前で 1 つの属性を選択します。たとえば、my_saml_attr_1 を選択するには、次の式を使用します。

attributes.saml_attributes.selectByName("my_saml_attr_1")

append

append 関数を使用して、属性のリストに属性を追加します。この属性は、サポートされている IAP 属性リストのいずれかから選択する必要があります。たとえば、my_saml_attr_1 を含むリストに my_saml_attr_2 を追加するには、次の式を使用します。

attributes.saml_attributes.filter(x, x.name in ["my_saml_attr_1"]).append(attributes.saml_attributes.selectByName("my_saml_attr_2"))

フィルタリストに "my_saml_attr_2" を追加できます。次のように追加を連結することで、複数の属性を追加してリストに追加することもできます。

attributes.saml_attributes.filter(x, x.name in ["my_saml_attr_1"]).append(
attributes.saml_attributes.selectByName("my_saml_attr_2")).append(
attributes.saml_attributes.selectByName("my_saml_attr_3"))

単一属性の付加は、strict と emitAs の機能と組み合わせると最も効果的です。

strict

IAP が名前の先頭に x-goog-iap-attr- を付けないように、strict 関数を使用して属性にフラグを付けます。これは、バックエンドアプリケーションに対して正確な属性名を使用する必要がある場合に有用です。例:

attributes.saml_attributes.selectByName("my_saml_attr_1").strict()

emitAs

emitAs 関数を使用して、属性の新しい名前を指定します。指定した名前は、すべての認証情報に出力されます。たとえば、my_saml_attr_1 の名前を custom_name に変更するには、次の式を使用します。

attributes.saml_attributes.selectByName("my_saml_attr_1").emitAs("custom_name")

さまざまな関数を使用して、特定のユースケースに合わせて属性をカスタマイズできます。たとえば、次の式を使用して、IAP 属性からのユーザーのメールアドレスを他の SAML 属性とともに "SM_USER" として伝搬できます。

attributes.saml_attributes.filter(x, x.name in ["my_saml_attr_1"]).append(
attributes.iap_attributes.selectByName("user_email").emitAs("SM_USER").strict())

出力ヘッダーは次のようになります。

"x-goog-iap-attr-my_saml_attr_1": "value_1,value_2"
"SM_USER": "email@domain.com"

SAML 属性のプロパゲーションを使用する際の制約

ログイン時に、ID プロバイダからの受信属性には 2 KB の SAML 属性データの上限があります。最大 2 KB を超えるアサーションは拒否され、ログインが失敗します。

ほとんどのウェブサーバーのリクエストサイズの上限は 8 KB です。これにより、ヘッダー内での属性の重複を含めて、送信カスタム属性のサイズが制限されます。複製してエンコードされた属性のサイズ（名前と値）が 5,000 バイトを超える場合、IAP はリクエストを拒否し、IAP エラーコード 401 を返します。

SAML 属性のプロパゲーションUnicode 文字を使用

この機能では Unicode 文字と UTF-8 文字がサポートされないため、属性値は小文字の ASCII 文字列にする必要があります。アサーションが小文字の ASCII ではない場合、ログインは失敗します。