SAML 2.0 シングル サインオンとは何ですか?

SAML（Security Assertion Markup Language）は、別のプラットフォームでのセッションに基づいてユーザーをアプリケーションにログインさせるための標準です。このシングルサインオン（SSO）ログイン標準は、ユーザー名とパスワードを使ったログインに比べて、次のような大きな利点があります。

• 資格情報を入力する必要がない
• パスワードを覚えたり更新したりする必要はありません
• 弱いパスワードは使用しないでください

ほとんどの組織では、ユーザーがActive Directoryドメインまたはイントラネットにログインしているため、既にユーザーのIDを把握しています。この情報を使用して、当社のプラットフォームを含む他のアプリケーションにユーザーをログインさせることは理にかなっています。そのためのより洗練された方法の一つがSAMLの使用です。

どのように機能しますか?

SAML SSOは、XMLドキュメントのデジタル交換を通じて、ユーザーのIDをある場所（IDプロバイダー）から別の場所（サービスプロバイダー）に転送することを可能にします。プロセスは以下のとおりです。ユーザーがIDプロバイダーにログインし、リモートアプリケーションへのアクセスを試みると、アプリケーションはユーザーをIDプロバイダーにリダイレクトして認証を行います。その後、IDプロバイダーはユーザーの情報を含む署名済みXMLドキュメントをサービスプロバイダーに送信します。IDプロバイダーを既に把握しているサービスプロバイダーは、証明書のフィンガープリントを使用してドキュメントを検証し、ユーザーにアプリへのアクセスを許可します。

1. プラットフォームでSAML SSOを有効にする

SSOを設定できるのはプラットフォームの管理者ユーザーのみです。設定するには、以下の手順が必要です。

1. 左下にOrg設定があります
2. シングルサインオンタブに移動します
3. 「新しい構成を追加」をクリックします

その後、以下の詳細を入力する必要があります。

2. SSOパラメータの入力

必須構成パラメータ

これらは、お客様が選択したアイデンティティ プロバイダー (IdP) によって提供され、当社のプラットフォームに設定されます。

• IdP エンティティ ID: SAML エンティティの一意の名前（例: Azure）。この名前は SP レスポンス URL に追加され、IdP サービスプロバイダーに入力する必要があります。名前は英数字のみで、スペースを含めることはできません。検証チェックを通過するには、IdP から提供された名前を使用することが重要です。
• IdP SSO URL : ユーザーがログインのためにリダイレクトされる場所。これはクライアントのプラットフォーム URL である必要があります。
• 証明書: クライアントは、IdP プロバイダーからの証明書情報を英数字の文字列 (x.509 証明書) の形式で提供する必要があります。
• ベース URL : ホワイト ラベルが設定されていない限り、これはhttps://uberall.comになります。ホワイト ラベルが設定されている場合は、アクティブなホワイト ラベル ドメインのベース URL になります。

プラットフォーム提供の構成パラメータ

これらは IdP プロバイダーによって消費されます。

• メタデータ エンドポイント: SAML アサーションの対象ユーザーであるアプリケーション定義の一意の識別子。
• SSO URL または ACS エンドポイント: SAML アサーションが HTTP POST リクエストとともに送信され、サインインが成功した後にクライアントの IdP が認証されたユーザーをリダイレクトする場所。

ユーザーのSSOを有効にする

SSOの詳細を設定したら、ユーザーに対してSSOを有効化する必要があります。有効化すると、ユーザーはSSOでログインできるようになります。有効化するには、ユーザーのプロフィール（設定）に移動し、シングルサインオン機能を有効にしてください。

今後、そのユーザーはログイン ページから SSO を使用してログインできるようになります。

3. ジャストインタイム（JIT）プロビジョニングによるユーザーの作成と更新（オプション）

このプラットフォームでは、ユーザーをリアルタイムで作成または更新できます。これを実現するには、XMLアサーションに以下の属性が含まれるようにIdP設定を調整する必要があります。

必須項目

これらはユーザーを識別するために必要です

