技術資料

Microsoft Entra IDとPHPでSAML認証を実装していると、認証自体は成功しているのに、PHPアプリケーションでユーザーの情報を取得できないことがあります。

このような場合は、Microsoft Entra IDにユーザー属性が登録されていることだけでなく、その属性がSAMLResponseへクレームとして出力されているか、そしてPHP側で実際のクレーム名を使って取得しているかを確認する必要があります。

今回は、Microsoft Entra IDの「属性とクレーム」で設定したユーザー属性を、onelogin/php-samlを利用したPHPアプリケーションで取得する方法を整理します。クレーム名はPHP側で分かりやすい名前へ明示的に設定し、SAMLResponseの内容と対応付けて確認します。

前提

今回の構成は次の通りです。

• PHPアプリケーション
• onelogin/php-saml
• Microsoft Entra IDをIdP(Identity Provider)として利用
• PHPアプリケーションをSP(Service Provider)として利用
• 認証フローは動作し、認証後の属性取得を確認する

PHPアプリケーションへのSAML認証の導入方法は、onelogin/php-samlで実現するPHP SAML認証で紹介しています。また、ログインできない場合の全体的な切り分けは、PHPのSAML認証でログインできないときの切り分けを参照してください。

ユーザー属性とSAMLクレームの関係

Microsoft Entra IDのユーザープロパティと、SAMLResponseに含まれるクレームは、同じものとして扱わないようにします。

「属性とクレーム」では、ユーザープロパティをクレームのソースとして指定します。そのうえで、SAMLResponseへ出力するクレーム名を設定します。PHP側では、SAMLResponseに出力されたクレーム名がonelogin/php-samlの属性配列のキーになります。

今回は、Microsoft Entra IDのユーザープロパティと「属性とクレーム」設定対応表を参考に、次のような対応で設定します。

ここで設定するクレーム名は説明用の例です。Microsoft Entra IDではクレーム名にURI形式を使うこともできるため、実際には保存後の設定とSAMLResponseのAttribute Nameを確認してください。

また、ユーザーを識別する値と、画面に表示する値は分けて考えます。表示名は変更される可能性があるため、ユーザー識別に使う場合は、ユーザープリンシパル名やオブジェクトIDなど、アプリケーションの要件に合った値を選びます。

Microsoft Entra IDで属性とクレームを設定する

まず、Microsoft Entra管理センターで対象のエンタープライズアプリケーションを開きます。

1. 「エンタープライズ アプリケーション」から対象のアプリケーションを開く。
2. 「シングル サインオン」を開く。
3. 「属性とクレーム」の編集画面を開く。
4. 「新しいクレームの追加」からクレームを追加する。

例えば、表示名を追加する場合は、クレーム名にdisplayNameを入力し、ソース属性としてuser.displaynameを選択します。

同じ手順で、次のクレームを追加します。

Name: displayName
Source attribute: user.displayname

Name: userPrincipalName
Source attribute: user.userprincipalname

Name: objectId
Source attribute: user.objectid

Name: department
Source attribute: user.department

Name: employeeId
Source attribute: user.employeeid

ソース属性にユーザーの値が登録されていない場合、そのクレームがSAMLResponseへ出力されないことがあります。特に部署や従業員IDは、ユーザーごとに値が入力されているかを確認します。

NameIDの設定を確認する

NameIDは、追加した属性クレームとは別に、SAMLのSubject内へ出力されるユーザー識別子です。「属性とクレーム」のName identifierの設定で、ソース属性と形式を確認します。

例えば、検証環境でユーザープリンシパル名をNameIDへ設定する場合は、Name identifierのソースとしてuser.userprincipalnameを選択します。ただし、NameIDを本番環境のユーザー識別子として利用するかどうかは、値が変更される可能性やアプリケーションの要件を確認して決めてください。

NameIDの形式をSAMLRequest側から指定している場合は、Microsoft Entra IDがその指定を考慮して応答します。設定画面の形式と、実際のSAMLResponseに出力された形式が一致しているかも確認します。

SAMLResponseで出力された属性を確認する

設定を保存したら、SAML認証を実行してSAMLResponseを確認します。SAML Chrome Panelなど、ローカル環境で通信内容を確認できる手段を利用します。

説明用に一部を抜き出すと、SAMLResponseは次のような構造になります。

<saml:Subject>
    <saml:NameID>user@example.test</saml:NameID>
</saml:Subject>
<saml:AttributeStatement>
    <saml:Attribute Name="displayName">
        <saml:AttributeValue>テストユーザー</saml:AttributeValue>
    </saml:Attribute>
    <saml:Attribute Name="userPrincipalName">
        <saml:AttributeValue>user@example.test</saml:AttributeValue>
    </saml:Attribute>
    <saml:Attribute Name="objectId">
        <saml:AttributeValue>00000000-0000-0000-0000-000000000000</saml:AttributeValue>
    </saml:Attribute>
</saml:AttributeStatement>

