シングルサインオンPHP構成

ヒント

構成情報を変更しても、構成キャッシュを再ロードしない限り、その構成情報がSwarmで使用されることはありません。構成キャッシュを再ロードすると、変更した構成情報がSwarmで強制的に使用されます。Swarm構成キャッシュを再ロードするには、admin ユーザまたはsuper ユーザでなくてはなりません。[ユーザID]ドロップダウンメニューに移動して[システム情報]を選択し、[キャッシュ情報]タブをクリックしてから[構成の再ロード]ボタンボタンをクリックします。

Helix認証サービス

重要

  • Helix認証サービスを使用するように設定されているHelixサーバでSwarmを使用するには、Swarm構成ファイルで、Swarm sso構成可能変数の値をoptionalまたはenabledに設定する必要があります。

  • Swarm 2021.1以降、sso_enabled構成可能変数は非推奨になりました(ただし、引き続き使用できます)。代わりに、より柔軟性の高いsso構成可能変数が導入されました。sso_enabled構成可能変数とsso構成可能変数の両方をp4構成ブロック内に指定した場合、Swarmではsso構成可能変数が使用されます。

Helix認証サービスは、Swarmのサービスプロバイダ(SP)に対するSAML IDプロバイダ(IdP)として機能します。管理者がHelix認証サービスで設定したプロトコルを使用して、外部IdPによる認証機能が有効になります。

このセクションでは、Swarmconfig.phpファイル内で、Helix認証サービス用に設定されたHelixサーバを使用してSwarmの認証を有効にするSAML 2.0の設定方法について説明します。SWARM_ROOT/data/config.phpファイル内のSAML PHP構成ブロックを使用して、Swarmに対するHelix認証サービスとサービスプロバイダ(SP)の接続の詳細を設定します。これにより、SwarmからHelix認証サービスへの接続と、Helix認証サービスからSwarmへの接続が可能になり、IdPログインプロセスを使用してSwarmにログインできるようになります。

SwarmをHelix認証サービス用に設定する

Swarm SAML 2.0の設定

このセクションでは、SwarmがHelix認証サービス用に有効化されたHelixサーバに接続できるようにするために入力する必要がある最低限必要な設定について説明します。samlの構成ブロックをSWARM_ROOT/data/config.phpファイルの最後に追加する必要があります。以下に例を示します。

ヒント

saml構成ブロックの内容は、使用中のSAMLの構成に応じて異なります。Helixサーバ SAMLの構成で必要な場合、他の構成可能変数をSAML PHPブロックに追加することができます。例えば、SP (Swarm)用のx509certとprivateKeyがcertsフォルダ内に存在する場合、samlブロックのsp項目でx509certとprivateKeyを指定する必要はありません。ただし、samlブロックのidp項目で、必ずidpのx509certを指定する必要があります。

SAML 2.0の概要については、https://github.com/onelogin/php-samlを参照してください。

SAML PHPの構成例、構成可能変数について詳しくは、以下の下線が付いているリンクに従います。

警告

以下に示す例の構文は正しいものですが、動作しない構成値も含まれています。samlブロックをテスト環境や本番環境で使用する前に、SAMLの構成に合わせて、現在の構成を適切に調整してください。

<?php
    // the saml block should be a peer of 'p4' located at the end of 
    // the Swarm configuration block in the config.php file
    'saml' => array(
        // If your Helix Server trigger expects a message header so that it can 
        // easily recognize SAML response messages, add the header text
        'header' => 'saml-response: ', // leave empty for no message header ''
        // Service Provider Data that we are deploying
        'sp' => array(
            // Identifier of the SP entity  (must be a URI)
            'entityId' => '<urn:my_swarm:sp>',
            // Specifies info about where and how the AuthnResponse message MUST be
            // returned to the requester, in this case our SP.
            'assertionConsumerService' => array(
                // URL Location where the Response from the IdP will be returned, this is the Swarm URL and port
                'url' => '<[http[s]://]<swarm-host>[:<port>]>',
            ),

            // Usually x509cert and privateKey of the SP (Swarm) are provided by files placed in
            // the certs folder. These files must be named sp.crt and sp.key. 
            // Optional: you can also provide them with the following parameters
            'x509cert' => '<my_sp_swarm_full_cert_string_including_the_BEGIN_CERTIFICATE_and_END_CERTIFICATE_parts>',
            'privateKey' => '<my_sp_swarm_private_key>',
        ),
        // Identity Provider Data that we want to connect to with our SP (Swarm)
        'idp' => array(
            // Identifier of the IdP entity  (must be a URI)
            'entityId' => '<my_entityid_provided_by_the_idp>',
            // SSO endpoint info of the IdP. (Authentication Request protocol)
            'singleSignOnService' => array(
                // URL Target of the IdP where the SP (Swarm) will send the Authentication Request Message
                'url' => '<full_idp_URL_path_to_send_authentication_request_message_to>',
            ),

            // The x509cert of the idp is provided by the following x509cert parameter.
            // Do not add the privateKey parameter. 
            // You must use the x509cert parameter, you must not add the cert file the certs folder. 
            'x509cert' => '<my_idp_full_cert_string_including_the_BEGIN_CERTIFICATE_and_END_CERTIFICATE_parts>',
        ),
    ),
