Prepared for Financial-grade API Hands-on 2019-11-21

1. 2019-11-21
Authleteで体験する金融グレードAPI (FAPI)
Authlete, Inc.

2. 2
• 実際に手を動かしながらサーバー側の動作
を理解するハンズオン形式の勉強会です
• サーバーとクライアントとの間でやりとり
される OAuth / OIDC のメッセージを確認
しながら、サーバーが何をするのかを理解
していきます
• 「Authlete（オースリート）」を用いるこ
とにより、短時間で効率的な実習を目指し
ます
Welcome!

3. Financial-grade API (FAPI) 概要

4. “OAuth 2.0” の基本的なシーケンス
(AuthorizationCode GrantFlow / Bearer Token)
4
Resource
Owner
User Agent Client
Authorization
Server
Resource
Server
（スタート）
(OAuth) 認可リクエスト
(OAuth) 認可レスポンス
(OAuth)
トークン
リクエスト
(OAuth)
トークン
レスポンス
(OAuth)
API
リクエスト
(OAuth)
API
レスポンス
（完了）
ユーザー認証・
アクセス承認
認可
リクエスト
認可
コード
認可
コード
アクセス
トークン
アクセス
トークン
APIレスポンス
• 認可リクエストを受け付け
たら認可コードを返す
• 認可コードをもらったら
アクセストークンを返す
• アクセストークンつきの
APIリクエストを受け付け
てレスポンスを返す

5. セキュアな “OAuth Dance” を踊るには
1. 「認可リクエスト」「認可
コード返却」の真正性の担保
2. 「アクセストークン」取得時
におけるリクエスト元の確認
3. APIアクセスにおける「アク
セストークン」行使者の限定
5
利用者 Fintech企業 金融機関
ユーザー Webブラウザ Webサイト
認可
サーバー
APIサーバー
認可
リクエスト
認可
コード
認可
コード アクセス
トークン
アクセス
トークン
APIレスポンス
ログインして
連携を許可
金融機関との
連携を開始
連携完了

6. 6
• 金融 API 向けの OAuth 2.0 適用プラクティス
• さまざまな立場の専門家が仕様策定に集結
– OAuth / OpenID Connect 仕様策定者
– 金融機関
– サードパーティ（Fintech事業者）
– セキュリティ研究者
– ソリューションベンダー
– …
Financial-grade API (FAPI)
Source: https://openid.net/w g/fapi/

7. FAPIセキュリティ・プロファイル
• Part 1 (Read Only)
– OAuth 2.0 適用のプラクティス
– OAuth 2.0 拡張仕様
– OIDC によるユーザー識別子の授受
• Part 2 (Read & Write): OIDC の積極
的な活用 + 新たな拡張仕様
– Request Object, Hybrid Flow, MTLS,
OAUTB
– JARM
7
OIDC拡張仕様
OIDCプラクティス
OAuth2拡張仕様
OAuth2プラクティス
Part1(ReadOnly)
Part2(Read&Write)

8. • 認可リクエスト / レスポンスの送信者
詐称・改ざん防止
– Request Objectの利用
– Hybrid FlowもしくはJARMの利用
• 認可コードの漏洩・盗用防止
– redirect_uriの厳密な管理
• クライアントのなりすまし防止
– Mutual TLSもしくはJWTによる
クライアント認証
• トークンの漏洩・盗用防止
– OAUTB（トークン・バインディング）
もしくはMTLS（双方向TLS接続への
バインド）の利用
FAPIにおける “OAuth Dance” の改善・改良
Resource
Owner
User Agent Client
Authorization
Server
Resource
Server
（スタート）
(OAuth) 認可リクエスト
(OAuth) 認可レスポンス
(OAuth)
トークン
リクエスト
(OAuth)
トークン
レスポンス
(OAuth)
API
リクエスト
(OAuth)
API
レスポンス
（完了）
ユーザー認証・
アクセス承認
認可
リクエスト
認可
コード
認可
コード
アクセス
トークン
アクセス
トークン
APIレスポンス
8

