はじめに
先日、Laravel 12 から Breeze と Jetstream の代わりに Starter Kits がサポートされたということを知りました。Starter Kits では WorkOS が公式にサポートされ、WorkOS 経由の SSO が比較的簡単に導入できるようになっていました。
せっかくなので Laravel Breeze で作ったアプリを Starter Kits を利用して作り直し、認証を WorkOS に寄せて Entra ID で SSO ログインをしてみました。実際にやってみると、WorkOS 側で拒否されるドメインがあったり、Entra ID 側の設定でログインに失敗するといったことがあり、結構なハマりポイントが多かったです。
今回は、導入までにハマったポイントを中心に記録を残していきます。
WorkOS は、Google や Microsoft などのサービスを使ったソーシャルログインや SAML 認証で SSO を実現できる認証プロバイダーです。WorkOS を利用するには WorkOS アカウントが必要です。
準備
Laravelアプリケーション
laravel コマンドをあらかじめインストールしておきます。laravel new で新しい Laravel プロジェクトを対話形式で作成できます。このとき、認証プロバイダーを選択できるので WorkOS を選んでおきます。
┌ Which authentication provider do you prefer? ────────────────┐
│ ○ Laravel's built-in authentication │
│ › ● WorkOS (Requires WorkOS account) │
└──────────────────────────────────────────────────────────────┘WorkOS の API を利用するために .env も編集しておきます。各値は WorkOS のダッシュボードから確認できます。
WORKOS_CLIENT_ID=xxxx
WORKOS_API_KEY=xxxx
WORKOS_REDIRECT_URL="http://localhost:8000/authenticate"Entra ID側の準備とSAML接続
Entra ID 側で WorkOS と SAML 接続できるように設定をしておきます。手順はドキュメントの通りで大丈夫です。
ACS URL と SP Entity の場所が若干わかりづらいですが、Organizations から対応するものを選択して View connections ボタンを押下した先にあります (執筆当時)。
UI は度々変更になるようですので、見当たらなければ根気よく探す必要があります。
ハマったポイント
アプリケーションへのアクセス権がなくて拒否される (AADSTS50105)
アプリのログイン画面 (または AuthKit) でメールアドレスを入力して送信すると、以下のようなメッセージが表示されます。
AADSTS50105: Your administrator has configured the application HOGE SAML App ('xxxxx') to block users unless they are specifically granted ('assigned') access to the application. The signed in user 'foo@bar.example.com' is blocked because they are not a direct member of a group with access, nor had access directly assigned by an administrator. Please contact your administrator to assign access to this application.これは、ログインしようとしたユーザーに当該アプリケーションへのアクセスが許可されていないことに起因します。
Entra 管理センターまたは Azure ポータルからユーザーを追加することで解消ができるはずです。
ドメインの設定漏れでSign in画面がループする
WorkOS で SSO を利用するには、事前にドメインの検証と設定が必要です。この設定が漏れていると Sign in 画面から先に進めずループしてしまう挙動を示すことがあります。
ドメインの検証方法には、次の2つがあります。
- Self-serve Domain Verification
- Manual Domain Verification
詳しくは公式ドキュメントをご覧ください。
Manual Domain Verification を利用する場合、既に Entra ID などで所有が確認されたカスタムドメインを、WorkOS の設定に手動で追加します。
ここでは所有が確認できるドメインを入力するので、gmail.com や outlook.com などの public consumer domain を入力しようとすると拒否されます。
属性のマッピング不正でログインに失敗する
ログインに失敗すると、Notifications に以下のログが残る場合があります。
同様に Admin Email 宛に以下のようなメッセージも届いているかと思います。
Single Sign-On failed for XXXXXX
Your foo.example.com connection received invalid user attributes and failed to authenticate a user.
Why this might happen
The user attributes are misconfigured in Entra ID (Azure AD).
A single user is misconfigured in Entra ID (Azure AD). (Check the received attributes below).
How to fix this
Verify that attribute mapping is correct in the Entra ID (Azure AD) dashboard.このエラーは、idP (今回の場合 Entra ID) から返却される attribute が WorkOS 側で期待しているものと異なっていることを示しています。
WorkOS 側で期待している属性値と Entra ID 側から送っている属性がマッチしていることを確認します。
WorkOS 側で required となっている項目については、Entra ID 側で設定されていないとキー毎何も返さなくなるので、設定しておく必要があります。特に Starter Kits を利用する場合は姓名が必須になっているので注意が必要です。
また、姓名を漢字などのマルチバイト文字で登録すると何故か返って来ないという現象がありました (これについては未解決です)。
さいごに
本記事では、Laravel Starter Kit で WorkOS を利用し、Microsoft Entra ID と SAML SSO を組み合わせた際に直面した問題とその対処法をまとめました。これが実際のプロジェクトで導入しようとしている方々の助けになれば幸いです。
今回紹介したものは、WorkOS 特有のハマりポイントもありましたが、Entra ID や SAML の仕様で躓いた部分もありました。私自身が SAML への理解が浅いということが露呈した結果ではあります。精進します。