注意

Swarmの構成ファイルには、PHPの標準的な終了タグである「?>」は含まれていません。Swarmの出力に不要な空白が挿入されるのを防ぐため、意図的にこの終了タグを除外しています。意図しない空白が挿入されると、HTTPヘッダを制御するSwarmの機能が正しく動作しなくなります。空白が入った結果として生じる動作やエラーメッセージはしばしば誤解を招くことがあるため、意図しない空白に起因するデバックの問題は難しい場合があります。

ヘッダ

Helixサーバトリガの一部では、SAMLの応答メッセージにヘッダ(プレフィックス)を追加することによって、Helixサーバが簡単にメッセージを特定できるようにする必要があります。ヘッダはheaderの値に設定されています。

ヘッダが不要な場合は、headerを空「''」に設定します。

<?php
    'saml' => array(
        // If your Helix Server trigger expects a message header so that it can 
        // easily recognize SAML response messages, add the header text
        'header' => 'saml-response: ', // leave empty for no message header ''
    ),

デフォルト値は'saml-response: 'です。

sp

sp(サービスプロバイダ)セクションでは、IdP(IDプロバイダ)のコールバック先と識別子情報について定義します。これにより、IdPはSwarmへの接続方法を識別します。

  • entityId: IdPが認識するSwarmの識別子です。エンティティIDを設定して、同じ値をIdPの構成ツールで使用します。SwarmがIdPに接続すると、エンティティIDを使用してユーザの接続を検証します。これはURIである必要があります。
  • assertionConsumerService url: SwarmのURLとポート番号を入力します。これによって、SwarmインスタンスがIdPの応答先のURLとして設定されます。ポート番号を入力しない場合、ポート番号80が使用されます。
    • 重要

    localhostをurlに使用しないでください。

  • x509certおよびprivateKey: Swarmインスタンスのセキュリティ接続の詳細を入力します。 
<?php
    'saml' => array(
        // Service Provider Data that we are deploying
        'sp' => array(
            // Identifier of the SP entity  (must be a URI)
            'entityId' => '<urn:my_swarm:sp>',
            // Specifies info about where and how the AuthnResponse message MUST be
            // returned to the requester, in this case our SP.
            'assertionConsumerService' => array(
                // URL Location where the Response from the IdP will be returned, this is the Swarm URL and port
                'url' => '<[http[s]://]<swarm-host>[:<port>]>',
            ),

            // Usually x509cert and privateKey of the SP (Swarm) are provided by files placed in
            // the certs folder. These files must be named sp.crt and sp.key. 
            // Optional: you can also provide them with the following parameters
            'x509cert' => '<my_sp_swarm_full_cert_string_including_the_BEGIN_CERTIFICATE_and_END_CERTIFICATE_parts>',
            'privateKey' => '<my_sp_swarm_private_key>',
        ),
    ),

idp

Helix認証サービスは、Swarmのサービスプロバイダ(SP)に対するSAML IDプロバイダ(IdP)として機能します。管理者がHelix認証サービス用に選択したプロトコルを使用して、外部IdPによる認証機能が有効になります。idp (IDプロバイダ)セクションでは、Helix認証サービスの接続とセキュリティ情報について定義します。これにより、SwarmはIdPへの接続方法を識別します。

  • entityId: Helix認証サービスで設定されているエンティティIDを入力します。これにより、SwarmがHelix認証サービスに接続できるようになります。これはURIである必要があります。
  • singleSignOnService url: Swarmが認証要求を送る先となるURLを入力します。このURLは、Helix認証サービスで設定されています。
  • x509cert: Helix認証サービスのセキュリティ接続証明書を入力します。 
<?php
    'saml' => array(
        //  Identity Provider Data that we want to connect to with our SP (Swarm)
        'idp' => array(
            // Identifier of the IdP entity  (must be a URI)
            'entityId' => '<my_entityid_provided_by_the_idp>',
            // SSO endpoint info of the IdP. (Authentication Request protocol)
            'singleSignOnService' => array(
                // URL Target of the IdP where the SP (Swarm) will send the Authentication Request Message
                'url' => '<full_idp_URL_path_to_send_authentication_request_message_to>',
            ),

            // The x509cert of the idp is provided by the following x509cert parameter.
            // Do not add the privateKey parameter. 
            // You must use the x509cert parameter, you must not add the cert file the certs folder. 
            'x509cert' => '<my_idp_full_cert_string_including_the_BEGIN_CERTIFICATE_and_END_CERTIFICATE_parts>',
        ),
    ),