汎用 SAML アプリケーション

このページでは、SAML 認証プロトコルを使い、Cloudflare Access に SaaS アプリケーションを設定する汎用の手順を説明します。

前提条件

Cloudflare One に設定済みのアイデンティティプロバイダー
SaaS アプリケーションアカウントへの管理者アクセス

1. SaaS アプリケーションの URL を取得する

SaaS アプリケーションアカウントから、次の URL を取得します。

Entity ID: SaaS アプリケーションに発行される一意の URL。例: https://<your-domain>.my.salesforce.com
Assertion Consumer Service URL: SAML アサーションを受け取り、解析するためのサービスプロバイダーのエンドポイント

2. Access にアプリケーションを追加する

Cloudflare ダッシュボード ↗ で、Zero Trust > Access controls > Applications を開きます。
Create new application を選択します。
SaaS application を選択します。
ドロップダウンから Application を選択します。一覧にない場合は、Application フィールドにカスタム名を入力し、下に表示されるテキストボックスを選択します。
SAML を選択します。
Add application を選択します。
SaaS アプリケーションアカウントから取得した Entity ID と Assertion Consumer Service URL を入力します。
SaaS アプリケーションが期待する Name ID Format を選択します（通常は Email）。
（任意）SaaS アプリケーションが必要とする追加の SAML 属性ステートメントを設定します。
SSO endpoint、Access Entity ID or Issuer、Public key をコピーします。

Access policies で、既存のポリシーを追加するか、新しいポリシーを作成して、アプリケーションに接続できるユーザーを制御します。Access アプリケーションはデフォルトで拒否です。ユーザーは Allow ポリシーに一致してからアクセスが許可されます。
ユーザーの認証方法を設定します。
1. アプリケーションで有効にするアイデンティティプロバイダーを選択します。
2. （推奨）単一の IdP だけでアクセスを許可する場合は、Apply instant authentication をオンにします。エンドユーザーには Cloudflare Access のログインページは表示されません。代わりに、Cloudflare はユーザーを SSO ログインへ直接リダイレクトします。
3. （任意） Authenticate with Cloudflare One Client をオンにすると、ユーザーは Cloudflare One Client のセッションアイデンティティでアプリケーションに認証できます。
（任意）Additional settings を開き、アプリケーションの表示をカスタマイズします。
- App Launcher customization: App Launcher でのこのアプリケーションの表示方法を設定します。
- Custom block pages: アプリケーションへのアクセスを拒否されたときに、ユーザーへ表示する内容を選びます。
  - Cloudflare default: ログインページを再読み込みし、Cloudflare Access のロゴの下にブロックメッセージを表示します。既定のメッセージは That account does not have access です。カスタムメッセージを入力することもできます。
  - Redirect URL: 指定した Web サイトへリダイレクトします。
  - Custom page template: Cloudflare One でホストするカスタムブロックページを表示します。
Create を選択します。

3. SaaS アプリケーションで SSO を設定する

次に、ユーザーが Cloudflare Access 経由でログインするよう、SaaS アプリケーションを設定します。サードパーティの SAML SSO プロバイダーの設定手順は、SaaS アプリケーションのドキュメントを参照してください。Cloudflare One から次の値が必要です。

SSO endpoint
Access Entity ID or Issuer
Public key

このデータを SaaS アプリケーションに手動で入力するか、メタデータ XML ファイルをアップロードできます。メタデータは次の URL で入手できます: <SSO endpoint>/saml-metadata

SAML Response を検証する

SAML アイデンティティプロバイダーとして動作する場合、Cloudflare は SAML Response と SAML Assertion の両方に SHA-256 アルゴリズムで署名します。SaaS アプリケーションは、アップロードした Public key でこの署名を検証できます。

4. 統合をテストする

シークレットブラウザーウィンドウを開き、SaaS アプリケーションのログイン URL へアクセスします。Cloudflare Access のログイン画面へリダイレクトされ、アイデンティティプロバイダーでのサインインが求められます。

SAML 属性

SAML 属性は、認証成功後に Cloudflare Access が SAML SaaS アプリケーションと共有するユーザー ID の特性です。デフォルトでは、Cloudflare Access は次の属性（利用可能な場合）を SaaS アプリケーションへ渡します。

