OpenID Connect Token Request

OpenID Connect における認証結果である ID Token を取得するためのAPIです。
Callback 時に受け取った Authorization Code を OPTiM Store の Token Endpoint に送信 (Token Request) することで、認証結果を示すトークン (ID Token) を受け取ることができます。

Request

Method

  • POST

Resource URL

  • URLは、OPTiM Store との契約時にご連絡いたします。
  • 本章では、https://store-xyz-federation.optim.co.jp/connect/token として記載致します。

Header Parameters

Content-Type: application/x-www-form-urlencoded

Query Parameters

  • なし

Request Parameters

key description
client_id 事前登録時に取得した Client ID
client_secret 事前登録時に取得した Client Secret
grant_type authorization_code 固定
code 取得した code 値
redirect_uri 認証リクエスト時に指定した redirect_uri

Sample Body

grant_type=authorization_code&client_id=<your-client-id-for-the-tenant>&client_secret=<your-client-secret-for-the-tenant>&code=<onetime-token>&redirect_uri=https%3A%2F%2Fyour-service.example.com%2Foptim-store%2Fcallback

Concept Code

以下に Ruby での Token Request 送信のコンセプトコードを記載します。(実際の利用時には OpenID Connect ライブラリ等の利用を推奨します)

params = {
  client_id: '<your-client-id-for-the-tenant>',
  client_secret: '<your-client-secret-for-the-tenant>',
  grant_type: 'authorization_code',
  code: '<onetime-token>',
  redirect_uri: 'https://your-service.example.com/optim-store/callback'
}
token_endpoint = 'https://store-xyz-federation.optim.co.jp/connect/token'

response = HTTPClient.post(token_endpoint, params)
response.body
# {
#   "access_token": "fake",
#   "token_type": "bearer",
#   "expires_in": 300,
#   "id_token": "<id-token>"
# }

Response

正しく Token Request が送信されてきた場合、下記に従ったレスポンスを返却します。

Response Code

200 OK

Response Parameters

key type description
access_token string 一部のライブラリでエラーになることを防ぐ目的で OAuth 2.0 に準拠するためだけに発行される Token です。OPTiM Store との連携ではこの Token は利用しません。
token_type string bearer 固定
expires_in integer access_token の有効期間 (秒数) です。access_token は利用しないので無視してください。
id_token string ID Token です。後述の手順でこちらの Token をパースして認証結果を検証することになります。

Error Response

リクエスト失敗時にはエラー内容が JSON で返されます。 40x 系のエラーの場合は、同じ Authorization Code を使って Token Request をリトライしても同じくエラーになりますので、認可リクエストからやり直すようにしてください。

ID Token の検証

OpenID Connect の ID Token は、JSON Web Token (JWT) という仕様にしたがって OPTiM Store によって署名が付与された JSON データです。

JWT の仕様はこのドキュメントの冒頭で紹介したサイトで翻訳版およびライブラリリストが公開されています。

また以下のサイトでも、各言語ごとの JWT ライブラリが紹介されているので、参考にしてください。

  • https://jwt.io

以下に Ruby による ID Token デコード用のコンセプトコードを記載します。

require 'json-jwt'

id_token = JSON::JWT.decode '<id-token>', :skip_verification
# {
#   "iss": "https://store-xyz-federation.optim.co.jp",
#   "aud": "<your-client-id-for-the-tenant>",
#   "sub": "<optim-store-user-guid>",
#   "nonce": "<session-binded-opaque-value>",
#   "auth_time": 1464320207,
#   "iat": 1464320208,
#   "exp": 1464320508
# }

ID Token の中には以下のような属性値が入っています。

key description
iss Token 発行者 (issuer) の識別子です。https://store-xyz-federation.optim.co.jp 固定です。
aud Token 受信者 (audience) の Client ID です。
sub 認証されたユーザー様 (subject) の OPTiM Store 上の GUID です。
nonce 認可リクエスト時に御社サービスが指定した値がそのまま含まれます。
auth_time OPTiM Store 上でのユーザー様の最終ログイン日時 (authenticated_at) を示す Unix Timestamp です。強制認証リクエストを送信した場合には、リクエストパラメータの改ざんによる強制認証回避を防ぐため、この値が直近の日時であることを確認してください。
iat ID Token の生成日時 (issued_at) を示す Unix Timestamp です。
exp ID Token の有効期限 (expires_at) を示す Unix Timestamp です。

ID Token に含まれる上記の属性値を以下の通り検証してください。

  • iss が https://store-xyz-federation.optim.co.jp と一致すること。
  • aud が該当テナントに発行された Client ID と一致すること。
  • nonce が認可リクエスト送信時に指定した値と一致すること。
  • exp が未来の日時であること。
  • iat が現在もしくは過去の日時であること。
  • 強制認証要求時には auth_time が直近の日時 (5秒以内等) であること。

なお、OPTiM Store Token Endpoint へのリクエスト時に TLS サーバ認証を行うことで、そのレスポンスは OPTiM Store サーバーから返却されたことが保障されるため、ID Token 自体の署名検証は省略可能です。

ID Token 検証が成功したら、該当テナント内に存在する sub に紐付いたユーザー様を認証済としてください。

sub 値に紐付いたユーザー様は、事前にプロビジョニング (SCIM) API 経由で登録されているはずです。