SAML 2.0 認証 saml-2-0-authentication

任意の SAML 2.0 互換 IDP に対して（AEM オーサー以外の）エンドユーザーを設定し、認証する方法について説明します。

SAML for AEM as a Cloud Service とは

AEM パブリッシュ（またはプレビュー）との SAML 2.0 統合により、AEM ベースの Web エクスペリエンスのエンドユーザーは、アドビ以外の IDP（ID プロバイダー）に対して認証し、指定された承認済みユーザーとして AEM にアクセスできます。

設定の手順

このビデオでは、AEM as a Cloud Service のパブリッシュサービスとの SAML 2.0 統合の設定、および Okta を IDP として使用する方法について説明します。

前提条件

SAML 2.0 認証を設定する場合は、次の操作が必要です。

SAML 2.0 は、AEM パブリッシュまたはプレビューに対するユーザーの認証にのみサポートされます。 IDP を使用して AEM オーサーの認証を管理するには、IDP を Adobe IMS と統合します。

AEM に IDP 公開証明書をインストールする

IDP の公開証明書が AEM グローバルトラストストアに追加され、IDP から送信される SAML アサーションが有効であることを検証するために使用されます。

Global Trust Store は、AEM オーサー上で IDP の公開証明書を使用して設定されますが、SAML は AEM パブリッシュでのみ使用されるので、AEM パブリッシュで IDP 公開証明書にアクセスできるようにするには、グローバルトラストストアを AEM パブリッシュにレプリケートする必要があります。

認証サービスキーストアの作成 authentication-service-keystore

認証サービスのキーストアの作成が必要なのは、SAML 2.0 認証ハンドラーの OSGi 設定プロパティ handleLogoutが true に設定されている場合か、AuthnRequest 署名／SAML アサーション暗号化が必要な場合です。

AEM の 公開鍵と秘密鍵のペアをインストールする install-aem-public-private-key-pair

AEM 公開鍵と秘密鍵のペアのインストールはオプションです

AEM パブリッシュは、（IDP に対して）AuthnRequest に署名し、（AEM に対して）SAML アサーションを暗号化するように設定できます。これは、AEM パブリッシュに秘密鍵を提供し、これが IDP への公開鍵と一致することで実現されます。

AuthnRequest 署名と SAML アサーション暗号化は両方ともオプションですが、SAML 2.0 認証ハンドラーの OSGi 設定プロパティuseEncryptionを使用して有効になっています。両方とも使用するか両方とも使用しないかを選択できます。

SAML 2.0 認証ハンドラーの設定 configure-saml-2-0-authentication-handler

AEM の SAML 設定は、Adobe Granite SAML 2.0 Authentication Handler の OSGi 設定により行われます。
設定は OSGi ファクトリ設定です。つまり、1 つの AEM as a Cloud Service パブリッシュサービスに、リポジトリの個別のリソースツリーをカバーする複数の SAML 設定がある場合があります。これは、マルチサイト AEM のデプロイメントに役立ちます。

環境ごとの OSGi 設定（config.publish.dev、config.publish.stage および config.publish.prod）は、SAML 設定が環境によって異なる場合に、特定の属性を使用して定義できます。

暗号化を使用

AuthnRequest と SAML アサーションを暗号化する場合、プロパティとして useEncryption、spPrivateKeyAlias、keyStorePassword の 3 つが必要です。keyStorePassword はパスワードを含むので、その値は OSGi 設定ファイルに保存してはならず、秘密の設定値を使って挿入する必要があります。

リファラーフィルターの設定

SAML 認証プロセスにおいて、IDP は AEM パブリッシュの .../saml_login エンドポイントに対してクライアントサイドの HTTP POST を開始します。IDP と AEM パブリッシュが異なる接触チャネルに存在する場合、AEM パブリッシュの​ リファラーフィルター ​は、OSGi 設定を介して IDP の接触チャネルからの HTTP POST を許可するように設定されます。

