シングルサインオンAPI利用の前提条件について

シングルサインオンAPIの利用には、makeshop APIの利用前提に加えて以下のRFCへの理解が求められます。

• The OAuth 2.0 Authorization Framework
• OpenID Connect 1.0（draft 17）
• JSON Web Token (JWT)
• OpenID Connect Session Management

APIの活用には高度な技術や専門的な知識が必要となりますので、本ドキュメントを一読の上利用ご検討をお願いいたします。

動作概要

当APIを利用することで、外部サイトでmakeshopの認証機構を利用することができます。
外部サイトとmakeshopでシングルサインオンします。

API群でシングルサインオン機能を提供します。

1. ユーザー認証API（ログイン要求）
   外部サイトでログインが必要な場合、指定URLへクライアントID・リダイレクト先URLと共にmakeshopへログイン要求を行います。
   makeshop上のログイン画面でログインが完了した場合、認可コードと共にリダイレクト先へ遷移します。
   この時点でmakeshop上ではログインが完了しています。
2. アクセストークン発行API
   認可コードによってアクセストークンおよびIDトークンを取得します。
   ※クライアントにて各トークンの検証処理を行っていただく必要があります。
3. 会員ID取得API
   取得したアクセストークンで会員情報にアクセスし、ログイン中の会員IDを取得します。
4. ログアウト連携API
   取得したアクセストークンで会員情報にアクセスし、ログイン中の会員IDを取得します。

備考

ログアウトに関する動作

• アクセストークンの有効期限が切れている場合はNGを返す。必要であれば、外部サイト側で再ログインを要求する

makeshopでログアウトする条件

• 明示的にログアウトの操作をした場合
• ブラウザを終了した場合
• ログインから30日間放置した場合

動作イメージ（makeshopに未ログインのとき）

動作イメージ（MakeShopにログイン済みのとき）

動作イメージ（ログアウト連携）

ご利用前の準備

シングルサインオンAPIを利用するには、ショップ管理画面でシングルサインオンの利用設定を行ってください。

シングルサインオンを利用する外部サイトを登録・修正します。

ログイン画面の動作制限（PC/スマホ共通）

• PC・スマホは接続元の端末を判別してそれぞれのログイン画面へ自動振り分けられます。
• 複数ショップ連携を利用している場合、ログインが成功している場合はどのショップでもログイン状態となります。
• GoogleAnalyticsの計測には対応していません。
  GoogleAnalyticsの計測に対応致しました。（2020年5月28日更新）

※PHPセッションを利用する際の注意事項
makeshopではセッション管理に「PHPSESSID」を使用しています。
WordPressなどmakeshop外のサービス、サイトで同名称のCookieを使用すると、
ログインや購入手続きなどでにエラーとなる可能性があります。

• 「PHPSESSID」以外の名称を利用する
• 「PHPSESSID」をそのまま用いる場合はドメインが変わってもcookie情報が引き継がれるよう

　HttpOnly属性、Secure属性、SmaeSite属性（none）を指定する

など対応をお願いします。

API仕様

注意事項

• 文字コード
  UTF-8をご利用ください。
• APIリクエスト先URL
  APIのリクエストは、全て管理画面の収容サーバーへ行います。管理画面へログイン後にURLをご確認ください。

ユーザー認証API

ユーザーがログインID、クライアントが認可コードを取得するAPIです。

リクエストURL

https://管理画面のドメイン/api/openid/login/

SNIにご対応ください。

リクエストパラメータ

• ※パラメータはPOSTでURLエンコードした値を送信してください。

レスポンス

管理画面で設定したリダイレクト先URLにパラメータを付与してリダイレクトします。

サンプルレスポンス

https://example.jp/auth/mypage/?code=xxxxxxxxxxxxxxxxxxxxxx&state=aaaaaaaaaaaaaa

• ※レスポンスの文字コードはUTF-8です

クライアント検証

クライアント（外部アプリケーション）は以下に従ってレスポンスを検証する。（フェーズ1の仕様から変更なし）

• クライアントは2回以上認可コードを使用してはならない。
• クライアントは認識できないレスポンスパラメーターを無視する。
• リクエストパラメータ「state」を設定した場合、レスポンス値と同一である事を確認する。
  ※リクエスト前のパラメータ「state」値は保存しておく必要がある。

アクセストークン発行API

クライアントがアクセストークンおよびIDトークンを取得するためのAPIです。

リクエストURL

https://管理画面のドメイン/api/openid/access_token.html

リクエストパラメータ

• ※パラメータはPOSTでURLエンコードした値を送信してください。

レスポンス

レスポンスはJSON形式で返却されます。

サンプルレスポンス

