OpenID Connect 実装チュートリアル

ここでは OpenID Connect を使った ID 連携をチュートリアル形式で実装していきます。

なお、本ドキュメントは Web ブラウザを通じて利用される SaaS サービスを対象としています。
SaaS サービスの Backend API と連携する Native App を通じて利用される SaaS サービスの場合は、本ドキュメントではなく OpenID Connect 実装チュートリアル (Native アプリ向け) をご覧ください。

なお、本チュートリアルではプログラミング言語に依存しない形での解説を行っていますが、実際に実装する際には各言語・フレームワークで広く使われている OAuth ライブラリ、OpenID Connect ライブラリの利用を推奨します。

Step0. OpenID Connect Client の登録

OPTiM Store では、Tenant Contract API および OpenID Connect Client Registration API を利用して、OpenID Connect Client の登録を自動化していますが、本ドキュメントでは事前にそれらの API を利用して、もしくは手動にて以下のように OpenID Connect Client を登録済であると仮定します。

Key	Value
client_id	`7a05a846d3dc5a860013ea7fe201e025`
client_secret	`d9fccaa5cdf30f86c6efe73f25774e9a625ceaa9aa26de7e9f364370a71820d5`
redirect_uris	`["https://your-service.example.com/optim-store/callback"]`

Step1. Authorization Request の送信

御社サービス側でユーザーの認証が必要になったタイミング (アプリ起動時や Dashboard へのアクセス時 etc.) で、https://store-xyz-federation.optim.co.jp/connect/authorization に OpenID Connect の定める以下のパラメータを付与して、ユーザーをリダイレクトさせます。

Key	Value
client_id	`7a05a846d3dc5a860013ea7fe201e025`
response_type	`code`
scope	`openid`
redirect_uri	`https://your-service.example.com/optim-store/callback`
state	セッションに紐付いた値 (この例では `590d36e1688aa02f863c78cae78d5dc8` とします)
nonce	セッションに紐付いた値 (この例では `72cf7cf3a0010c45912ce3562d25e2c3` とします)

実際にリダイレクト先になる URL は以下のようになります。

https://store-xyz-federation.optim.co.jp/connect/authorization?client_id=7a05a846d3dc5a860013ea7fe201e025&response_type=code&scope=openid&redirect_uri=https%3A%2F%2Fyour-service.example.com%2Foptim-store%2Fcallback&state=590d36e1688aa02f863c78cae78d5dc8&nonce=72cf7cf3a0010c45912ce3562d25e2c3

state の生成方法

state には推測困難な乱数値 (Secure Random) を使用し、その値を Web ブラウザと御社サーバーの間のセッションに紐付けて保存するようにしてください。

後述の Token Response 受信時に state のチェックを怠ったり当該セッションに紐付かない state を受け入れてしまうと、被害者が悪意ある攻撃者に攻撃者のアカウントで強制的にログインさせられる (いわゆる「ログイン CSRF」) 危険性があります。
ログイン CSRF 攻撃が成立してしまうと、被害者が攻撃者アカウントでログインした後に御社サービス上で生成した各種データ (メール送信履歴やクラウドに保存したドキュメント等) が、攻撃者の手に渡ってしまうことになります。

nonce の生成方法

nonce には推測困難な乱数値 (Secure Random) を使用し、その値を Native App と Backend API Server の間で確立されたセッションに紐付けて保存するようにしてください。

OpenID Connect の仕様上、Web アプリの場合は nonce の利用はオプションですが、何らかの脆弱性等により Code が漏洩した場合に発生しうるリスクを軽減するためにも nonce の利用は有効です。

Step2. Authorization Response の受信

OPTiM Store 側でのユーザー認証等が正常に終了すると、redirect_uri として指定された https://your-service.example.com/optim-store/callback に code と state が付与された状態で、ユーザーがリダイレクトして戻されます。

ここでは以下のような値が code として返されるものとします。

Key	Value
code	`f467ccbaca74f35da15c265616a059cc1ea7a31d2cde0a119e5e8d6714cc3e68`

すると、ユーザーは以下の URL にリダイレクトされ、御社サービスに戻されます。

https://your-service.example.com/optim-store/callback?code=f467ccbaca74f35da15c265616a059cc1ea7a31d2cde0a119e5e8d6714cc3e68&state=590d36e1688aa02f863c78cae78d5dc8

前述の通り、ログイン CSRF 攻撃を防止するため、Authorization Response を受けとったらまず state が Authorization Request 送信時のセッションに紐付いていることを確認してください。

Step3. Token Request の送信 & Token Response の受信

state のチェックが終わったら、受け取った code を https://store-xyz-federation.optim.co.jphttps://store-xyz-federation.optim.co.jp/connect/token に POST して、access_token、refresh_token、id_token を取得します。

この時送信するパラメータは、以下の通りです。

Key	Value
client_id	`7a05a846d3dc5a860013ea7fe201e025`
client_secret	`d9fccaa5cdf30f86c6efe73f25774e9a625ceaa9aa26de7e9f364370a71820d5`
grant_type	`authorization_code`
code	`f467ccbaca74f35da15c265616a059cc1ea7a31d2cde0a119e5e8d6714cc3e68` (実際に受け取った値を指定してください)
redirect_uri	`https://your-service.example.com/optim-store/callback`

実際に送信される HTTP POST Request は、以下のようになります。

POST /connect/token HTTP/1.1
Content-Type: application/x-www-form-urlencoded
HOST: store-xyz-federation.optim.co.jp

client_id=7a05a846d3dc5a860013ea7fe201e025&client_secret=d9fccaa5cdf30f86c6efe73f25774e9a625ceaa9aa26de7e9f364370a71820d5&grant_type=authorization_code&code=f467ccbaca74f35da15c265616a059cc1ea7a31d2cde0a119e5e8d6714cc3e68&redirect_uri=https%3A%2F%2Fyour-service.example.com%2Foptim-store%2Fcallback

レスポンスとしては以下のような JSON データが返されます。

{
  "access_token": "eyJ..(省略)..oxA",
  "refresh_token": "413..(省略)..873",
  "token_type": "bearer",
  "expires_in": 300,
  "id_token": "eyJ..(省略)..LeA"
}

通常はここで受け取った access_token および refresh_token を利用することはありませんので、それらはそのまま破棄していただいて結構です。

id_token は御社サービス側でのログイン処理に利用します。

Step5. ID Token の検証およびログイン処理

ID Token の検証方法については ID Token の検証 - OpenID Connect Federation にまとめてあるので、そちらをご覧ください。

ID Token 検証が成功したら、御社ドメインの認証 Cookie を発行するなど、当該ユーザーを認証済状態とする処理を行うことになるでしょう。

以上で、OpenID Connect による Federation の一連のフローは完了です。