• FirstName –文字列– ユーザーの名
• LastName –文字列– ユーザーの姓
• メール –文字列– ユーザーのメールアドレス
• 識別子 –文字列– 社内システムに応じた安定した一意のユーザー識別子
• 役割 – ADMIN、ACCOUNT_MANAGER、BUSINESS_MANAGER、LOCATION_MANAGER のいずれか– Uberall ユーザーの役割。この役割が存在する場合、「追加ルール」セクションに記載されている役割の想定は適用されません。
  • ACCOUNT_MANAGERを設定する場合は、アサーションに1つまたは複数のビジネス（ビジネスの内部プラットフォームID）も渡す必要があります。
  • BUSINESS_MANAGERを設定する場合は、アサーションに1つまたは複数のビジネス（ビジネスの内部プラットフォームID）も渡す必要があります。
  • LOCATION_MANAGER を設定する場合は、アサーションで 1 つ以上のロケーション (ロケーションの内部プラットフォーム ID) または 1 つ以上のグループ (グループの内部プラットフォーム ID) も渡す必要があります。

オプションフィールド

これにより、ユーザーが意図したアクセス制御と製品モジュールの権限を取得できるようになります。

• 機能 – リスト – ユーザーに対して有効にする必要がある機能のリストです。機能の完全なリストについては、 Userモデルを確認してください。どの機能にアクセスできるかわからない場合は、プラットフォームにログインしてこの URLを開くと、機能の下にリストが表示されます。
• ロケーション –リスト– ロケーションの所有権を割り当てます。割り当てる必要があるUberallロケーションIDを渡す必要があります。LOCATION_MANAGERロールを持つユーザーに適用されます。
• ビジネス –リスト– ビジネスの所有権を割り当てます。割り当てるビジネスのUberallビジネスIDを渡す必要があります。ACCOUNT_MANAGERまたはBUSINESS_MANAGERロールを持つユーザーに適用されます。
• グループ –リスト– グループへの所属を割り当てます。ユーザーに関連付けられるUberallグループIDを渡す必要があります。
• WLIdentifier – 文字列 – SP内に複数のWLがある場合にユーザーに割り当てる必要があるUberallホワイトラベルID。指定されていない場合は、デフォルトのホワイトラベルIDが使用されます。

追加ルール（自動化）

これらを考慮すると、ワークフローでのユーザーの作成と自動化が容易になります。

• Businesses に複数の値を渡す → BUSINESS_MANAGER を作成し、ビジネスを割り当てます。
• Businesses に単一の値を渡すと、BUSINESS_MANAGER が作成され、ビジネスが割り当てられます。
• 場所またはグループの受け渡し → LOCATION_MANAGERを作成し、場所またはグループを割り当てます

クライアント開始ログイン

独自のプラットフォームから直接ログインを開始し、当社のログイン ページにアクセスする必要がない場合は、次のリンクをシステムに埋め込むことができます。

https://uberall.com/api/sso/saml/authenticate/ $salesPartnerId

• salesPartenrIdは、SSO URLとAudience URLの末尾にある数値です。
• ホワイトラベル設定の場合は、ベースURLも独自のドメインに切り替える必要があります。

トラブルシューティング

SSO設定を確実に成功させるために、送信されたSAMLResponse（XML）を検証するための専用のエンドポイントを開発しました。このエンドポイントは、誤りのあるフィールドや不足しているフィールドに関する詳細情報を提供します。

デバッグエンドポイントの使用

デバッグ エンドポイントを使用するには、アサーション コンシューマー サービス (ACS) URL を次の形式で設定する必要があります。

https://$base_url/api/sso/saml/verify/$sales_partner_id

この URL 形式により、ログイン時に送信されたアサーションを検証し、次のいずれかを示すメッセージを含む JSON 応答を返すことができます。

• 検証成功
• 不正確なフィールドや不足しているフィールドを示す、人間が読めるエラー