{
    "access_token" : "aaaaaaaaaaaaaaaaa",
    "token_type" : "Bearer",    //固定値
    "expires_in" : 3600,        //固定値
    "scope" : "login_info"      //固定値   
    "id_token":"eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJpc3MiOiJodHRwczpcL1wvZGV2Lm1ha2VzaG9wLmpwIiwic3ViIjoiMTEwMTAyNTcxODU5MDA4NjIxODEzIiwiYXVkIjoidGVlMmxoNW43NXp2a2pvaDV0ajYybXNoNG84d2I4OThxZ3V2NHd2eCIsImV4cCI6MTQyMTgyMDUzMiwiaWF0IjoxNDIxODE2OTMyLCJhdXRoX3RpbWUiOjE0MjE4MTY1MTIsIm5vbmNlIjoiclJoTUI5SXJGYm82eEhCYThvbjRSeSIsImF0X2hhc2giOiJ4YjBPUEh0aVRRR195MVlzQ0YwLVVnIn0.FkNTxT59BCUqwkXgYcSF1HCyaHc1u7zbR-coIyMDSSo"
}

• ※レスポンスの文字コードはUTF-8です

IDトークン概要

IDトークン構造図

IDトークンは以下のデータ構造として表現される。

※参照:JSON Web Token (JWT)

IDトークン生成方法

HMAC-SHA256アルゴリズムで署名する。以下の手順で署名し、JWTを生成する。

1. JSON形式のヘッダ部、ペイロード部をそれぞれBase64URLエンコードする。
2. 1のヘッダ部、ペイロード部を.で連結し、こちらをメッセージ文字列とする。
3. client_secretを共通鍵として、メッセージ文字列をアルゴリズムHMAC-SHA256によってシグネチャー生成する。
4. 3で生成したシグネチャーをBase64URLエンコードする。
5. 2で生成したメッセージ文字列と4のシグネチャーを.で連結し、JWTとする。

IDトークン ヘッダ部

IDトークン ペイロード部（クレーム・セット）

IDトークン サンプル

メッセージ（ヘッダー：JSON）

{"typ":"JWT","alg":"HS256"}

メッセージ（クレーム・セット：JSON）

  {
    "iss":"https:\/\/dev.makeshop.jp",
    "sub":"110102571859008621813",
    "aud":"tee2lh5n75zvkjoh5tj62msh4o8wb898qguv4wvx",
    "exp":1421820532,
    "iat":1421816932,
    "auth_time":1421816512,
    "nonce":"rRhMB9IrFbo6xHBa8on4Ry",
    "at_hash":"xb0OPHtiTQG_y1YsCF0-Ug"
  }

メッセージ（ヘッダーおよびクレーム・セットをBase64URLエンコード、.連結後）

eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9
.
eyJpc3MiOiJodHRwczpcL1wvZGV2Lm1ha2VzaG9wLmpwIiwic3ViIjoiMTEwMTAyNTcxODU5MDA4NjIxODEzIiwiYXVkIjoidGVlMmxoNW43NXp2a2pvaDV0ajYybXNoNG84d2I4OThxZ3V2NHd2eCIsImV4cCI6MTQyMTgyMDUzMiwiaWF0IjoxNDIxODE2OTMyLCJhdXRoX3RpbWUiOjE0MjE4MTY1MTIsIm5vbmNlIjoiclJoTUI5SXJGYm82eEhCYThvbjRSeSIsImF0X2hhc2giOiJ4YjBPUEh0aVRRR195MVlzQ0YwLVVnIn0

メッセージをHMAC-SHA256でシグネチャー生成（結果をBase64URLエンコード）

FkNTxT59BCUqwkXgYcSF1HCyaHc1u7zbR-coIyMDSSo

• ※client_secret=x5k6osnhze6tnz5zonhcdswzcjjjo4pwltswv43uを共通鍵とする。

IDトークン（メッセージとシグネチャー生成を.連結）

eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9
.
eyJpc3MiOiJodHRwczpcL1wvZGV2Lm1ha2VzaG9wLmpwIiwic3ViIjoiMTEwMTAyNTcxODU5MDA4NjIxODEzIiwiYXVkIjoidGVlMmxoNW43NXp2a2pvaDV0ajYybXNoNG84d2I4OThxZ3V2NHd2eCIsImV4cCI6MTQyMTgyMDUzMiwiaWF0IjoxNDIxODE2OTMyLCJhdXRoX3RpbWUiOjE0MjE4MTY1MTIsIm5vbmNlIjoiclJoTUI5SXJGYm82eEhCYThvbjRSeSIsImF0X2hhc2giOiJ4YjBPUEh0aVRRR195MVlzQ0YwLVVnIn0
.
FkNTxT59BCUqwkXgYcSF1HCyaHc1u7zbR-coIyMDSSo

