SSO連絡先インターフェース
この記事では、連絡先のメールアドレスまたはサードパーティのユーザー ID でシングルサインオンする方法を説明します。appId と Secret Key はサブアカウント SSO インターフェースと同じですが、URL、署名項目、ログイン後の行き先は異なります。サブアカウントの作成とロール設定は、引き続きサブアカウント SSO インターフェースを使ってください。
概要
連絡先のメールアドレスまたはサードパーティのユーザー ID を渡すと、システムは署名を検証してその連絡先でログインします。ログイン後の動作は次のとおりです。
- 有効な surveyId を渡した場合、そのアンケートの回答ページを直接開きます。優先度は returnUrl より高くなります。
- surveyId を渡さない、または surveyId が無効な場合は、returnUrl へ移動します。サブアカウントと一般の連絡先の両方に適用され、連絡先ページへ移動することもできます。
- returnUrl を渡さない場合、サブアカウントはアンケート一覧へ、一般の連絡先は連絡先ホームへ移動します。
利用シーン
- 業務システムに連絡先のメールアドレスまたはサードパーティのユーザー ID があり、パスワードなしで SurveyMars に入りたい。
- ログイン後すぐに特定のアンケートへ回答させる。surveyId を渡します。
- サブアカウントと一般の連絡先のどちらも returnUrl に従えます。連絡先ページも含みます。
事前準備
1. メインアカウントで SurveyMars にログインし、「マイアカウント」で appId(アカウント ID)を確認します。
2. サポートに連絡して Secret Key を有効にします。鍵はサーバー側の署名にだけ使い、URL やフロントエンドのコードには書かないでください。
3. サーバー側でこの記事の規則に従って SHA256 署名を作り、GET でログインリンクを開きます。

