Skip to main content

OAuth2 v1

概要#

DMDATA.JPでは、認可にOAuth2.0を使用します。 認可コードフロー/リフレッシュトークンフロー、インプリシットフロー、クライアント・クレデンシャルズフローをサポートしています。

RFC6749、RFC7009、RFC7636にて定義されている仕様に沿って認可サーバーは実装(一部コアな実装を除く)されています。

アカウント連携などの認証 (OpenID Connect) はサポートしていません。

OAuth クライアント#

OAuth2.0では、作成したアプリケーションごとにクライアント必要です。クライアントの発行は、認証情報よりできます。

また、リダイレクトURIや使用するフロー、製作者の公開連絡先、アプリケーションの公開URL、利用規約、プライバシーポリシーが必要です。

クライアントの種類#

OAuthではクライアントの種類が2つ定められており、「機密」と「公開」があります。

公開は、クライアントシークレットキーが保護できないWebアプリケーションや、ネイティブアプリケーションに使用します。 クライアント・クレデンシャルズフローは使用できません。

機密は、クライアントシークレットキーが保護できるごく限られたWebサーバーなどに使用します。

クライアントの種類が機密の場合、トークンエンドポイントにリクエストする際、シークレットキーが必要となります。

エンドポイント#

認可エンドポイント#

https://manager.dmdata.jp/account/oauth2/v1/auth

トークンエンドポイント#

https://manager.dmdata.jp/account/oauth2/v1/token

失効エンドポイント#

https://manager.dmdata.jp/account/oauth2/v1/revoke

認可コードフロー#

このフローではWebサーバーアプリケーションや、Webアプリ、ネイティブアプリケーション等に適しています。

認可エンドポイントに認可リクエストを送信し、ユーザーに認可されると、DMADTA.JPは登録されたリダイレクトURIに認可コードを送信します。

OAuth クライアントは、受け取った認可コードをトークンエンドポイントにアクセストークンを発行要求し、認可が完了すると、各種APIにアクセスできるアクセストークンを送信します。

また、セキュリティ対策のため、stateを必須としているほか、ネイティブアプリケーション(特にiOSやAndroid)においては認可コード横取り攻撃の対策のため、PKCE(Proof Key for Code Exchange)の実装を推奨します。

1. 認可コードを要求#

認可エンドポイントに各種パラメータを含めて要求します。

https://manager.dmdata.jp/account/oauth2/v1/auth
?client_id=CId.CCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCC
&response_type=code
&redirect_uri=https:%2F%2Fmanager.dmdata.jp%2Fcontrol%2Faccount
&response_type=query
&scope=telegram.list%20telegram.get.earthquake%20telegram.data
&state=abcd
&code_challenge=E9Melhoa2OwvFrEMTJguCHaoeK1t8URWbuGJSstw-cM
&code_challenge_method=S256
パラメータ名必須説明
client_idはいString
OAuth クライアント毎に割り当てられた、CId.で始まるID
response_typeはいString
認可コードフローでは、codeを指定する必要があります。
redirect_uriはいString
認可コードを送信するURIで、OAuth クライアントで指定されたリダイレクトURIを厳密に一致させる必要があります。
なお、指定されたリダイレクトURIが1個のみの場合は必須ではありません。
scopeはいString
ユーザーから認可を求めるスコープ(権限)。複数含める場合はスペースで区切ります。
response_modeオプションString
認可コードを送信する際に使用する場所を指定します。
queryfragmentform_postを指定でき、デフォルトではqueryが指定されています。
また、パラメータresponse_typetokenが含まれる場合queryは選択できません。
stateはいString
stateはCSRF対策の一環で実装が必須です。
またこの値は一意の値であり、64バイト以下である必要があります。
この値は認可コード発行時にリダイレクトURIと一緒に返答されます。
code_challengeオプションString
PKCEを使用し、認可コードを保護します。
パラメータcode_challenge_methodが含まれている場合必須です。
code_challenge_methodオプションString
code_challengeのエンコードを示すメソッド。
S256plainが使用できますが、S256を推奨します。

リクエストが送信されると、ユーザーへの認可要求ページが表示されます。ユーザーが認可すると、redirect_uriresponse_modeに基づき認可コードとstateを送信します。

成功した応答 response_mode=query#