AEM パブリッシュは、1 つのリファラーフィルター設定をサポートしているので、SAML 設定要件と既存の設定を結合します。

環境ごとの OSGi 設定（config.publish.dev、config.publish.stage および config.publish.prod）は、allow.hosts（または allow.hosts.regex）が環境間で異なる場合、特定の属性で定義できます。

クロスオリジンリソース共有（CORS）の設定

SAML 認証プロセスにおいて、IDP は AEM パブリッシュの .../saml_login エンドポイントに対してクライアントサイドの HTTP POST を開始します。IDP と AEM パブリッシュが異なるホストやドメインに存在する場合、AEM パブリッシュの​ クロスオリジンリソース共有（CORS） ​は、IDP のホストまたはドメインからの HTTP POST を許可するように設定されている必要があります。

この HTTP POST リクエストの Origin ヘッダーの値は通常、AEM パブリッシュホストとは異なるので、CORS 設定が必要です。

ローカル AEM SDK（localhost:4503）で SAML 認証をテストする場合、IDP は Origin ヘッダーを null に設定する場合があります。その場合は、alloworigin リストに "null" を追加します。

{
    "alloworigin": [
        "$[env:SAML_IDP_ORIGIN;default=https://dev-1234567890.okta.com]",
        "null"
    ],
    "allowedpaths": [
        ".*/saml_login"
    ],
    "supportedmethods": [
        "POST"
    ]
}

環境ごとの OSGi 設定（config.publish.dev、config.publish.stageおよび config.publish.prod）は、alloworigin と allowedpaths が環境ごとに異なる場合、特定の属性で定義することができます。

AEM Dispatcher の設定による SAML HTTP POST の許可

IDP への認証に成功すると、IDP は HTTP POST を調整して AEM の登録済み /saml_login エンドポイント（IDP に設定済み）に返します。この /saml_login への HTTP POSTは、Dispatcher でデフォルトでブロックされるので、次の Dispatcher ルールを使用して明示的に許可する必要があります。

...

# Allow SAML HTTP POST to ../saml_login end points
/0190 { /type "allow" /method "POST" /url "*/saml_login" }

Apache web サーバーで URL の書き換えが設定されている場合（dispatcher/src/conf.d/rewrites/rewrite.rules）、.../saml_login エンドポイントへのリクエストが誤ってマングリングされないようにします。

動的グループメンバーシップ

動的グループメンバーシップは、グループの評価とプロビジョニングのパフォーマンスを向上させる Apache Jackrabbit Oak の機能です。この節では、この機能が有効な場合のユーザーとグループの保存方法、および SAML 認証ハンドラーの設定を変更して新しい環境または既存の環境に対して有効にする方法について説明します。

新しい環境で SAML ユーザーの動的グループメンバーシップを有効にする方法

新しい AEM as a Cloud Service 環境でのグループ評価パフォーマンスを大幅に向上させるには、新しい環境での動的グループメンバーシップ機能のアクティベーションをお勧めします。
また、これは、データ同期をアクティブ化する際にも必要な手順です。詳しくは、こちらを参照してください。
これを行うには、OSGI 設定ファイルに次のプロパティを追加します。

/apps/example/osgiconfig/config.publish/com.adobe.granite.auth.saml.SamlAuthenticationHandler~example.cfg.json

この設定では、ユーザーとグループは Oak 外部ユーザーとして作成されます。AEM では、外部ユーザーとグループには、[user name];[idp] または [group name];[idp] で構成されるデフォルトの rep:principalName があります。
アクセス制御リスト（ACL）は、ユーザーまたはグループの PrincipalName に関連付けられます。
以前に identitySyncType を指定していなかったか、default に設定した既存のデプロイメントにこの設定をデプロイすると、新しいユーザーとグループが作成され、これらの新しいユーザーとグループに ACL を適用する必要があります。外部グループにローカルユーザーを含めることはできません。Repoinit は、ユーザーがログインを実行する際にのみ作成される場合でも、SAML 外部グループの ACL の作成に使用できます。
ACL でのこのリファクタリングを回避することを目的に、標準の移行機能が実装されました。