9. リクエストオブジェクト
OIDC認証リクエストへの署名や暗号化
9
Resource
Owner
User Agent Client
Authorization
Server
Resource
Server
OIDC認証リクエスト
• 値渡し
• 参照渡し
リクエストオブジェクトのクレーム
{
"iss": "s6BhdRkqt3",
"aud": "https://server.example.com",
"response_type": "code id_token",
"client_id": "s6BhdRkqt3",
"redirect_uri": "https://client.example.org/cb",
"scope": "openid",
"state": "af0ifjsldkj",
"nonce": "n-0S6_WzA2Mj",
"max_age": 86400,
"claims":
{
"userinfo": { … "email": {"essential": true},…},
"id_token": { "gender": null, …
"acr": {"values": ["urn:mace:incommon:iap:silver"]}
}
}
}
GET /authorize?request=eyJhbGciOiJSUzI1NiIsImtpZCI6Imsy
YmRjIn0.ew0KICJpc3MiOiAiczZCaGRS…
GET /authorize?
request_uri=%3A%2F%2Fclient.example.org%2Frequest.jwt…
リクエストオブジェクト生成

10. Resource
Owner
User Agent Client
Authorization
Server
Resource
Server
フラグメント
取得
フラグメント
送信
(フラグメント）state,
code, id_token#
state, code,
id_token
Hybrid Flow
認可コードとIDトークンを認可EPから返却
10
認可リクエスト
GET /authorize
?response_type=code%20id_token
[…]
&state=af0ifjsldkj
Detached Signatureによる検証
トークンリクエスト
トークンレスポンス
code
AT, RT,
ID Token
認可レスポンス
HTTP/1.1 302 Found
Location: https://api.mytpp.com/cb#
code=SplxlOBeZQQYbYS6WxSbIA
&id_token=eyJ0 ... NiJ9.eyJ1c ...
I6IjIifX0.DeWt4Qu ... ZXso
&state=af0ifjsldkj
Detached Signature生成

11. Detached Signature
検証用の値に署名して本文と別に返却
11
Resource
Owner
User Agent Client
Authorization
Server
Resource
Server
認可レスポンス
HTTP/1.1 302 Found
Location: https://api.mytpp.com/cb#
code=SplxlOBeZQQYbYS6WxSbIA
&id_token=eyJ0 ... NiJ9.eyJ1c ...
I6IjIifX0.DeWt4Qu ... ZXso
&state=af0ifjsldkj
IDトークン（SignedJWT）を検証した上で、c_hash,
s_hashを抽出し、それぞれをもとにcode,stateを検証
{ …
"s_hash": "76sa5dd",
"c_hash": "asd097d” …
}
code=SplxlOBeZQQYbYS6WxSbIA
state=af0ifjsldkj
state
(フラグメント）state, code,
id_token (s_hash, c_hash, 署名)
クレームセット
{ …
"s_hash": "76sa5dd",
"c_hash": "asd097d” …
}
IDトークン（Signed JWT）生成
state, code の値が確定
s_hash, c_hash生成
#
IDトークン（Signed JWT）として
検証できた（改ざんされていない）値
クエリパラメーターとして
受け取った値

12. JARM
JWT SecuredAuthorizationResponseMode
for OAuth 2.0
12
Resource
Owner
User Agent Client
Authorization
Server
Resource
Server
response (code, state, 署名)
code
AT, RT,
ID Token
認可リクエスト
GET /authorize?
response_type=code&response_mode=jwt&[…]
認可レスポンス
HTTP/1.1 302 Found
Location: https://client.example.com/cb?
response=eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9.
eyJpc3MiOiJodHRwczovL2FjY291bnRzLmV4YW1wbGUuY29tIiwiYXVkI
joiczZCaGRSa3F0MyIsImV4cCI6MTMxMTI4MTk3MCwiY29kZSI6IlB5eU
ZhdXgybzdRMFlmWEJVMzJqaHcuNUZYU1FwdnI4YWt2OUNlUkRTZDBRQSI
sInN0YXRlIjoiUzhOSjd1cWs1Zlk0RWpOdlBfR19GdHlKdTZwVXN2SDlq
c1luaTlkTUFKdyJ9.
HkdJ_TYgwBBj10C-aWuNUiA062Amq2b0_oyuc5P0aMTQphAqC2o9WbGSk
pfuHVBowlb-zJ15tBvXDIABL_t83q6ajvjtq_pqsByiRK2dLVdUwKhW3P
_9wjvI0K20gdoTNbNlP9Z41mhart4BqraIoI8e-L_EfAHfhCG_DDDv7Yg
トークンリクエスト
トークンレスポンス
Signed JWT検証
クレームセット
{
"iss": "https://accounts.example.com",
"aud": "s6BhdRkqt3",
"exp": 1311281970,
"code": "PyyFaux2o7Q0YfXBU32jhw.5FXSQpvr8akv9CeRDSd0QA",
"state": "S8NJ7uqk5fY4EjNvP_G_FtyJu6pUsvH9jsYni9dMAJw"
}
response（SignedJWT）生成

13. MTLSを用いたクライアント認証
クライアントから提示されたX.509証明書の「サブジェクト識別名（DN）」を登録値と照合
13
Resource
Owner
User Agent Client
Authorization
Server
Resource
Server
トークンリクエスト
• TLS相互認証を行ってクライアントのX.509証明書を取得し、
その証明書のサブジェクトDNをもとにクライアントを認証
• リクエスト内のclient_idの値からクライアントを識別
• そのクライアント情報として事前登録されている「証明書の
サブジェクトDN」の値と照合し認証
トークンレスポンス
• 証明書に結びつけた（バインドした）アクセストークンを返却
APIリクエスト
• TLS相互認証を行いクライアントのX.509証明書を取得
• 証明書とアクセストークンの結びつき（バインド）を確認
X.509 PKC +
client_id

14. MTLSによる“Holder of Key”
トークンリクエスト時のクライアント証明書に、発行するアクセストークンをバインド
14
Resource
Owner
User Agent Client
Authorization
Server
Resource
Server
トークンリクエスト
• TLS相互認証を行ってクライアントのX.509証明書を取得し、
その証明書のサブジェクトDNをもとにクライアントを認証
• リクエスト内のclient_idの値からクライアントを識別
• そのクライアント情報として事前登録されている「証明書の
サブジェクトDN」の値と照合し認証
X.509 PKC +
code + client_id
client_id
code
トークンレスポンス
• 証明書に結びつけた（バインドした）アクセストークンを返却
AT, RT
APIリクエスト
• TLS相互認証を行いクライアントのX.509証明書を取得
• 証明書とアクセストークンの結びつき（バインド）を確認
• トークンに含まれる or イントロスペクションの結果と
して得られる、証明書の「サムプリント」を利用
X.509 PKC + AT
X.509 PKC +
RT + client_id

15. ハンズオン

16. API認可・公開基盤
APIクライ
アント
既存システム
Authlete: OAuth/OIDC サーバーのバックエンド
16
Webサイト
携帯端末
ネットワーク
デバイス
認可サーバー
認可ロジック
（認可判定）
ユーザー
認証
同意確認 権限管理
APIサーバー
/data /function /transaction
Authlete
認可
バック
エンド
API 認可情報
DB
API認可リクエスト
（トークン取得）
APIアクセス
(トークン利用)
認可状態確認
（トークン検証など）
OAuth/OIDC処理リクエスト（認可コード/トークン発行など）
認可
フロント
エンド
既存の認証/同意/
権限等と認可サー
バーとを分離
Authleteに依存することなく
自由に認可ロジックを実装可能
APIサーバと
認可サーバの
構築・運用を分離
面倒なOAuth/OIDC処理
と認可情報（トークン）
管理を外部化
/…
認可サーバー
構築に必要な
ライブラリを
OSSにて提供

17. 17
Authlete API: プロトコル処理とトークン管理
Resource
Owner
User Agent Client
Authorization
Server
Resource
Server
（スタート）
(OAuth) 認可リクエスト
(OAuth) 認可レスポンス
(OAuth)
トークン
リクエスト
(OAuth)
トークン
レスポンス
(OAuth)
API
リクエスト
(OAuth)
API
レスポンス
ユーザー認証・
アクセス承認
Authlete API
認可リクエスト
処理
認可コード生成
トークンリクエスト
処理
アクセス
トークン
検証
/auth/authorizationPOST
/auth/authorization/issuePOST
/auth/tokenPOST
/auth/introspectionPOST

18. 18
FAPIモード有効化による主な変更点
Resource
Owner
User Agent Client
Authorization
Server
Resource
Server
（スタート）
(OAuth) 認可リクエスト
(OAuth) 認可レスポンス
(OAuth)
トークン
リクエスト
(OAuth)
トークン
レスポンス
(OAuth)
API
リクエスト
(OAuth)
API
レスポンス
ユーザー認証・
アクセス承認
Authlete API
認可リクエスト
処理
認可コード生成
トークンリクエスト
処理
アクセス
トークン
検証
/auth/authorizationPOST
/auth/authorization/issuePOST
/auth/tokenPOST
/auth/introspectionPOST
• リクエストオブジェクト使用の必須化
• ハイブリッドフロー or JARM要求の必須化
• 認証コンテキストリファレンス（acr）クレームの必須化
• ハイブリッドフロー or JARMでのレスポンス生成
• クライアント証明書送付の必須化
• クライアント証明書送付の必須化

19. 19
• “FAPI - Part 2: Read and Write API
Security Profile” に対応した認可
サーバー/アイデンティティプロバイ
ダーを構築するために
• 認可リクエストからAPIアクセスまで
順番にAuthleteのFAPI設定を実施し
• FAPIのセキュリティ条項を確認して
いきます
Authleteチュートリアル: FAPI Basics
https://www.authlete.com/ja/developers/tutorial/fapi/

20. 全体の構成とリクエスト・レスポンスの流れ
20
User Agent
Client
Resource
Server
Authorization
Server
Authlete API
End User API Client API Server Authlete
Resource
Owner
/auth/authorizationAPI
/auth/authorization/issue API
/auth/token API
/auth/introspectionAPI4. TokenResponse
Including Certificate-
bound AccessToken
5. API Request With
Certificate-bound Access
Token And Client
Certificate(Mutual TLS)
0. Start
1’. User Authentication
And Consent
1. Authorization
Request
Using “Request
Object”
1
4
5
2
2. Authorization
Response Including
Authorization Code In
Fragment
3. Token
RequestWith
Client Certificate
(Mutual TLS)
3
認可サーバー
（+ リソースサーバー）の
立場になり
クライアント（+ ユーザー
エージェント）から受け付けた
（と仮定する）リクエストを
Authlete API を活用して
処理します

21. 21
• (Request from Client to AS via UA)
– FAPI準拠の認可リクエストを送信
• Request from AS to Authlete
– リクエストパラメーターをAuthleteに
そのまま転送
• Response from Authlete to AS
– リクエストパラメーターを検証
– 「チケット」（検証成功時）と、認可
サーバーがクライアントに返却する
「レスポンスの内容」とその伝達手段
を回答
• (Response from AS to Client via UA)
– チケットをユーザーセッションに保存
– 「レスポンスの内容」をクライアント
に返却
1. 認可リクエスト
User Agent
Client
Resource
Server
Authorization
Server
Authlete API
End User API Client API Server Authlete
Resource
Owner
Authorization
Request
/auth/authorization API

22. 22
• (Interaction between Client and AS)
– ユーザー認証・アクセス同意
• Request from AS to Authlete
– 「チケット」と「ユーザー識別子」を
送信
• Response from Authlete to AS
– 認可サーバーがクライアントに返却す
る「レスポンスの内容」とその伝達手
段を回答
• (Response from AS to Client)
– チケットをユーザーセッションに保存
– 「レスポンスの内容」をクライアント
に返却
2. 認可レスポンス
User Agent
Client
Resource
Server
Authorization
Server
Authlete API
End User API Client API Server Authlete
Resource
Owner
Authorization
Response
/auth/authorization/issue
API

23. 23
• (Request from Client to AS)
– 双方向TLS接続を確立
• 認可サーバーがクライアント証明書を検証
– FAPI準拠のトークンリクエストを送信
• Request from AS to Authlete
– 双方向TLS接続からクライアント証明書を抽出
– リクエストパラメーターとクライアント証明書（PEM
形式）をAuthleteにそのまま転送
• Response from Authlete to AS
– リクエストパラメーターを検証
– クライアント証明書のSubject DNを検証
– Subject DNにひもづくトークンを生成
– 認可サーバーがクライアントに返却する「レスポンス
の内容」とその伝達手段を回答
• (Response from AS to Client)
– 「レスポンスの内容」をクライアントに返却
3 & 4. トークンリクエスト/レスポンス
User Agent
Client
Resource
Server
Authorization
Server
Authlete API
End User API Client API Server Authlete
Resource
Owner
Token
Request
/auth/token API

24. 24
• (Request from Client to RS)
– 双方向TLS接続を確立
• リソースサーバーがクライアント証明書を検証
– アクセストークンを含むAPIリクエストを送信
• Request from RS to Authlete
– 双方向TLS接続からクライアント証明書を抽出
– アクセストークンとクライアント証明書（PEM形
式）をAuthleteにそのまま転送
• Response from Authlete to RS
– クライアント証明書のSubject DNを検証
– Subject DNとアクセストークンのひもづけを検証
– アクセストークンの有効性と、それにひもづく情報
を回答
• (Response from RS to Client)
– Authleteからの回答をもとにアクセス可否やレスポ
ンス内容を決定し応答
5. APIリクエスト
User Agent
Client
Resource
Server
Authorization
Server
Authlete API
End User API Client API Server Authlete
Resource
Owner
API
Request
/auth/introspection
API

25. 25
• 初期設定以降の各章を
ステップバイステップ
で実習していきます
本日の進めかた
• はじめに
• 構成
• FAPI を用いた API クライアントと API サーバーとの間のやりとり
• 初期設定
• 新規 Authlete サービスとそのクライアントの追加
• 初期設定後の動作確認
• 認可リクエストの FAPI 対応
• リクエストオブジェクトの設定
• 認証コンテキストリファレンス (acr) の設定
• 認可レスポンスの FAPI 対応
• ID トークンの署名アルゴリズムの変更
• トークンリクエストの FAPI 対応
• TLS クライアント認証の設定
• トークンレスポンスの FAPI 対応
• Holder of Key の設定
• 設定完了後の実行例
• 認可リクエスト
• 認可レスポンス
• トークンリクエスト/レスポンス
• API リクエスト
• まとめ

26. ふりかえり

27. 27
• 本日は、Financial-grade API (FAPI) 仕
様が規定するセキュリティ条項の要点
を、実習を通して確認しました
• Authleteの活用によりFAPI対応認可
サーバーをシンプルに実装できること
を感じていただければ幸いです
まとめ

28. 28
• Financial-grade API (FAPI) - Authlete
https://www.authlete.com/ja/developers/fapi/
– FAPI とは
– FAPI セキュリティプロファイル
– Authlete と FAPI
リソース

29. Thank You
www.authlete.com
www.linkedin.com/in/tatsuokudo