ヘルプセンター アカウント ログイン方法 シングルサインオン（SSO）サブアカウントインターフェース

シングルサインオン（SSO）サブアカウントインターフェース

概要

このエンドポイントでは、シングルサインオン（SSO）を通じてサブアカウントを作成できます。サブアカウントを作成した後、同じエンドポイントでサインインできます。

このエンドポイントで作成されたユーザーは、あなたのプライマリアカウント配下のサブアカウントです。権限はプライマリアカウントと同期されます。作成方法やサインイン方法を除けば、権限や設定は手動で作成したサブアカウントと同じです。


導入前の準備

1. プライマリアカウントで SurveyMars にサインインします。マイアカウントページで appId（アカウント ID）を確認してください。


2. カスタマーサポートに連絡して SSO を有効にし、Secret Key を取得してください。このキーはサーバー側でのみ使用して sign 署名を計算してください。平文で URL に付加したり、フロントエンドのコードに露出させたりしないでください。


マイアカウント


3. サーバーで有効な SHA256 署名文字列を生成できること、そしてユーザーのブラウザまたはその他の信頼できる環境から GET リクエストでログイン URL を開けることを確認してください。


パラメータ


メソッド: GET


エンドポイント: https://surveymars.com/app/login/sso/verify?appId=&email=&userName=&roleId=&ts=&returnUrl=&language=&isOnlyLogin=&sign=



パラメータ 説明 必須
appId 会社の ID。プライマリアカウントでサインインした後、マイアカウント を開くと表示されるアカウント ID が統合に必要な appId です。クエリパラメータ名は大文字小文字を含めこのドキュメントと正確に一致する必要があります：appId。 はい
Secret Key 開発者用シークレット。生成するにはカスタマーサポートに連絡してください。作成後は マイアカウント で確認できます。sign を計算するためにサーバー側でのみ使用してください。 いいえ
ts Unix タイムスタンプ：1970-01-01 00:00:00 UTC からの秒数。有効期限は60秒です。 はい
sign 暗号学的署名。sign は、連結したプレーンテキストの小文字の 16 進表現による SHA256 ダイジェストです。クエリパラメータ sign として渡します。リクエストに roleId が含まれる場合、プレーンテキストは appId + email + userName + roleId + ts + Secret Key です。roleId が省略される（オプション項目を送らない）場合、プレーンテキストには roleId セグメントを含めてはいけません：appId + email + userName + ts + Secret Key。連結の順序と型は正確に一致する必要があります。Secret Key はサーバー側でのみ連結し、ブラウザのアドレスバーに表示してはいけません。署名計算ルールは下記を参照してください。
補足：クエリパラメータ isOnlyLogin は language や returnUrl と同様に、署名プレーンテキストには参加しません。isOnlyLogin=true かつ URL に userName が含まれない場合、userName セグメントは署名計算時に 空文字列 として扱ってください（順序は変更しません：appId + email + 空の userName + roleId（存在する場合） + ts + Secret Key）。
連結を確認するため、プレーンテキスト文字列をサードパーティツール（例：オンライン SHA256 ハッシュ生成ツール）に貼り付けてダイジェストを生成することができます。本番では必ずサーバー側のコードで sign を計算し、Secret Key をブラウザに露出しないでください。		 はい
email サブアカウントに紐付けるメールアドレス。統合内で必ず一意となる値を使用してください。空にできません。 はい
userName サブアカウントの表示名。最大 150 文字。空にできません。値にスペース、中国語文字、またはその他の特殊文字が含まれる場合は、パラメータを URL エンコード してください（例：スペースは にエンコード）。
補足：isOnlyLogin=true の場合、userName はオプションです（サインインのみでサブアカウントは作成されません；isOnlyLogin を参照）。isOnlyLogin=false またはパラメータ省略時（デフォルトは false）では、userName は必須です。		 条件付き
isOnlyLogin 既存のサブアカウントにのみサインインするか（作成しないか）を指定します。値は true / false（小文字推奨）；省略時は false がデフォルトです。このパラメータは SHA256 署名の入力には含まれません。
true：指定した email の既存サブアカウントのみを検証してサインインし、新規作成は行いません。userName は省略可能です。サブアカウントが存在しない場合、製品は ユーザーが存在しません（user does not exist） のメッセージを表示します（表示文言は UI 言語に従います）。
false または省略：userName は必須です。そのメールのサブアカウントが既に存在すればサインインし、存在しなければサブアカウントを作成してからサインインします（初回作成時の roleId 等のルールが適用されます）。		 いいえ
roleId 新しいサブアカウントの役割。任意です。省略または空の場合はデフォルトで調査管理者（Survey Administrator）になります。サブアカウントの役割一覧：1—システム管理者、2—調査管理者、3—集計閲覧者、4—全結果閲覧者、6—調査編集者（共同作成者）。この一覧外の値を送信しないでください；API はエラーを返します。 いいえ
returnUrl サインイン成功後のリダイレクト先（相対パス推奨、例：/usercenter, /survey/list）。省略した場合、ユーザーは My Surveys に遷移します。モバイルクライアントで正しく解決されるよう、必要に応じてパスを URL エンコードしてください。 いいえ
language UI 言語を整数で指定します。任意；省略した場合は製品のデフォルト言語が適用されます。このパラメータは上記の sign SHA256 入力文字列には参加しません。
値のマッピング：
1—簡体字中国語（zh）
2—英語（en）
3—繁体字中国語（tw）
4—日本語（ja）
5—韓国語（ko）
6—アラビア語（ar）
7—フランス語（fr）
8—ドイツ語（de）
9—スペイン語（es）
10—ポルトガル語（pt）
11—イタリア語（it）
12—ロシア語（ru）
13—タイ語（th）
14—トルコ語（tr）
15—インドネシア語（id）
16—ベトナム語（vi）
17—ポーランド語（pl）
18—オランダ語（nl）
22—ヘブライ語（he）
23—スウェーデン語（sv）
27—デンマーク語（da）
28—フィンランド語（fi）
30—マレー語（ms）
31—ノルウェー語（nb）
50—アイスランド語（is）		 いいえ


