認証API実装ガイド
SaaSus Platform 認証APIを使って、独自のログイン画面からログイン処理を実装するため の概要を説明します。
基本実装の具体的なコードは 認証APIを利用した基本実装 を、応用例は 認証APIを利用した応用例（IDログイン） を、セキュリティ実装は 認証セキュリティ・ポリシーの実装 をご参照ください。
認証APIとは
認証APIは、SaaSus Platform が提供する標準のホステッドログイン画面を使用せず、SaaS プロバイダーが独自に構築した UI からログイン機能を実装するための API です。
サーバーサイドから SaaSus Platform Auth API（/sign-in および /sign-in/challenge）を呼び出すことで、ID トークン・アクセストークン・リフレッシュトークンを取得でき、以降の API 呼び出しや認可に利用します。
本ドキュメントでは、この認証APIを使って「独自ログイン画面」を使った、ログイン処理を実装する方法を説明します。
認証APIでできること
独自ログイン画面からのメールアドレス＋パスワード認証
SaaSus Platform 標準ログイン画面を利用せず、自社ブランドの UI からログイン処理を行えます。ログイン画面のデザインやUXをカスタマイズできます。
トークン（ID／アクセス／リフレッシュトークン）の取得
正常に認証が完了すると、SaaSus Platform API 呼び出しに必要な各種トークンが取得できます。
認証フローとアーキテクチャ
認証APIは、Secure Remote Password（SRP）プロトコルに基づいた 2段階認証フロー です。単にパスワードを送信するのではなく、チャレンジ＆レスポンス方式で安全に認証を行います。
認証フロー概要
フローの詳細
- 認証開始: フロントエンドでメールアドレス（または ID）とパスワードを入力し、SRP_A を生成してバックエンドに送信します（パスワードは送信しません）。
- チャレンジ情報取得: バックエンドが SRP_A を SaaSus Platform Auth API の
/sign-inに送信します。 - チャレンジ情報受信: SaaSus Platform Auth API からチャレンジ情報（SRP_B, SALT, SECRET_BLOCK など）がバックエンドに返されます。
- チャレンジ情報転送: バックエンドがチャレンジ情報をフロントエンドに返却します。
- 署名生成と送信: フロントエンドが署名（
PASSWORD_CLAIM_SIGNATUREなど）を生成し、バックエンドに送信します。 - 検証の依頼: バックエンドが署名とチャレンジ情報を SaaSus Platform Auth API の
/sign-in/challengeに送信します。 - トークン発行: 認証成功時、ID トークン・アクセストークン・リフレッシュトークンがバックエンドに返却されます。
- トークン保存: バックエンドが HttpOnly Cookie でトークンをフロントエンドに返します。
SRP（Secure Remote Password）プロトコルでは、パスワードそのものをネットワーク上に平文で送信しません。ハッシュ化や SRP 計算を通じて認証を行うため、中間者攻撃に対してもセキュアな認証が実現できます。フロントエンドだけで SRP 計算を完結させるのは複雑なため、本サンプルアプリケーションでは、フロントエンドで SRP_A や署名の生成を行い、バックエンドが SaaSus Platform API との通信を仲介する構成をとっています。
チャレンジの種類と分岐処理
SaaSus Platform Auth API から返されるチャレンジには、以下の種類があります：
| チャレンジ名 | 説明 | 処理 |
|---|---|---|
PASSWORD_VERIFIER | 通常のパスワード検証 | チャレンジレスポンスを送信してトークンを取得 |
NEW_PASSWORD_REQUIRED | 初回ログイン時のパスワード変更 | 新しいパスワードの入力を求め、再度チャレンジを送信 |
サンプルアプリケーションの構成
本実装ガイドのサンプルアプリケーションは、以下のリポジトリで公開しています。
技術スタックは以下の通りです：
| 項目 | 技術スタック |
|---|---|
| フロントエンド | React + TypeScript |
| バックエンド | Go |
| トークン管理 | HttpOnly Cookie |
| セキュリティ | CSRF 対策 |
実装されている画面・機能
- ログイン画面: メールアドレスログインとIDログインのタブ切り替えUI
- 新パスワード設定画面: 初回ログイン時のパスワード変更
- 認証API: SaaSus Platform Auth API との SRP 認証フロー
- IDログイン: テナント属性
login_domainを活用した ユーザー名＋テナントIDによるログイン - トークン管理: HttpOnly Cookie による安全なトークン保存
- ログアウト処理: Cookie クリアによるセッション終了
具体的な実装内容は、認証APIを利用した基本実装 をご覧ください。