OAuth2 Authorization Code Flow による認証を行い、特定の API エンドポイントにアクセスする権限を取得する。
各 API エンドポイントには、アクセスに必要な権限(スコープ)が指定されている。クライアントソフトウェアは、指定された全ての権限について本エンドポイントから認可された時にのみ、当該の API エンドポイントにアクセスできる。本エンドポイントへのアクセスは、API エンドポイントへのアクセスごとや権限ごとに行う必要は無く、複数の API エンドポイントで必要な権限をまとめて認可されうる。各権限は、次の全てを満たした場合に認可される。
- クライアントソフトウェアの登録時に、マネーフォワードがクライアントソフトウェアに対してその権限を与えている。
- クライアントソフトウェアが本エンドポイントにアクセスした時に、要求のパラメーターにその権限が含まれている。
- クライアントソフトウェアがその権限を持ってユーザーの情報にアクセスすることをユーザーがウェブブラウザを通じて認める。
本エンドポイントから権限の認可を受けるだけでは API エンドポイントを使うことは出来ず、戻り値に含まれる code の値を使ってさらにアクセストークンを得る必要がある。
クライアントソフトウェアが秘密の文字列を生成して要求時にパラメーター state の値として渡すと、応答にも同じ値が返され、クライアントソフトウェアがその同一性を検証することによって、応答がマネーフォワードのなりすましからのものでないことの目安にできる。
GET https://moneyforward.com/oauth/authorize
| 場所 | 随意性 | 名称 | 内容 |
|---|---|---|---|
| クエリー | 必須 | response_type |
code |
| クエリー | 必須 | client_id |
クライアントソフトウェア登録時にマネーフォワード担当者がお渡ししたクライアントソフトウェア固有の文字列 |
| クエリー | 必須 | redirect_uri |
クライアントソフトウェアの登録時に指定された、クライアントソフトウェア上のアクセスポイント |
| クエリー | 必須 ※1 | state |
リクエストとコールバックの間で状態を維持するために使用するランダムな値。マネーフォワードはリダイレクトによってクライアントに処理を戻す際にこの値を付与する。当パラメーターは CSRF を防ぐために用いる |
| クエリー | 必須 | scope |
このあと発行されるトークンを使ってアクセスする API エンドポイントに必要な全ての権限を空白でつないだもの |
※1 state パラメータはは OAuth2.0 標準規格の上では推奨ですが、CSRF 対策として当社との認可フロー上においては必ず付与して下さい。
GET https://moneyforward.comoauth/authorize?response_type=code&client_id=5e82f05f322845b8c96d5f8b0fbe19bd23ecadb69b700e9d011027b490de0b0b&redirect_uri=http%3A%2F%2Flocalhost%3A1234%2Fcallback&state=hoge&scope=openid%20email
要求をすると認可画面にリダイレクトされ、ユーザーがその画面上の説明に同意して「許可する」ボタンを押すと、次にredirect_urlにリダイレクトされる。その URL のクエリーに以下のパラメータ値が与えられる。
| 名称 | 内容 |
|---|---|
code |
認可を受けたことを示す、アクセストークンを得るために必要な秘密の文字列 |
state |
要求の state パラメーターの値 |
http://localhost:1234/callback?code=e885b973e64797bcf3342529d57cd2adca97a11f787ef9736ea92d8061e5aa59&state=NzHDXGuMme5c4GkCEd7TXUYebK0