署名の計算方法


1. 署名に使うフィールドを決まった順序で区切り文字なしに連結して 1 つの文字列にします。roleId を送る場合、順序は appId + email + userName + roleId + ts + Secret Key です。roleId を省略する場合は、roleId セグメントを完全に含めないでください：appId + email + userName + ts + Secret Key。補足：isOnlyLogin=true かつ URL に userName が含まれない場合、署名計算時の userName セグメントは空文字列として扱ってください；isOnlyLogin 自体は決して連結されません。


2. その文字列を SHA256 でハッシュし、小文字の 16 進ダイジェストを sign として使用します。


3. language、returnUrl、isOnlyLogin のようなクエリパラメータは署名プレーンテキストに参加しません；署名に使うのはステップ 1 のフィールドとその順序だけです。



初回作成と以後のサインイン


email、roleId、および userName は、サブアカウントが 初めて作成されるときのみemail のサブアカウントが既に存在する場合、後続のリクエストは新しい roleId や userName が以前に保存されたものと一致するかを検証せず、保存されたプロファイルを新しい値で更新しません。無効な署名や必須フィールドの欠如は、署名またはパラメータエラーを返す可能性があります。


補足（isOnlyLogin とサインイン／作成の違い）： isOnlyLogin=false または省略の場合：指定した email のサブアカウントが既に存在すればサインインし、存在しなければサブアカウントを作成してからサインインします（初回作成時に userName やその他のフィールドが保存されます）。isOnlyLogin=true の場合：既存のサブアカウントのみサインイン可能で、何も作成されません；サブアカウントが存在しない場合、UI は ユーザーが存在しません（user does not exist） と報告します。


FAQ

Q: 署名やパラメータのエラーが表示されるのはなぜですか？


A: Secret Key が正しいことを確認してください：roleId がある場合は appId、email、userName、roleId（整数）、ts、Secret Key を連結します；roleId がない場合は roleId セグメントを省略して連結します（appId、email、userName、ts、Secret Key）。isOnlyLogin=true かつ URL に userName がない場合はプレーンテキストに空の userName セグメントを使用してください。ts が許容ウィンドウ内にあること、そして URL エンコードで実際に連結される生の値が変更されていないことを確認してください。appId が欠落しているか email が空だとパラメータエラーになります；isOnlyLogin=false（または省略）の場合、userName が空だとパラメータエラーになります。


Q: サブアカウントはすでに調査管理者（Survey Administrator）なのに、間違った roleId でもサインインできるのはなぜですか？


A: その email のサブアカウントが既に存在する場合、システムは現在のリクエストの roleId や userName を検証したり更新したりしません；これらのフィールドは主に初回作成時に影響します。初回作成時には有効な roleId を送るか、空にしてデフォルトのロールを使用してください。


Q: ts はなぜこんなに短時間で期限切れになるのですか？


A: 本番環境ではタイムスタンプがサーバー時刻から 60 秒 以内である必要があります。ユーザーをリダイレクトする直前に ts と sign を生成してください。


Q: userName にスペースや中国語文字が含まれていて呼び出しが失敗したらどうすればいいですか？


A: クエリパラメータを URL エンコードしてください（スペースは など）。エンコードしないと、一部の HTTP クライアントがリクエストを切り詰めたり破損させたりします。それは通常クライアント側の失敗として見えることが多く、サーバーが有効な文字を拒否しているわけではありません。


Q: isOnlyLogin=true と false の違いは何ですか？なぜ “user does not exist” が表示されるのですか？


A: isOnlyLogin=true はサインインのみでサブアカウントの作成は行わない設定で、userName は省略可能です。指定した email に対応するサブアカウントがプライマリアカウント配下に存在しない場合、製品は ユーザーが存在しません（user does not exist） と表示します。isOnlyLogin=false または省略時は userName が必須で、既存のメールならサインインし、なければサブアカウントを作成します。


Q: SurveyMars で SSO 作成されたサブアカウントを削除するにはどうすればいいですか？


A: プライマリアカウントでサインインし、Sub-accounts ページで手動でサブアカウントを削除してください。自社の人事システムやディレクトリでユーザーを削除しても、SurveyMars のサブアカウントは自動で削除されません；両システムを連携させる場合は、独自のデータポリシーで整合性を保ってください。


この記事はどのくらい役に立ちましたか？
前の記事
WhatsAppログイン
二要素認証 2FA
次の記事