id - ユーザーの Access ID の UUID
name - ユーザーの氏名（例: John Doe）
email - ユーザーのメールアドレス
groups - アイデンティティプロバイダーのグループ所属

Access for SaaS では、追加の SAML 属性を加えたり、SaaS アプリケーションへ送る SAML ステートメントをカスタマイズしたりできます。特定の SAML 属性要件がある SaaS アプリケーションとも統合できます。

SAML 属性ステートメント

SaaS アプリケーションへ追加の SAML 属性を送るには、属性ごとに次のフィールドを設定します。

Name: SAML 属性名
SAML friendly name: （任意）SAML 属性の人が読める名前
Name format: SaaS アプリケーションが期待する Name 形式を指定します。
- Unspecified: （デフォルト）特定の形式は不要です。
- URI: urn:ietf:params:scim:schemas:core:2.0:User:userName や urn:oid:2.5.4.42 のような形式の名前です。
- Basic: userName のような通常の文字列です。
IdP claim: この SAML 属性に対応させるアイデンティティプロバイダーの値です。Cloudflare One の IdP 統合で設定した任意の SAML 属性または OIDC クレームを選択できます。
Required: 必須とマークされた属性が IdP から提供されない場合、Cloudflare は認証リクエストを失敗させ、エラーページを表示します。
Add per IdP claim: （任意）SaaS アプリケーションで複数のアイデンティティプロバイダーを有効にしている場合、IdP ごとに異なる属性マッピングを選べます。これらの値は親の IdP claim を上書きします。

JSONata 属性変換

Advanced settings > Transformation に、User Registry の ID のコピーを変更する JSONata ↗ スクリプトを入力できます。デフォルト値の設定、メールアドレスの除外、ユーザー名が任意の条件を満たすようにする、といった用途に使えます。Access は変更後のユーザー ID を SAML 属性として SaaS アプリケーションへ送ります。

これは Access applications API の saml_attribute_transform_jsonata フィールドに対応します。

たとえば、次の JSONata スクリプトはグループ名をリストにまとめ、ユーザーメールに対応する eduPersonPrincipalName フィールドを追加します。

$merge([$, {"groups": groups.name, 'eduPersonPrincipalName': email}])

JSONata 変換を適用する前のユーザー ID の例です。

{
  "account_id": "699d98642c564d2e855e9661899b7252",
  "amr": [
    "pwd"
  ],
  "auth_status": "NONE",
  "common_name": "",
  "device_id": "c1744f8b-faa1-48a4-9e5c-02ac921467fa",
  "device_sessions": {
    "49e653db-991e-11ee-af26-2243bf8c3428": {
      "last_authenticated": 1703004275
    }
  },
  "devicePosture": {
    "8534a230-e85e-4183-8964-a4b7dcf72986": {
      "rule_name": "Warp",
      "success": true,
      "type": "warp"
    }
  },
  "email": "[email protected]",
  "gateway_account_id": "bTSquyUGwLQjYJn8cI8S1h6M6wU",
  "geo": {
    "country": "US"
  },
  "groups": [
    {
      "id": "12fdf91a-fb23-41b3-995a-de2f72c61d0e",
      "name": "IdentityProtection-RiskyUser-RiskLevel-low"
    },
    {
      "id": "12348f47-8234-4860-a03f-c2a1513f267b",
      "name": "Global Administrator"
    },
    {
      "id": "11235980-87d7-4917-b0aa-74c01914c40e",
      "name": "Application Administrator"
    }
  ],
  "iat": 1659474397,
  "id": "OidHvkPt-I-13IBSnd77UJ8cHgsrUpjs3W6_4t6ES7M",
  "idp": {
    "id": "b08e8c0c-a75d-4b3f-8e7b-cd427b7c7b47",
    "type": "azureAD"
  }
}

例の JSONata スクリプトを適用した結果です。