インターフェース
メソッド:GET
| パラメーター | 必須 | 説明 |
| appId | はい | メインアカウント ID。サブアカウント SSO インターフェースと同じ appId を使います。 |
| 条件付き | 連絡先のメールアドレス。thirdUserId と少なくとも一方が必要です。メインアカウントで「連絡先メールアドレスを空にできる」を有効にしていない場合、email は必須です。 | |
| thirdUserId | 条件付き | サードパーティのユーザー ID。email と少なくとも一方が必要です。両方渡した場合、検証は thirdUserId を無視しますが、その値は署名に含めます。 |
| language | いいえ | メッセージの言語。署名には含めません。 |
| returnUrl | いいえ | ログイン成功後の移動先。サブアカウントと一般の連絡先の両方に適用され、連絡先ページへ移動できます。署名には含めません。アドレスに & または ? が含まれる場合、returnUrl 全体を 1 回だけ URL エンコードしてください。 |
| surveyId | いいえ | アンケート ID。署名には含めません。有効な場合はそのアンケートの回答ページを直接開き、returnUrl より優先されます。無効な場合は returnUrl へ移動します。 |
| ts | はい | 1970-01-01 00:00:00(UTC)からの秒数。有効期限は 60 秒です。URL の ts は署名に使った ts と同じにしてください。リンクを開く直前に生成します。 |
| sign | はい | 署名。連結した平文を SHA256 した十六進数の小文字が sign です。平文は appId + email + thirdUserId + ts + Secret Key です。順序を守ってください。Secret Key はサーバー側の連結にだけ使い、ブラウザのアドレスバーには出しません。詳しくは下記「署名の計算」を参照してください。 |
署名の計算
署名の計算規則
1. 署名対象の項目を、区切りなしで次の順に連結します。appId + email + thirdUserId + ts + Secret Key。渡していない email または thirdUserId は空文字として連結します。この部分を省いたり、プレースホルダーに置き換えたりしないでください。Secret Key はサーバー側の連結にだけ使い、ブラウザのアドレスバーには出しません。
2. その文字列の SHA256 を計算し、十六進数の小文字を sign の値にします。
3. クエリの language、returnUrl、surveyId は署名文字列に含めません。手順 1 の項目と順序だけを使います。
4. ts は 1970-01-01 00:00:00(UTC)からの秒数で、有効期限は 60 秒です。ユーザーが移動する直前に ts と sign を生成し、URL の ts は署名に使った ts と同じにしてください。URL エンコードで、連結に使う元の値を変えないでください。
5. 連結が正しいか確認するには、平文を外部ツール(例:LZL オンライン SHA256)に貼り付けます。本番ではサーバー側のコードで sign を生成し、Secret Key をブラウザに出さないでください。
6. サブアカウント SSO の署名文字列をこのインターフェースに使わないでください。サブアカウント側の項目は appId、email、userName、roleId、ts です。このインターフェースに userName と roleId はありません。
メールアドレスと thirdUserId
1. email と thirdUserId の少なくとも一方を指定します。
2. 両方指定した場合、検証は email だけを使い、thirdUserId は無視します。thirdUserId は元の値のまま署名に含め、URL に残すこともできます。
3. メインアカウントで「連絡先メールアドレスを空にできる」を有効にしていない場合は、email が必須です。
ログイン後の移動
1. 有効な surveyId を渡した場合:ログイン後、そのアンケートの回答ページを直接開きます。優先度は returnUrl より高くなります。
2. surveyId を渡さない、または surveyId が無効な場合:returnUrl へ移動します。サブアカウントだけに限りません。一般の連絡先も移動でき、連絡先ページも含みます。
3. returnUrl を渡さない場合:サブアカウントはアンケート一覧へ、一般の連絡先は連絡先ホームへ移動します。
returnUrl のエンコード
returnUrl に & または ? が含まれる場合は、returnUrl 全体を 1 回だけ URL エンコードしてからログインリンクに入れてください。一部だけをエンコードしたり、2 回エンコードしたりしないでください。全体をエンコードしないと、& と ? がログインリンク自身の区切りとして扱われ、サーバーが完全なアドレスを認識できません。
たとえば、元のアドレスが https://surveymars.com/app/contacts?tab=1&id=2 の場合、1 回エンコードして次のように書きます。
returnUrl=https%3A%2F%2Fsurveymars.com%2Fapp%2Fcontacts%3Ftab%3D1%26id%3D2
returnUrl は署名に含めないため、エンコードしても sign は変わりません。
注意事項
- Secret Key はサーバー側だけで使い、ブラウザのアドレスバーに出さないでください。
- このインターフェースは連絡先のログイン用です。サブアカウントの作成やロール設定には使いません。
- email の @ などを URL に入れるときはエンコードしてください。署名にはエンコード前の元の値を使います。
- surveyId は任意で、署名には含めません。有効なら回答ページを開き、無効なら returnUrl へ移動します。
- returnUrl に & または ? が含まれる場合は、アドレス全体を 1 回だけ URL エンコードしてください。
よくある質問
問:このインターフェースとサブアカウント SSO の違いは?
答:サブアカウントの URL は /app/login/sso/verify で、サブアカウントの作成またはログインに使います。連絡先の URL は /app/login/contact/verify で、メールアドレスまたはサードパーティのユーザー ID で連絡先にログインします。署名項目が異なるため、sign は流用できません。
問:thirdUserId だけ渡し、email は省けますか?
答:はい。ただしメインアカウントで「連絡先メールアドレスを空にできる」を有効にしておく必要があります。無効な場合、email は必須です。署名では、渡していない項目を空文字として連結します。
問:email と thirdUserId の両方を渡したのに、メールアドレスでログインされるのはなぜですか?
答:両方渡した場合、検証は thirdUserId を無視し、email だけで連絡先を識別します。thirdUserId は署名に含める必要があります。
問:一般の連絡先も returnUrl に従えますか?
答:はい。returnUrl はサブアカウント専用ではなくなりました。一般の連絡先も移動でき、連絡先ページも含みます。有効な surveyId がある場合は、先にそのアンケートの回答ページを開きます。
問:surveyId と returnUrl の両方を渡すと、どのページが開きますか?
答:有効な surveyId がそのアンケートの回答ページを優先して開き、returnUrl より優先されます。surveyId が無効、または渡されていない場合だけ returnUrl へ移動します。
問:returnUrl に & または ? があると、移動先が欠けるのはなぜですか?
答:returnUrl 全体を 1 回だけ URL エンコードしてください。たとえば ? は %3F、& は %26 です。一部だけをエンコードしたり、2 回エンコードしたりしないでください。
問:署名検証に失敗するのはなぜですか?
答:Secret Key と、appId、email、thirdUserId、ts、Secret Key の連結順を確認してください。渡していない email または thirdUserId は空文字として連結します。ts が 60 秒以内であること、URL エンコードが連結前の値を変えていないことも確認してください。language、returnUrl、surveyId は署名文字列に入れないでください。
問:ts はなぜすぐ期限切れになりますか?
答:本番環境では、タイムスタンプとサーバー時刻の差を 60 秒以内にする必要があります。ユーザーが移動する直前に ts と sign を生成してください。