https://manager.dmdata.jp/control/account
?code=ACe.AAAAAAAAAAAAAAAAAAAAAAAA
&state=abcd
パラメータ名説明
codeString
要求に対して発行されたACe.で始まる認可コード。
この認可コードを使用してアクセストークンを要求します。
この認可コードの有効期間は5分間です。
stateString
要求にあるstateと同じ値を返答します。
クライアントは要求に含めたstateと一致するかどうか検証する必要があります。

成功した応答 response_mode=fragment#

https://manager.dmdata.jp/control/account
#code=ACe.AAAAAAAAAAAAAAAAAAAAAAAA
&state=abcd

成功した応答 response_mode=form_post#

リダイレクトURIにPOSTを実行し、リクエストBody内にformとして送信します。

POST /control/account
Host: https://manager.dmdata.jp
Content-Type: application/x-www-form-urlencoded
code=ACe.AAAAAAAAAAAAAAAAAAAAAAAA
&state=abcd

エラー#

ユーザーが拒否したなど認可に失敗した場合、次のようにリダイレクトURIに送信します。

https://manager.dmdata.jp/control/account
?error=access_denied
&state=abcd

また、リダイレクトURIを特定できないか、認可ページ表示段階で失敗している場合は、リダイレクトは発生しません。

パラメータ名説明
errorString
エラーの際に使用するエラーコード。
error_descriptionString
エラーの際、どのような問題が発生しているか、具体的に記述したメッセージ。
stateString
要求にあるstateと同じ値を返答します。

返答するエラーコードは以下の通りです。

エラーコード説明
invalid_requestリクエストされたパラメーターが足りないか、パラメータの値が正しくありません。
invalid_clientリクエストされたclient_idが見つかりません。
invalid_redirect_uriリクエストされたredirect_uriが設定されたリダイレクトURIと一致しません。
invalid_scopeリクエストされたscopeが正しくない形式か、存在しないスコープが含まれています。
unauthorized_clientクライアントは指定された方法で認可コードを取得することを許可されていません。
access_deniedユーザーが認可を拒否しました。
recaptcha_verification_failedGoogle reCaptchaの検証に失敗。これを受け取った場合、もう一度認可フローを最初から実行する必要があります。
unsupported_response_type認可サーバーは、リクエストされたresponse_typeをサポートしていません。
unsupported_code_challenge_method認可サーバーは、リクエストされたcode_challenge_methodをサポートしていません。
no_signinユーザーがサインインしていません。通常このエラーは出現しません。
server_error内部エラーにより処理できません。

2. アクセストークンを要求#

認可コードを取得したら、次はトークンエンドポイントにアクセストークン発行要求を実行します。

トークンエンドポイントにPOST要求、フォームでデータを渡します。

POST /account/oauth2/v1/token
Host: https://manager.dmdata.jp
Content-Type: application/x-www-form-urlencoded
client_id=CId.CCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCC
&client_secret=CSt.SSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSS
&grant_type=authorization_code
&code=ACe.AAAAAAAAAAAAAAAAAAAAAAAA
&redirect_uri=https:%2F%2Fmanager.dmdata.jp%2Fcontrol%2Faccount
&code_verifier=dBjftJeZ4CVP-mB92K27uhbUJU1p1r_wW1gFWFOEjXk
パラメータ名必須説明
client_idはいString
OAuth クライアント毎に割り当てられた、CId.で始まるID
client_secretオプションString
OAuth クライアント毎に割り当てられた、CSt.で始まるシークレットキー。
クライアントの種類が「機密」の場合は必須です。
grant_typeはいString
認可コードフローでは、authorization_codeを指定する必要があります。
codeはいString
認可コード要求で取得したACe.で始まる認可コード。
redirect_uriオプションString
認可コード要求する際にパラメータに入力したredirect_uriを指定します。
code_verifierオプションString
認可コード要求時に、PKCEが使用されていた場合は必須です。

成功した応答#