この例では、AttributeのNameが、先ほど設定したクレーム名になっています。実際のSAMLResponseでNameがURI形式になっている場合は、そのURI全体がPHP側の配列キーになります。

なお、SAMLResponseにはユーザー識別子、メールアドレス、テナント情報などが含まれる場合があります。確認用の画面キャプチャやログを作成するときは、実際の値をそのまま掲載せず、マスキングしてください。

onelogin/php-samlで属性を取得する

ACSへSAMLResponseが送信されたら、processResponse()でレスポンスを処理します。その後、認証状態を確認してからgetNameId()やgetAttributes()を呼び出します。

<?php

require __DIR__ . '/vendor/autoload.php';
session_start();

$settingsInfo = require __DIR__ . '/config/settings.php';
$auth = new OneLogin\Saml2\Auth($settingsInfo);

$auth->processResponse();

$errors = $auth->getErrors();
if (!empty($errors)) {
    error_log('[SAML] ' . implode(', ', $errors));
    error_log('[SAML] ' . $auth->getLastErrorReason());

    http_response_code(500);
    echo 'SAML認証の応答を検証できませんでした。';
    exit;
}

if (!$auth->isAuthenticated()) {
    http_response_code(401);
    echo '認証されていません。';
    exit;
}

$nameId = $auth->getNameId();
$attributes = $auth->getAttributes();

$getFirstAttribute = static function (array $attributes, string $name): ?string {
    $values = $attributes[$name] ?? [];

    if (!isset($values[0]) || !is_string($values[0])) {
        return null;
    }

    return $values[0];
};

$user = [
    'name_id' => $nameId,
    'display_name' => $getFirstAttribute($attributes, 'displayName'),
    'user_principal_name' => $getFirstAttribute($attributes, 'userPrincipalName'),
    'object_id' => $getFirstAttribute($attributes, 'objectId'),
    'department' => $getFirstAttribute($attributes, 'department'),
    'employee_id' => $getFirstAttribute($attributes, 'employeeId'),
];

$_SESSION['samlUserdata'] = $user;

getAttributes()で取得する属性値は、1つの値でも配列として返ります。そのため、$attributes['displayName']をそのまま表示するのではなく、値の存在を確認してから$values[0]を利用します。

上のコードでは、クレーム名をEntra ID側で明示的に設定したため、PHP側ではdisplayNameやobjectIdなどの名前で取得しています。SAMLResponseのAttribute NameをURI形式で設定した場合は、PHP側も次のように実際の名前へ合わせます。

$objectId = $attributes['http://schemas.microsoft.com/identity/claims/objectidentifier'][0] ?? null;

つまり、PHP側のキーを推測で決めるのではなく、Entra IDから発行された属性名とPHPコードの配列キーを一致させることが重要です。

属性を取得できない場合の確認ポイント

設定を変更したときは、設定画面、SAMLResponse、PHPコードの3か所を同じ表に記録すると、名前の不一致を見つけやすくなります。

Entra IDのソース属性: user.objectid
Entra IDのクレーム名: objectId
SAMLResponseのAttribute Name: objectId
PHPの配列キー: objectId

本番環境での注意点

開発中にgetAttributes()の結果を画面へ表示すると、ユーザー情報やテナント情報を意図せず公開する可能性があります。確認が終わったら、画面へのvar_dump()や詳細エラーの表示は削除してください。

ログへ記録する場合も、必要な項目だけに限定し、メールアドレス、ユーザーID、SAMLResponse全体、証明書情報などはマスキングまたは記録しないようにします。SAMLResponseをオンラインのデコードサービスへ貼り付ける方法も避けます。

ユーザー識別に表示名を使うと、名前の変更や同名ユーザーによって別の問題が起きる可能性があります。表示用にはdisplayNameを使い、内部的な識別にはアプリケーションの要件に合ったUPNやオブジェクトIDなどを使い分けます。

まとめ

Microsoft Entra IDのユーザー属性をPHPで取得するときは、ユーザープロパティ、SAMLのクレーム名、SAMLResponseのAttribute Name、PHPの配列キーを順番に対応付けます。

今回の例では、user.displaynameなどのソース属性に対して、displayNameやobjectIdなどのクレーム名を明示的に設定しました。これにより、PHP側のコードで扱う名前を分かりやすくできます。

ただし、PHP側のキーを推測で決めるのではなく、実際のSAMLResponseに含まれるNameIDとAttribute Nameを確認してください。認証が成功している場合でも、クレームの未設定、ユーザー属性の空欄、クレーム名の不一致によって、アプリケーションでユーザーを特定できないことがあります。

参考資料

• Microsoft Entra IDのユーザープロパティと「属性とクレーム」設定対応表
• Customize SAML token claims - Microsoft Learn
• Single sign-on SAML protocol - Microsoft Learn
• OneLogin PHP SAML Toolkit
• PHPのSAML認証でログインできないときの切り分け：Microsoft Entra IDとonelogin/php-samlを確認する
• SAML認証を行なうWebアプリケーションで通信内容を確認するChrome拡張機能