はじめに

先日、Laravel 12 から Breeze と Jetstream の代わりに Starter Kits がサポートされたということを知りました。Starter Kits では WorkOS が公式にサポートされ、WorkOS 経由の SSO が比較的簡単に導入できるようになっていました。

Starter Kits - Laravel - The PHP Framework For Web Artisans

Laravel is a PHP web application framework with expressive, elegant syntax. We’ve already laid the foundation — freeing ...

laravel.com

Starter Kits - Laravel 12.x - The PHP Framework For Web Artisans

Laravel is a PHP web application framework with expressive, elegant syntax. We’ve already laid the foundation — freeing ...

laravel.com

せっかくなので Laravel Breeze で作ったアプリを Starter Kits を利用して作り直し、認証を WorkOS に寄せて Entra ID で SSO ログインをしてみました。実際にやってみると、WorkOS 側で拒否されるドメインがあったり、Entra ID 側の設定でログインに失敗するといったことがあり、結構なハマりポイントが多かったです。

今回は、導入までにハマったポイントを中心に記録を残していきます。

WorkOS は、Google や Microsoft などのサービスを使ったソーシャルログインや SAML 認証で SSO を実現できる認証プロバイダーです。WorkOS を利用するには WorkOS アカウントが必要です。

WorkOS — Your app, Enterprise Ready.

Developer APIs/SDKs for Enterprise Ready features like Single Sign-On, Directory Sync, Audit Logging, and more. Get star...

workos.com

準備

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 接続できるように設定をしておきます。手順はドキュメントの通りで大丈夫です。

Entra ID SAML (formerly Azure AD) – Integrations – WorkOS Docs

Learn how to configure a connection Entra ID via SAML.

workos.com

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.

これは、ログインしようとしたユーザーに当該アプリケーションへのアクセスが許可されていないことに起因します。

エラー AADSTS50105 - サインインしているユーザーがアプリケーションのロールに割り当てされていません。

Microsoft Entra SSO を使用して SAML ベースの構成済みアプリにサインインするときにAADSTS50105 エラーが発生する問題について説明します。

learn.microsoft.com

Entra 管理センターまたは Azure ポータルからユーザーを追加することで解消ができるはずです。

ドメインの設定漏れでSign in画面がループする

WorkOS で SSO を利用するには、事前にドメインの検証と設定が必要です。この設定が漏れていると Sign in 画面から先に進めずループしてしまう挙動を示すことがあります。

ドメインの検証方法には、次の2つがあります。

• Self-serve Domain Verification
• Manual Domain Verification

詳しくは公式ドキュメントをご覧ください。

Domain Verification – AuthKit – WorkOS Docs

Verify organization domains for secure authentication and provisioning.

workos.com

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 側で期待しているものと異なっていることを示しています。

API Reference – WorkOS Docs

Code snippets and type definitions for the WorkOS client libraries.

workos.com

WorkOS 側で期待している属性値と Entra ID 側から送っている属性がマッチしていることを確認します。

WorkOS 側で required となっている項目については、Entra ID 側で設定されていないとキー毎何も返さなくなるので、設定しておく必要があります。特に Starter Kits を利用する場合は姓名が必須になっているので注意が必要です。

また、姓名を漢字などのマルチバイト文字で登録すると何故か返って来ないという現象がありました (これについては未解決です)。

さいごに

本記事では、Laravel Starter Kit で WorkOS を利用し、Microsoft Entra ID と SAML SSO を組み合わせた際に直面した問題とその対処法をまとめました。これが実際のプロジェクトで導入しようとしている方々の助けになれば幸いです。

今回紹介したものは、WorkOS 特有のハマりポイントもありましたが、Entra ID や SAML の仕様で躓いた部分もありました。私自身が SAML への理解が浅いということが露呈した結果ではあります。精進します。

ある分野の知識を体系的に学んで身につけるには、資格取得へ向けて勉強するのが良いというのを身を以て知っているので、とりあえず基礎的な AZ-900 を受験してきました。

Microsoft 認定: Azure Fundamentals - Certifications

クラウドの概念、Azure のコア サービス、および Azure の管理とガバナンスの機能とツールに関する基本的な知識を示します。

learn.microsoft.com