{
"access_token": "ATn.TTTTTTTTTTTTTTTTTTTTTTTTTTTTTTTTTTTTTTTTTTTTTTTTTTTTTTTTTTTTTTTTTTTTTTTTTTTTTTTTTTTTTTT",
"token_type": "Bearer",
"expires_in": 21600,
"refresh_token": "ARh.RRRRRRRRRRRRRRRRRRRRRRRRRRRRRRRRRRRRRRRRRRR",
"scope": "telegram.list telegram.get.earthquake telegram.data"
}
パラメータ名説明
access_tokenString
ATn.で始まるアクセストークン。
token_typeString
アクセストークンの種類を示し、Bearerで固定です。
expires_inString
アクセストークンの有効期間(秒)。6時間有効です。
refresh_tokenString
アクセストークンの有効期限が切れた場合、このリフレッシュトークンを使用して、アクセストークンを再度発行できます。
リフレッシュトークンは、半年が有効期間ですが使用するごとに半年期限が延長されます。
scopeString
アクセストークンに付与されたスコープ。

エラー#

{
"error": "invalid_request",
"error_description": "The client_id is missing."
}
パラメータ名説明
errorString
エラーの際に使用するエラーコード。
error_descriptionString
エラーの際、どのような問題が発生しているか、具体的に記述したメッセージ。

返答するエラーコードは以下の通りです。

エラーコード説明
invalid_requestリクエストされたパラメーターが足りないか、パラメータの値が正しくありません。
invalid_clientリクエストされたclient_idが見つかりません。
invalid_redirect_uriリクエストされたredirect_uriが設定されたリダイレクトURIと一致しません。
invalid_grant認可コードが見つかりませんでした。
invalid_code_verifierPKCE検証に失敗しました。
unauthorized_clientクライアントは指定された方法で取得することが許可されていません、。
unsupported_grant_type認可サーバーは、リクエストされたgrant_typeをサポートしていません。
server_error内部エラーにより処理できません。

3. アクセストークンを再取得#

アクセストークンは、有効期間が短いため続けて使用する際はアクセストークンをリフレッシュトークンフローで再度取得する必要があります。トークンエンドポイントを使用し、2. アクセストークンを要求するで取得したリフレッシュトークンを使用します。

トークンエンドポイントにPOST要求、フォームでデータを渡します。

POST /account/oauth2/v1/token
Host: https://manager.dmdata.jp
Content-Type: application/x-www-form-urlencoded
client_id=CId.CCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCC
&client_secret=CSt.SSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSS
&grant_type=refresh_token
&refresh_token=ARh.RRRRRRRRRRRRRRRRRRRRRRRRRRRRRRRRRRRRRRRRRRR
パラメータ名必須説明
client_idはいString
OAuth クライアント毎に割り当てられた、CId.で始まるID
client_secretオプションString
OAuth クライアント毎に割り当てられた、CSt.で始まるシークレットキー。
クライアントの種類が「機密」の場合は必須です。
grant_typeはいString
リフレッシュトークンフローでは、refresh_tokenを指定する必要があります。
refresh_tokenはいString
認可コード要求で取得したARh.で始まるリフレッシュトークン。

成功した応答#

{
"access_token": "ATn.TTTTTTTTTTTTTTTTTTTTTTTTTTTTTTTTTTTTTTTTTTTTTTTTTTTTTTTTTTTTTTTTTTTTTTTTTTTTTTTTTTTTTTT",
"token_type": "Bearer",
"expires_in": 21600,
"scope": "telegram.list telegram.get.earthquake telegram.data"
}
パラメータ名説明
access_tokenString
ATn.で始まるアクセストークン。
token_typeString
アクセストークンの種類を示し、Bearerで固定です。
expires_inString
アクセストークンの有効期間(秒)。6時間有効です。
scopeString
アクセストークンに付与されたスコープ。

エラー#

{
"error": "invalid_request",
"error_description": "The client_id is missing."
}
パラメータ名説明
errorString
エラーの際に使用するエラーコード。
error_descriptionString
エラーの際、どのような問題が発生しているか、具体的に記述したメッセージ。

返答するエラーコードは以下の通りです。

エラーコード説明
invalid_requestリクエストされたパラメーターが足りないか、パラメータの値が正しくありません。
invalid_clientリクエストされたclient_idが見つかりません。
invalid_grantリフレッシュトークンが見つかりませんでした。
unauthorized_clientクライアントは指定された方法で取得することが許可されていません、。
unsupported_grant_type認可サーバーは、リクエストされたgrant_typeをサポートしていません。
server_error内部エラーにより処理できません。

クライアント・クレデンシャルズフロー#

