認証・認可の実装ガイド

本ガイドは、OIDC 1.0 / OAuth 2.0（認可コードフロー）に準拠した認証・認可サーバーを構築するための手順書です。 貴社の認証・認可サーバー（Identity Provider = IdP）は、UPWARDアプリケーション（Relying Party = RP）に対して認証・認可機能を提供する必要があります。

必要な理解

スムーズな実装のため、以下の仕様を事前にご確認いただくことを推奨いたします：

• OpenID Connect Core 1.0（日本語）
• OAuth 2.0（RFC 6749）（日本語）
• OAuth 2.0 Security Best Current Practice

フロー全体像

認証・認可フローの詳細は、認証・認可フローのシーケンス図を参照してください。

主な流れは以下の通りです：

1. UPWARDアプリに対するログイン試行（UPWARD側処理）
2. 認可リクエスト: 認可コードの発行
3. ログイン処理: ログイン画面での対話
4. スコープに対するユーザー同意: 同意画面での対話
5. トークン発行: 認可コードと各種トークンの交換
6. セッション確立: ユーザー情報の取得とセッション管理

ユーザーインターフェース（UI）実装

Web API実装以外の実装内容として、以下のUIが別途必要となります：

• ログイン画面: ユーザーがIdPに直接認証情報を入力
• 同意画面: アクセス許可の確認と同意取得

これらの画面は、ブラウザ上で動作する必要があります。（サーバーサイドレンダリング / SPA等、実装形態は問いません）

また、PC / スマートフォンどちらでの表示も前提としたUIを構築してください。

データ登録

認可コードフローに準拠した認証・認可サーバーを構築するにあたり、以下のデータを任意の格納先（データベーステーブル等）に登録する必要があります：

• OAuthクライアント情報: UPWARDのアプリケーションをOAuthクライアントとして登録

  フィールド	形式	登録・管理する値
  クライアントID	文字列	任意の識別子（例: UUID）
  クライアント名	文字列	UPWARD
  クライアントシークレット	文字列	十分にランダムで推測不可能な任意の文字列 推奨値： 文字種: 英数字と記号 文字列長: 64文字以上 生成方法: 暗号学的に安全な乱数生成器を使用
  リダイレクトURI一覧	文字列の配列	https://app.upward.jp/callback/ https://mobile.upward.jp/callback/ msauth.jp.upward.agent://auth 認証プロバイダにMicrosoft Entraを使用する場合のみ指定 この値はバンドルIDにjp.upward.agentを指定することで自動で生成されます
  スコープ一覧	文字列の配列	openid profile email offline_access
  アプリのロゴ	画像（任意）	UPWARDロゴ（png, svg）
  プライバシーポリシーURL	文字列（任意）	https://www.upward.jp/privacy

• 登録したデータのうち、「クライアントID」「クライアントシークレット」をUPWARDに情報提供して頂く必要があります

具体的な実装内容

認可コードフローを用いた認証・認可機能を実現するにあたり、以下のAPIエンドポイントやユーザーインターフェース（UI）の実装が必要となります

OpenID プロバイダーコンフィグレーションエンドポイント: 必須

エンドポイントの具体的な要求については、OIDC 1.0プロバイダーコンフィグレーションの取得をご確認ください。

公開鍵群（JWKs）取得エンドポイント: 必須

エンドポイントの具体的な要求については、OIDC 1.0公開鍵群の取得をご確認ください。

ユーザー情報（UserInfo）取得エンドポイント: 必須

認証・認可フロー: No.38 〜 No.40

エンドポイントの具体的な要求については、OIDC 1.0ユーザー情報の取得をご確認ください。

ログイン画面: 必須

認証・認可フロー: No.11 〜 No.17

有効なユーザーセッションが存在しない場合は、ログイン画面でのユーザー認証とユーザーセッションの確立後、貴社システム内のプライベートページにアクセスする仕組みを実装してください。

ユーザー認証の仕様や方法について、UPWARDからの具体的な要求はありません。（ユーザー名・パスワード or SSO、MFAの利用等不問）

パスワード変更画面: 任意

必要に応じて、ユーザーによるパスワード変更を可能にする画面を実装してください。

認可エンドポイント: 必須

認証・認可フロー: No.10 〜 No.27

エンドポイントの具体的な要求については、OIDC 1.0認可処理をご確認ください。

同意画面: 任意

認証・認可フロー: No.18 〜 No.24

認可コード発行タイミングでUPWARDがユーザーのプロフィール情報等にアクセスすることについて、ユーザー本人に明示的な同意を求める画面を実装するかどうかを選択してください。

実装の選択肢	実装方法	メリット	デメリット
初回のみ同意画面を表示（推奨）	ユーザー毎の同意履歴をデータベース等で管理し、2回目以降は同意画面の表示をスキップ	ユーザーへのプライバシー配慮と利便性を両立 OIDC仕様の推奨パターン	開発コストが最も高い（同意履歴管理が必要）
同意画面を一切表示しない（事前承認方式）	特になし（同意画面を実装しない）	開発コストが最も低い ユーザー体験がシームレス	別途、利用規約等でユーザー同意を得るなどの配慮や取り決めが必要 UPWARD以外のアプリケーションと認可コードフローにより連携する際に別途調整が発生する
常に同意画面を表示	ユーザー毎の同意履歴を管理せず、認可コード発行前に必ず同意画面を表示する	開発コストは中程度（履歴管理不要） セキュリティ意識の高いユーザーに安心感を提供	ユーザー利便性が低い（毎回同意が必要）

同意画面を実装する場合は、以下の要素を表示する必要があります：

• OAuthクライアント情報
  • クライアント名
  • 信頼できるクライアントであることを示す情報（ロゴ等）: 任意
• 認可エンドポイントに対して要求されたスコープの種類や説明
  • openid: IDトークン発行
  • profile: プロフィール情報
  • email: メールアドレス
  • offline_access: リフレッシュトークン発行
• アクセス許可ボタン
• アクセス拒否ボタン

トークン交換エンドポイント: 必須

認証・認可フロー: No.30 〜 No.36

エンドポイントの具体的な要求については、OIDC 1.0トークン交換処理をご確認ください。

トークン失効エンドポイント: 任意

必要に応じて、ログアウト時等に有効期限を迎えていないアクセストークンを失効させる機能を実装してください。