動的グループメンバーシップを使用してローカルグループと外部グループにメンバーシップを保存する方法

ローカルグループでは、グループメンバーは oak 属性 rep:members に保存されます。属性には、グループのすべてのメンバーの UID のリストが含まれます。詳しくは、こちらを参照してください。
例：

{
  "jcr:primaryType": "rep:Group",
  "rep:principalName": "operators",
  "rep:managedByIdp": "SAML",
  "rep:members": [
    "635afa1c-beeb-3262-83c4-38ea31e5549e",
    "5e496093-feb6-37e9-a2a1-7c87b1cec4b0",
    ...
  ],
   ...
}

動的グループメンバーシップを持つ外部グループでは、グループエントリにメンバーが保存されません。
代わりに、グループメンバーシップがユーザーエントリに保存されます。追加のドキュメントについて詳しくは、こちらを参照してください。例えば、次はグループの OAK ノードです。

{
  "jcr:primaryType": "rep:Group",
  "jcr:mixinTypes": [
    "rep:AccessControllable"
  ],
  "jcr:createdBy": "",
  "jcr:created": "Tue Jul 16 2024 08:58:47 GMT+0000",
  "rep:principalName": "GROUP_1;aem-saml-idp-1",
  "rep:lastSynced": "Tue Jul 16 2024 08:58:47 GMT+0000",
  "jcr:uuid": "d9c6af8a-35c0-3064-899a-59af55455cd0",
  "rep:externalId": "GROUP_1;aem-saml-idp-1",
  "rep:authorizableId": "GROUP_1;aem-saml-idp-1"
}

そのグループのユーザーメンバーのノードは、次のとおりです。

{
  "jcr:primaryType": "rep:User",
  "jcr:mixinTypes": [
    "rep:AccessControllable"
  ],
  "surname": "Test",
  "rep:principalName": "testUser",
  "rep:externalId": "test;aem-saml-idp-1",
  "rep:authorizableId": "test",
  "rep:externalPrincipalNames": [
    "projects-users;aem-saml-idp-1",
    "GROUP_2;aem-saml-idp-1",
    "GROUP_1;aem-saml-idp-1",
    "operators;aem-saml-idp-1"
  ],
  ...
}

既存の環境で SAML ユーザーの動的グループメンバーシップを有効にする方法

前の節で説明したように、外部ユーザーとグループの形式は、ローカルユーザーとグループに使用される形式とは少し異なります。外部グループに新しい ACL を定義して新しい外部ユーザーをプロビジョニングすることも、以下に説明するように移行ツールを使用することもできます。

外部ユーザーを含む既存の環境の動的グループメンバーシップの有効化

SAML 認証ハンドラーは、次のプロパティが指定されている場合に外部ユーザーを作成します："identitySyncType": "idp"。この場合、このプロパティを "identitySyncType": "idp_dynamic" に変更することで、動的グループメンバーシップを有効にすることができます。移行は必要ありません。

ローカルユーザーを含む既存の環境の動的グループメンバーシップへの自動移行

SAML 認証ハンドラーは、次のプロパティが指定されている場合にローカルユーザーを作成します："identitySyncType": "default"。これは、プロパティを指定しない場合のデフォルト値でもあります。この節では、自動移行手順で実行される手順について説明します。

この移行を有効にする場合、ユーザー認証中に実行され、次の手順で構成されます。

例えば、移行前に user1 がローカルユーザーで、ローカルグループ group1 のメンバーである場合、移行後に次の変更が行われます。
user1 は、外部ユーザーになります。属性 rep:externalId がプロファイルに追加されます。
user1 は、外部グループ group1;idp のメンバーになります。
user1 は、ローカルグループ group1 の直接メンバーではなくなりました。
group1;idp は、ローカルグループ group1 のメンバーです。
その後、user1 は、継承を通じてローカルグループ group1 のメンバーになります。