{
  "account_id": "699d98642c564d2e855e9661899b7252",
  "amr": [
    "pwd"
  ],
  "auth_status": "NONE",
  "common_name": "",
  "device_id": "c1744f8b-faa1-48a4-9e5c-02ac921467fa",
  "device_sessions": {
    "49e653db-991e-11ee-af26-2243bf8c3428": {
      "last_authenticated": 1703004275
    }
  },
  "devicePosture": {
    "8534a230-e85e-4183-8964-a4b7dcf72986": {
      "rule_name": "Warp",
      "success": true,
      "type": "warp"
    }
  },
  "email": "[email protected]",
  "gateway_account_id": "bTSquyUGwLQjYJn8cI8S1h6M6wU",
  "geo": {
    "country": "US"
  },
  "groups": [
    "IdentityProtection-RiskyUser-RiskLevel-low",
    "Global Administrator",
    "Application Administrator"
  ],
  "iat": 1659474397,
  "id": "OidHvkPt-I-13IBSnd77UJ8cHgsrUpjs3W6_4t6ES7M",
  "idp": {
    "id": "b08e8c0c-a75d-4b3f-8e7b-cd427b7c7b47",
    "type": "azureAD"
  },
  "eduPersonPrincipalName": "[email protected]"
}

その他の JSONata 変換の用途は、次の例を参照してください。

groups 属性を削除する

次の JSONata スクリプトは groups SAML 属性を削除します。SaaS アプリケーションがユーザーのグループ情報を必要としない場合に便利です。

JSONata 式txt

$ ~> |$|{}, ['groups']|

JSONata 変換を適用した結果です。

{
  "account_id": "699d98642c564d2e855e9661899b7252",
  "amr": [
    "pwd"
  ],
  "auth_status": "NONE",
  "common_name": "",
  "device_id": "c1744f8b-faa1-48a4-9e5c-02ac921467fa",
  "device_sessions": {
    "49e653db-991e-11ee-af26-2243bf8c3428": {
      "last_authenticated": 1703004275
    }
  },
  "devicePosture": {
    "8534a230-e85e-4183-8964-a4b7dcf72986": {
      "rule_name": "Warp",
      "success": true,
      "type": "warp"
    }
  },
  "email": "[email protected]",
  "gateway_account_id": "bTSquyUGwLQjYJn8cI8S1h6M6wU",
  "geo": {
    "country": "US"
  },
  "iat": 1659474397,
  "id": "OidHvkPt-I-13IBSnd77UJ8cHgsrUpjs3W6_4t6ES7M",
  "idp": {
    "id": "b08e8c0c-a75d-4b3f-8e7b-cd427b7c7b47",
    "type": "azureAD"
  }
}

groups フィールドをリネームし、グループ ID を削除する

次の JSONata スクリプトは groups.name フィールドを name から group_name に変更し、groups.id フィールドを削除します。

JSONata 式txt

{
  "account_id": account_id,
  "amr": amr,
  "auth_status": auth_status,
  "common_name": common_name,
  "devicePosture": devicePosture,
  "device_id": device_id,
  "device_sessions": device_sessions,
  "email": email,
  "gateway_account_id": gateway_account_id,
  "geo": geo,
	"groups": $map($.groups, function($group) {
    {"group_name": $group.name}}),
  "iat": iat,
  "id": id,
  "idp": idp
}

JSONata 変換を適用した結果です。

{
  "account_id": "699d98642c564d2e855e9661899b7252",
  "amr": [
    "pwd"
  ],
  "auth_status": "NONE",
  "common_name": "",
  "devicePosture": {
    "8534a230-e85e-4183-8964-a4b7dcf72986": {
      "rule_name": "Warp",
      "success": true,
      "type": "warp"
    }
  },
  "device_id": "c1744f8b-faa1-48a4-9e5c-02ac921467fa",
  "device_sessions": {
    "49e653db-991e-11ee-af26-2210bf8c3428": {
      "last_authenticated": 1703004275
    }
  },
  "email": "[email protected]",
  "gateway_account_id": "bTSquyUGwLQjYJn8cI8S1h6M6wU",
  "geo": {
    "country": "US"
  },
  "groups": [
    {
      "group_name": "IdentityProtection-RiskyUser-RiskLevel-low"
    },
    {
      "group_name": "Global Administrator"
    },
    {
      "group_name": "Application Administrator"
    }
  ],
  "iat": 1659474397,
  "id": "OidHvkPt-I-13IBSnd77UJ8cHgsrUpjs3W6_4t6ES7M",
  "idp": {
    "id": "b08e8c0c-a75d-4b3f-8e7b-cd427b7c7b47",
    "type": "azureAD"
  }
}