難易度的には基礎レベルなので、おそらく AWS Certified Cloud Practitioner と同程度と思っています。

どのような勉強をしたか

いつものように書籍を初手で購入したのですが、Microsoft に関連するものは公式の資料やトレーニング用コンテンツが豊富なので、それだけでも良かった気がします。

公式

Microsoft Learn

Microsoft Learn: キャリアの扉を開くスキルを身につける

ドキュメントやトレーニングによる技術スキルを獲得し、資格を取得し、コミュニティとつながる

learn.microsoft.com

各認定試験ごとにコースが用意されているようで、今回は AZ-900 受験に向けたコースを受講しました。もちろん無料です。

AZ-900T00-A コース: クラウド インフラストラクチャの概要 - Training

AZ-900T00-A コース: クラウド インフラストラクチャの概要

learn.microsoft.com

コースではサンドボックス内でのハンズオンが用意されています。手を動かしながら覚えられるのは地味に嬉しいですね。

AWS プロフェッショナル向け Azure

AWS プロフェッショナルのための Azure - Azure Architecture Center

Microsoft Azure プラットフォーム、アカウント、サービスの基本について説明します。 AWS プラットフォームと Azure プラットフォームの主な類似点と相違点について説明します。

learn.microsoft.com

既に AWS を利用している人向けの資料です。これはかなり利用しました。よく知らない Azure のサービス名が出てきたら、まずはこのページを開くぐらいのことはやっていました。

テキスト

全体像と用語がよくわかる! Microsoft Azure入門ガイド

Azure についての知識が0からのスタートだったので、全体を薄く解説している本を用意しようと思っていました。これと「AWS プロフェッショナル向け Azure」を行き来しながら読むと良いと思います。

まとめ

今まで受験した AWS 認定と比較してもかなり易しかったと思います。クラウドの基礎についての理解と Azure のメインのサービスを触ったことがあれば比較的簡単に合格できそうです。勉強時間はトータルで10時間程度だったと思います。

公式のコンテンツは AWS よりも日本語訳が進んでいるようですが、訳し方にムラがあるように思えます。「Azure Fundamentals」と「Azure の基礎」はどちらかに統一してもらいたかった。。

次も何か受けてみようと思います。

別解として SAS トークンを利用した認可もありますが、どうやら Entra ID が推奨みたいです。

Azure Blob Storage と JavaScript または TypeScript の概要 - Azure Storage

Azure Blob Storage で動作する JavaScript または TypeScript アプリケーションの開発を開始します。 この記事では、プロジェクトを設定し、Azure Blob Storage エンドポイントへのアクセス...

learn.microsoft.com

というわけで、今回は Microsoft Entra ID で認可して Blob Storage にファイルをアップロードするところまでやってみます。

構成

Microsoft Entra ID での認証自体は Remix で作った Web アプリを経由させ、Blob Storage へのアップロードはブラウザから直接行うようにします。登場人物をまとめた図は以下です。

Microsoft Entra 管理センター

Microsoft Entra 管理センターにて、アプリの登録を行います。アプリの登録ではアプリを一意に示す ID とアプリ自体の認証情報を作成します。

手順は以下を参考に。

クイック スタート - サンプル Web アプリでユーザーをサインインする - Microsoft identity platform

従業員テナントの従業員または外部テナントの顧客をサインインさせるサンプル Web アプリを構成する方法を示す Web アプリのクイック スタート

learn.microsoft.com

アプリの登録が完了すると、概要ペインからクライアント ID とテナント ID を取得できます。

今回は Web アプリ (機密クライアント) を選択したので、クライアントシークレットを生成します。

パブリックおよび機密のクライアント アプリ (MSAL) - Microsoft identity platform

Microsoft Authentication Library (MSAL) でのパブリック クライアント アプリケーションと機密クライアント アプリケーションについて説明します。

learn.microsoft.com

ログイン正常完了時にトークンを送る先をリダイレクト URI として追加します。

ストレージアカウント

Microsoft Entra ID で認証されたユーザーに Blob Storage の操作を許可します。これを実現するには、ロールベースのアクセス制御である Azure RBAC を利用します。