{
 "verificationId": "2d67a84d-b9b8-4498-b5a1-6f3772531caf",
 "success": true,
 "message": "Verification successful",
 "details": [
   {
     "key": "Email",
     "value": [
       "john.smith@uberall.com"
     ],
     "passed": true
   },
   {
     "key": "FirstName",
     "value": [
       "John"
     ],
     "passed": true
   },
   {
     "key": "LastName",
     "value": [
       "Smith"
     ],
     "passed": true
   },
   {
     "key": "Role",
     "value": [
       "admin"
     ],
     "passed": true
   },
   {
     "key": "Identifier",
     "value": [
       ""
     ],
     "passed": true
   },
   {
     "key": "Locations",
     "value": [
       ""
     ],
     "passed": true
   },
   {
     "key": "LocationIdentifiers",
     "passed": true
   },
   {
     "key": "Businesses",
     "value": [
       ""
     ],
     "passed": true
   },
   {
     "key": "Groups",
     "value": [
       ""
     ],
     "passed": true
   },
   {
     "key": "Features",
     "passed": true
   },
   {
     "key": "WlIdentifier",
     "passed": true
   }
 ],
 "userRequest": {
   "email": "john.smith@uberall.com",
   "firstname": "John",
   "lastname": "Smith",
   "role": "ADMIN",
   "managedBusinesses": [],
   "managedLocations": [],
   "managedLocationsIdentifiers": [],
   "locationGroups": [],
   "status": "VERIFIED",
   "salesPartner": {
     "id": 1926
   }
 }
}

{
 "verificationId": "3d9b2501-7d72-4012-8697-4cac0a1a2ae8",
 "success": false,
 "message": "SAML Attribute 'Role' is not one among [ADMIN, LOCATION_MANAGER, BUSINESS_MANAGER, BUSINESS_MANAGER_INBOX, ACCOUNT_MANAGER] and cannot be determined via Locations, Businesses, or Groups attributes. Received value for Attribute 'Role': ''",
 "details": [
   {
     "key": "Email",
     "value": [
       "john.smith@uberall.com"
     ],
     "passed": true
   },
   {
     "key": "FirstName",
     "value": [
       "John"
     ],
     "passed": true
   },
   {
     "key": "LastName",
     "value": [
       "Smith"
     ],
     "passed": true
   },
   {
     "key": "Role",
     "value": [
       ""
     ],
     "passed": true
   },
   {
     "key": "Identifier",
     "value": [
       ""
     ],
     "passed": true
   },
   {
     "key": "Locations",
     "value": [
       ""
     ],
     "passed": true
   },
   {
     "key": "LocationIdentifiers",
     "passed": true
   },
   {
     "key": "Businesses",
     "value": [
       ""
     ],
     "passed": true
   },
   {
     "key": "Groups",
     "value": [
       ""
     ],
     "passed": true
   },
   {
     "key": "Features",
     "passed": true
   },
   {
     "key": "WlIdentifier",
     "passed": true
   }
 ]
}

このエラー例では、SAMLResponse の「Role」属性が欠落しているか、無効な値が指定されていることを示しています。メッセージには、「Role」属性に許容される値がリストされ、受信された値（存在する場合）も表示されます。

その他のよくある問題

エラー: sso.user.error.invalidRole

エラー: Verification failed before assertion, error: https://$base_url/api/sso/saml/metadata/$salesPartnerId is not a valid audience for this Response

SSOの適用

ユーザーの詳細と権限設定を完全に制御し、シングルサインオン（SSO）を有効化したユーザーのみがアプリにアクセスできるようにしたい場合は、「SSOを強制」機能を有効にしてください。このオプションはSSO設定セクションにあります。

この機能を利用するには、必要なすべてのデータ（ユーザーの詳細、ユーザーの特徴、ユーザーの所在地／事業の所有権）がSAMLアサーション（ジャストインタイムプロビジョニング経由）に渡されていることを確認する必要があります。この機能を有効にすると、SAMLプロビジョニング外で行われたユーザー変更はすべて拒否されます。つまり、ユーザーインターフェースまたはAPI経由でユーザーを更新することはできません。

その他のよくある質問

Q: 後からredirectUrlを追加できますか?

A: はい、認証エンドポイントはredirectUrlパラメータをサポートしているため、フローの最後にユーザーはそのページに移動します。redirectUrlは完全に動的であり、必要なのはURL部分だけです（例：?redirectUrl=/dashboard）。