名前でグループを絞り込む

次の JSONata スクリプトは、正規表現に一致するグループだけに絞り込みます。

JSONata 式txt

$merge([$, { "groups": $filter(groups, function($v) { $contains($v.name, /Administrator/) }) }])

JSONata 変換を適用した結果です。

{
  "account_id": "699d98642c564d2e855e9661899b7252",
  "amr": [
    "pwd"
  ],
  "auth_status": "NONE",
  "common_name": "",
  "device_id": "c1744f8b-faa1-48a4-9e5c-02ac921467fa",
  "device_sessions": {
    "49e653db-991e-11ee-af26-2243bf8c3428": {
      "last_authenticated": 1703004275
    }
  },
  "devicePosture": {
    "8534a230-e85e-4183-8964-a4b7dcf72986": {
      "rule_name": "Warp",
      "success": true,
      "type": "warp"
    }
  },
  "email": "[email protected]",
  "gateway_account_id": "bTSquyUGwLQjYJn8cI8S1h6M6wU",
  "geo": {
    "country": "US"
  },
  "groups": [
    {
      "id": "12348f47-8234-4860-a03f-c2a1513f267b",
      "name": "Global Administrator"
    },
    {
      "id": "11235980-87d7-4917-b0aa-74c01914c40e",
      "name": "Application Administrator"
    }
  ],
  "iat": 1659474397,
  "id": "OidHvkPt-I-13IBSnd77UJ8cHgsrUpjs3W6_4t6ES7M",
  "idp": {
    "id": "b08e8c0c-a75d-4b3f-8e7b-cd427b7c7b47",
    "type": "azureAD"
  }
}

NameID 変換

デフォルトでは、Access はユーザーのメールアドレスを SAML の NameID として送ります。一部の SaaS アプリケーションは、従業員 ID、変更したメールアドレス、レガシーシステムのユーザー名など、別の値を求めます。

SaaS アプリケーションの name_id_transform_jsonata フィールドを Access applications API で設定すると、NameID をカスタマイズできます。このフィールドは、ユーザー ID に対して評価され、単一の文字列を返す JSONata ↗ 式を受け付けます。結果は SAML アサーションのデフォルト NameID を置き換えます。

たとえば、ユーザーのメールに +sandbox サフィックスを付ける場合（同じ SaaS アプリの複数インスタンスを接続するときに便利です）:

API で NameID 変換を設定するbash

curl --request PUT \
https://api.cloudflare.com/client/v4/accounts/{account_id}/access/apps/{app_id} \
--header "Authorization: Bearer {api_token}" \
--header "Content-Type: application/json" \
--data '{
  "saas_app": {
    "auth_type": "saml",
    "name_id_transform_jsonata": "$substringBefore(email, '\''@'\'') & '\''+sandbox@'\'' & $substringAfter(email, '\''@'\'')"
  }
}'

メールが [email protected] のユーザーでは、この式は [email protected] という NameID を生成します。

従業員 ID を NameID として使う

従業員 ID などメール以外の属性を送るには、JSONata 式で属性名を直接参照します。その属性は、IdP から取得したユーザー ID に含まれている必要があります。

employee_id を NameID に設定するbash

curl --request PUT \
https://api.cloudflare.com/client/v4/accounts/{account_id}/access/apps/{app_id} \
--header "Authorization: Bearer {api_token}" \
--header "Content-Type: application/json" \
--data '{
  "saas_app": {
    "auth_type": "saml",
    "name_id_transform_jsonata": "employee_id"
  }
}'

ユーザー ID に "employee_id": "efgh5678" が含まれる場合、SAML アサーションで送られる NameID は efgh5678 になります。

NameID 変換を削除する

デフォルト動作（ユーザーのメールを NameID として送る）に戻すには、フィールドを空文字列に設定します。

NameID 変換を削除するbash

curl --request PUT \
https://api.cloudflare.com/client/v4/accounts/{account_id}/access/apps/{app_id} \
--header "Authorization: Bearer {api_token}" \
--header "Content-Type: application/json" \
--data '{
  "saas_app": {
    "auth_type": "saml",
    "name_id_transform_jsonata": ""
  }
}'