まずは Azure portal から任意のストレージアカウントとコンテナーを作成します。作成できたら、アクセス制御 (IAM) ペインから 追加タブ > ロールの割り当ての追加 を選択します。

データ共同作業者を選択して次へを選択します。

許可するユーザーを追加してレビューと割り当てを選択します。

Remix アプリ

Remix で作ったものは GitHub にアップしてます。

GitHub - ShotaroMuraoka/azure-entra-auth-blob-storage: Azure Blob Storage へのアクセスを Microsoft Entra ID で認可するアプリ

Azure Blob Storage へのアクセスを Microsoft Entra ID で認可するアプリ - ShotaroMuraoka/azure-entra-auth-blob-storage

github.com

以降はポイントのみを説明していきます。

ライブラリ

Remix で Microsoft Entra ID を使った認証と Blob Storage の操作を行うのに以下のライブラリを利用しています。

• remix-auth: 3.7.0
• remix-auth-microsoft: 2.0.1
• remix-auth-oauth2: 1.11.0
• @azure-storage-blob: 12.26.0

環境変数

.env を作成し、取得した ID とクライアントシークレット、ストレージアカウント名などを記載します。

ENTRA_CLIENT_ID={クライアントID}
ENTRA_CLIENT_SECRET={クライアントシークレット}
ENTRA_REDIRECT_URI=http://localhost:5173/auth/microsoft/callback
ENTRA_TENANT_ID={テナントID}
AZURE_STORAGE_ACCCOUNT={ストレージアカウント名}
AZURE_BLOB_CONTAINER={コンテナー名}

認証・認可

remix-auth-microsoft では MicrosoftStrategy が用意されているので、それを利用した Authenticator を作っています。

ここでは、scope に Azure Storage のアクセストークンの要求を追加しています。

let microsoftStrategy = new MicrosoftStrategy(
  {
    clientId: process.env.ENTRA_CLIENT_ID || "",
    clientSecret: process.env.ENTRA_CLIENT_SECRET || "",
    redirectUri: process.env.ENTRA_REDIRECT_URI || "",
    tenantId: process.env.ENTRA_TENANT_ID || "",
    scope: [
      "openid",
      "email",
      "profile",
      "https://storage.azure.com/user_impersonation",
    ], // optional
    prompt: "login", // optional
  },

取得したアクセストークンはセッション情報に書き出されるので、loader でフロントエンドに渡しています。

export async function loader({ request }: LoaderFunctionArgs) {
  const user = await authenticator.isAuthenticated(request);
  if (!user) {
    throw new Response("Unauthorized", { status: 403 });
  }

  const accessToken = user.accessToken;
  const storageAccount = process.env.AZURE_STORAGE_ACCCOUNT;
  const blobContainer = process.env.AZURE_BLOB_CONTAINER
  return { accessToken, storageAccount, blobContainer };
}

アクセストークンは @azure-storage-blob が提供するクライアントの生成に利用しています。

const blobServiceClient = createBlobServiceClient(
  accessToken,
  storageAccount,
);

const containerClient = blobServiceClient.getContainerClient(blobContainer);
const blockBlobClient = containerClient.getBlockBlobClient(file.name);

try {
  const response = await blockBlobClient.uploadBrowserData(file, {
    blobHTTPHeaders: { blobContentType: file.type },
  });
  console.log("upload succeeded", response.requestId);
  alert("ファイルアップロード完了");
} catch (error) {
  console.error("upload failed", error);
  alert("ファイルアップロード失敗");
}

動作確認

アプリを起動します。

# npm run dev 

ブラウザで http://localhost:5173/login にアクセスします。

ログインボタンを押下すると、Microsoft のサインイン画面にリダイレクトされます。

ストレージアカウントで許可したユーザーの認証情報を入力してログインに成功すると、ダッシュボード画面にリダイレクトします。初回ログイン時にのみ、Azure Storage へのアクセス許可を聞かれます。

任意のファイルを選択して Upload ボタンを押下します。ファイルのアップロードが成功するとメッセージが表示されます。

Blob コンテナーを見てみると、ファイルがアップロードされていることが確認できます。

おわりに

普段、Azure や Entra ID を利用する機会が無いので、難易度が高かったです。次は SAS トークンを試してみようと思います。