クライアント検証

クライアント（外部アプリケーション）は以下に従ってレスポンスを検証する。

• IDトークンを検証する。

1. 暗号化されたIDトークンを、以下の手順で署名チェックし、複合化する。
   • JWTのヘッダ部とペイロード部とシグネチャー部の3つを.（ドット）で分割する。
   • 各値をBase64URLデコードする。
   • ヘッダー部のtypパラメータがJWT、algがHS256となっている事を確認する。
   • client_secretを共通鍵として、メッセージ文字列をアルゴリズムHMAC-SHA256によってシグネチャー生成する。
     ※メッセージ文字列：ヘッダー部とペイロード部を.（ドット）で連結した値（Base64URLデコード前の文字列）
   • 上記生成した値とシグネチャー部が一致することを確認する。
2. ペイロード部issがhttps://管理画面のドメインと同一である事を確認する。
   例）shop1の場合：https://shop1.makeshop.jp
3. ペイロード部audがclient_idと同一である事を確認する。
4. ペイロード部expが現在時刻のタイムスタンプより前である事を確認する。
5. ペイロード部iatが発行後10分以内（現在時刻のタイムスタンプ値 マイナス600秒）にレスポンスがあった事を確認する。
   ※ユーザ認証APIリクエストから10分以内（認可コードの有効期限内）にアクセスした事を確認する。
6. ペイロード部nonce値がユーザ認証APIリクエスト時に送信したnonce値と同一であることを確認する。
   • nonce値が、保存してあるnonceと同一である事を確認する。
   • リプレイアタックを防止するため、確認済のnonce値は破棄する。
     ※リクエスト前のnonce値はクライアント（外部アプリケーション）側のデータベース等に保存して管理する必要がある。

• アクセストークンを検証する。

1. レスポンスのaccess_tokenをハッシュアルゴリズムSHA-256（IDトークンのヘッダ中のalgパラメータで指定）にて、ASCIIバイト列（バイナリデータ）にハッシュ化する。
2. ハッシュの左半分（16バイト）を取り出し、それをBase64URLエンコードする。
3. IDトークンのペイロード部のat_hashクレームの値が生成された値と同一である事を確認する。at_hashについて詳しくは：3.2.2.10. ID Token

会員ID取得API

クライアントが会員IDを取得するためのAPIです。

リクエストURL

https://管理画面のドメイン/api/openid/user_login_info.html

リクエストパラメータ

• ※パラメータはPOSTでURLエンコードした値を送信してください。

レスポンスパラメータ

レスポンスはJSON形式で返却されます。

サンプルレスポンス

{
    "sub": "110102571859008621813",
    "member_id" : "1323213521"
}

• ※レスポンスの文字コードはUTF-8です
• ※メールアドレスでログインした場合でも、makeshopに登録された会員IDを返却します。

クライアント検証

クライアント（外部アプリケーション）は以下に従ってレスポンスを検証する。

• IDトークンで取得したsubクレームが、当レスポンスのsubと同一である事を確認する。

ログアウト連携API

サイト間でログアウト連携するためのAPIです。

リクエストURL

https://管理画面のドメイン/api/openid/logout/

リクエストパラメータ

• ※パラメータはPOSTでURLエンコードした値を送信してください。
• ※バリデーション方法

1. IDトークンのclient_id（=audクレーム）にてクライアントを認証する。
2. パラメータpost_logout_redirect_uriの値の検証、およびクライアントにて事前登録されているかどうか確認する。

レスポンスパラメータ

レスポンス方法

• ログアウトが正常の場合（=成功レスポンス）
  • リクエストで指定したリダイレクトエンドポイントpost_logout_redirect_uriへ、レスポンスパラメータをURLクエリパラメータとして付与してリダイレクトする。
• ログアウトでエラーの場合
  • HTTP 404エラーとする。

クライアント検証

クライアント（外部アプリケーション）は以下に従ってレスポンスを検証する。

• クライアント（外部アプリケーション）は以下に従ってレスポンスを検証する。
• クライアントは認識できないレスポンスパラメーターを無視する。
• リクエストパラメータstateを設定した場合、レスポンス値と同一である事を確認する。
• ※リクエスト前のパラメータstate値は保存しておく必要がある。

エラーレスポンス

エラーが発生した場合は、APIによってレスポンスの内容が異なります。

エラーレスポンスの返却先・形式

【ユーザー認証API】 404エラー

【アクセストークン発行API／会員ID取得API】 呼び出し元にJSON形式で返す

サンプルレスポンス（JSON形式の場合）

{
    "error_code" : "invalid_request"
}

• ※レスポンスの文字コードはUTF-8です

シングルサインオン仕様説明書Ver.2.2.0.pdf