このフローではOAuthクライアントのみを使用して、クライアントを作成したアカウントのアクセストークンを要求できます。

また、クライアントの種類が機密である必要があります。

アクセストークンの要求#

トークンエンドポイントにPOST要求、フォームでデータを渡します。

POST /account/oauth2/v1/token
Host: https://manager.dmdata.jp
Content-Type: application/x-www-form-urlencoded
client_id=CId.CCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCC
&client_secret=CSt.SSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSS
&grant_type=client_credentials
&scope=telegram.list%20telegram.get.earthquake%20telegram.data
パラメータ名必須説明
client_idはいString
OAuth クライアント毎に割り当てられた、CId.で始まるID
client_secretはいString
OAuth クライアント毎に割り当てられた、CSt.で始まるシークレットキー。
grant_typeはいString
クライアント・クレデンシャルズフローでは、client_credentialsを指定する必要があります。
scopeはいString
ユーザーから認可を求めるスコープ(権限)。複数含める場合はスペースで区切ります。

成功した応答#

{
"access_token": "ATn.TTTTTTTTTTTTTTTTTTTTTTTTTTTTTTTTTTTTTTTTTTTTTTTTTTTTTTTTTTTTTTTTTTTTTTTTTTTTTTTTTTTTTTT",
"token_type": "Bearer",
"expires_in": 21600,
"scope": "telegram.list telegram.get.earthquake telegram.data"
}
パラメータ名説明
access_tokenString
ATn.で始まるアクセストークン。
token_typeString
アクセストークンの種類を示し、Bearerで固定です。
expires_inString
アクセストークンの有効期間(秒)。6時間有効です。
scopeString
アクセストークンに付与されたスコープ。

エラー#

{
"error": "invalid_request",
"error_description": "The client_id is missing."
}
パラメータ名説明
errorString
エラーの際に使用するエラーコード。
error_descriptionString
エラーの際、どのような問題が発生しているか、具体的に記述したメッセージ。

返答するエラーコードは以下の通りです。

エラーコード説明
invalid_requestリクエストされたパラメーターが足りないか、パラメータの値が正しくありません。
invalid_clientリクエストされたclient_idが見つかりません。
unauthorized_clientクライアントは指定された方法で取得することが許可されていません、。
unsupported_grant_type認可サーバーは、リクエストされたgrant_typeをサポートしていません。
server_error内部エラーにより処理できません。

トークンの失効#

アクセストークンやリフレッシュトークンが不要になった場合は直ちにトークンの失効を実行しなければなりません。

失効の要求#

POST /account/oauth2/v1/revoke
Host: https://manager.dmdata.jp
Content-Type: application/x-www-form-urlencoded
client_id=CId.CCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCC
&client_secret=CSt.SSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSS
&tokne=ATn.TTTTTTTTTTTTTTTTTTTTTTTTTTTTTTTTTTTTTTTTTTTTTTTTTTTTTTTTTTTTTTTTTTTTTTTTTTTTTTTTTTTTTTT
パラメータ名必須説明
client_idはいString
OAuth クライアント毎に割り当てられた、CId.で始まるID
client_secretオプションString
OAuth クライアント毎に割り当てられた、CSt.で始まるシークレットキー。
クライアントの種類が「機密」の場合は必須です。
tokenはいString
ATn.で始まるアクセストークンか、ARh.で始まるリフレッシュトークン。

成功した応答#

失効に成功した場合、認可サーバーは何も返しません。

エラー#

{
"error": "invalid_request",
"error_description": "The client_id is missing."
}
パラメータ名説明
errorString
エラーの際に使用するエラーコード。
error_descriptionString
エラーの際、どのような問題が発生しているか、具体的に記述したメッセージ。

返答するエラーコードは以下の通りです。

エラーコード説明
invalid_requestリクエストされたパラメーターが足りないか、パラメータの値が正しくありません。
invalid_clientリクエストされたclient_idが見つかりません。
invalid_grantトークンが見つかりませんでした。
server_error内部エラーにより処理できません。

各コード/トークンの有効期間#

  • 認可コード - 600秒(10分)
  • アクセストークン - 21,600秒(6時間)
  • リフレッシュトークン - 183日(リフレッシュトークンフローで使用するごとに期限が183日延長)