外部グループのグループメンバーシップは、ユーザープロファイルのプロパティ rep:externalPrincipalNames に保存されます。

動的グループメンバーシップへの自動移行の設定方法

{
  "idpIdentifier": "<value of IDP Identifier (idpIdentifier)" property from the "com.adobe.granite.auth.saml.SamlAuthenticationHandler" configuration to be migrated>"
}

複数の SAML 設定を移行するには、com.adobe.granite.auth.saml.migration.SamlDynamicGroupMembershipMigration の複数の OSGi ファクトリ設定を作成し、それぞれ移行する idpIdentifier を指定する必要があります。

SAML 設定のデプロイ

OSGi 設定は、Git にコミットし、Cloud Manager を使用して AEM as a Cloud Service にデプロイする必要があります。

$ git remote -v
adobe   https://git.cloudmanager.adobe.com/myOrg/myCloudManagerGit/ (fetch)
adobe   https://git.cloudmanager.adobe.com/myOrg/myCloudManagerGit/ (push)
$ git add .
$ git commit -m "SAML 2.0 configurations"
$ git push adobe saml-auth:develop

フルスタックデプロイメントパイプラインを使用して、ターゲットの Cloud Manager Git ブランチ（この例では develop）をデプロイします。

SAML 認証の呼び出し

SAML 認証フローは、特別に作成されたリンクまたはボタンを作成して、AEM サイトの web ページから呼び出すことができます。以下に説明するパラメーターは、必要に応じてプログラムで設定できます。例えば、ログインボタンでは、ボタンのコンテキストに基づいて、SAML 認証が成功した際にユーザーが移動する場所である saml_request_path を様々な AEM ページに設定できます。

SAML 使用時のセキュリティ保護されたキャッシュ

AEM パブリッシュインスタンスでは、通常、ほとんどのページがキャッシュされます。ただし、SAML で保護されたパスの場合は、キャッシュを無効にするか、auth_checker 設定を使用してセキュリティ保護されたキャッシュを有効にする必要があります。詳しくは、こちらに記載されている詳細を参照してください。

auth_checker を有効にせずに保護されたパスをキャッシュすると、予期しない動作が発生する場合があります。

GET リクエスト

SAML 認証は、次の形式で HTTP GET リクエストを作成して呼び出すことができます。

HTTP GET /system/sling/login

次のクエリパラメーターを指定します。

例えば、この HTML リンクは SAML ログインフローをトリガーし、成功するとユーザーを /content/wknd/us/en/protected/page.html に移動します。これらのクエリパラメーターは、必要に応じてプログラムで設定できます。

<a href="/system/sling/login?resource=/content/wknd&saml_request_path=/content/wknd/us/en/protected/page.html">
    Log in using SAML
</a>

POST リクエスト

SAML 認証は、次の形式で HTTP POST リクエストを作成して呼び出すことができます。

HTTP POST /system/sling/login

次のフォームデータを指定します。

例えば、この HTML ボタンは HTTP POST を使用して SAML ログインフローをトリガーし、成功するとユーザーを /content/wknd/us/en/protected/page.html に移動します。これらのフォームデータパラメーターは、必要に応じてプログラムで設定できます。

<form action="/system/sling/login" method="POST">
    <input type="hidden" name="resource" value="/content/wknd">
    <input type="hidden" name="saml_request_path" value="/content/wknd/us/en/protected/page.html">
    <input type="submit" value="Log in using SAML">
</form>

Dispatcher 設定

HTTP GET メソッドと POST メソッドはどちらも AEM の /system/sling/login エンドポイントへのクライアントアクセスを必要とするので、AEM Dispatcher 経由で許可する必要があります。

GET または POST が使用されているかどうかに基づいて、必要な URL パターンを許可します。

# Allow GET-based SAML authentication invocation
/0191 { /type "allow" /method "GET" /url "/system/sling/login" /query "*" }

# Allow POST-based SAML authentication invocation
/0192 { /type "allow" /method "POST" /url "/system/sling/login" }