ユーザーのOAuth2クライアントを使う

intdash APIではOAuth 2.0(RFC 6749 、以下OAuth2)による認証が可能です。

intdash APIを利用するアプリケーションを開発する場合、OAuth2仕様に沿ってintdashの認可サーバーからアクセストークンを取得するようにしてください。なお、intdashにおいて認可サーバーとリソースサーバーは同一です。

グラントタイプは、認可コードとクライアントクレデンシャルに対応しています。

重要

本ページ内で使用される用語「クライアント」は、OAuth2の仕様で言うクライアント(client)を指します。

従って、OAuth2の仕組みを使ってアクセストークンを取得しintdash APIにアクセスするアプリケーション（ウェブアプリケーション、モバイルアプリケーション、組み込みアプリケーションなど）がクライアントと呼ばれます。

本ページでは、ユーザーが自分のユーザーアカウントに紐づいたクライアントを設定し、それを使用する方法を説明しています。 1つのユーザーアカウントが複数のクライアントを持つことができます。

../../_images/user-client.ja.png — 図 1 ユーザーが持つクライアント

1. アクセストークンを取得する

アクセストークンを取得するまでのフローには、以下を利用可能です。

認可コードによる認可 

intdash APIを利用するウェブアプリケーションやモバイルアプリケーションを開発する場合は認可コードフローを使用します。

この場合、そのウェブアプリケーションやモバイルアプリケーションがOAuth2におけるクライアントとなります。

intdash上のリソースにクライアントがアクセスしようとする際、ユーザー（リソースオーナー）はウェブブラウザーを使ってintdashにログインすることで同意を行います。

クライアントはあらかじめintdashの認可サーバーに登録しておく必要があります。登録は、REST APIのエンドポイント POST /auth/users/me/clients にて以下のように行ってください。

注釈

現時点では、ウェブコンソールアプリケーション上でクライアントを登録することはできません。APIを使って行う必要があります。

ウェブアプリケーション(https://myapp.example.com/)をクライアントとして登録する例:

curl -X POST "https://example.intdash.jp/api/auth/users/me/clients" \
-H "Content-Type: application/json" \
-H "Accept: application/json; charset=utf-8" \
-H "X-Intdash-Token: ....." \
--data-raw "{
  \"name\": \"my-authorization-code-client\",
  \"grant_type\": \"authorization_code\",
  \"token_endpoint_auth_method\": \"client_secret_basic\",
  \"redirect_uris\": [
    \"https://myapp.example.com/callback\"
  ]
}"

X-Intdash-Tokenヘッダー

ユーザーのAPIトークン（My Pageで発行されるもの）を指定してください。

name

任意の名前を指定してください。

grant_type

authorization_code を指定してください。

token_endpoint_auth_method

OAuth2におけるコンフィデンシャルクライアント（例えば、認証情報をセキュアな場所に保持できるサーバーアプリケーション）の場合は、 client_secret_basic を指定してください。

パブリッククライアント（例えば、SPAやモバイルアプリなど、アプリケーションの使用端末からリソースサーバーに直接アクセスし、認証情報をセキュアな場所に保持できないアプリケーション）の場合は、 none を指定してください。

redirect_uris

クライアントのアプリケーションがコールバックを受けるための、そのアプリケーションのURLを指定します（例: https://myapp.example.com/callback ）クライアントがモバイルアプリケーションの場合は、そのアプリのカスタムスキームによるURIを指定してください（例: companyname.appname://oauth2/callback ）。

レスポンス例:

上記のリクエストを行うと、クライアントが作成され、クライアントID(client_id)が生成されます。

{
  "client_id": "3cdf....",
  "client_secret": "2akq....",
  "name": "my-authorization-code-client",
  "grant_types": [
    "authorization_code",
    "refresh_token"
  ],
  "token_endpoint_auth_method": "client_secret_basic",
  "redirect_uris": ["https://myapp.example.com/callback"],
  "response_types": [
    "code"
  ],
  "scopes": [
    // ...
  ],
  "audiences": [],
  "tls_client_auth_subject_dn": "",
    // ...
}

クライアント（intdash APIを利用するアプリケーション）は、以下のようなフローが行われるように実装してください。

autonumber
actor "Resource Owner / User" as ro
participant Client as c
participant "Authorization Server" as auth
participant "Resource Server" as rs

ro -> c: Access
activate c
c -> rs: GET /何らかのリソース
rs --> c: 401 Unauthorized
c -> ro: Redirect to Authorization Endpoint
ro -> auth: GET /auth/oauth2/authorization?\nclient_id=...&response_type=code...
auth --> ro: 認証画面に誘導
note over ro: 認証画面でログイン
auth --> ro: Redirect to Client
ro -> c: https://myapp.example.com/callback?\ncode=...&state=...
c -> auth: POST /auth/oauth2/token
auth --> c: AccessToken
deactivate c — 図 2 認可コードによる認可のフロー

ユーザーが、クライアントを使ってintdashのリソースにアクセスする操作を行います。
クライアントがintdashのリソース（リソースサーバー）にアクセスしようとします。
認可を得ていないので、リソースサーバーは401 Unauthorizedを返却します。
するとクライアントは、以下の例のようなURLでintdashサーバーの認可エンドポイントにユーザーをリダイレクトします。
```
https://example.intdash.jp/api/auth/oauth2/authorization
  ?client_id=3cdf....
  &response_type=code
  &redirect_uri=https://myapp.example.com/callback
  &state=05d54.....
  &code_challenge=ZtNPu.....
  &code_challenge_method=S256
```
リダイレクトURLに含まれるリクエストパラメーター

client_id
クライアントID。クライアントを登録したときに生成されたこのクライアントのIDです。

response_type
OAuth2のresponse_type。 code のみサポートされています。

redirect_uri
認可後のリダイレクト先URI。クライアントアプリケーションのURIを指定します。クライアント登録時に指定したリダイレクト先(redirect_uris)の1つと一致する必要があります。

state
CSRF対策のためのstate。推測不能なランダムな値を指定します。この値は認証が終わって認可サーバーから戻ってきた時に利用するため、それまで何らかの手段でクライアントに保存しておきます。

code_challenge
PKCEコードチャレンジ。推測不能なランダムな値を生成し（これをcode verifierと呼びます）、そのSHA-256ハッシュをBase64 URLエンコードしたものを使用します。

code verifierに使用可能な文字は [a-Z] / [0-9] / "-" / "." / "_" / "~" です。 code verifierの長さは43文字以上、128文字以下としてください。

code_challenge_method
PKCEコードチャレンジの方式。 S256 （SHA-256）のみサポートされます。
上記リダイレクトにより、ユーザーはintdashサーバーの認可エンドポイントへのリクエストを行います。
intdashサーバーの認可エンドポイントは、ユーザーをintdashの認証画面に誘導します。
認証ができたら、認可サーバーは、設定されたコールバックURLへユーザーをリダイレクトします。このURLには認可コード（code）とstateが含まれています。
```
https://myapp.example.com/callback?code=w765op.....&state=05d54.....
```
上記リダイレクトリクエストにより、ユーザーはクライアントに対して、 code と state を含むリクエストを行います。

クライアントは、このURLに含まれる state が、さきほど認可エンドポイントに送った state と一致することを確認します。

ここでクライアントが得た code が、認可コード（authorization code）です。
クライアントは、認可コードを使用して認可サーバーのトークンエンドポイントにリクエストを送り、アクセストークンを発行してもらいます。クライアントからトークンエンドポイントへのリクエストは以下のようになります。
```
$ curl -X POST https://example.intdash.jp/api/auth/oauth2/token \
-d "code=w765op.....&grant_type=authorization_code&client_id=3cdf.....&redirect_uri=https://myapp.example.com/callback&code_verifier=2fhVB....."
```
リクエストパラメーター

code
認可コード

grant_type
グラントタイプ。 authorization_code とします。

client_id
OAuth2クライアントのID。クライアントの登録時に発行されたクライアントIDです。

redirect_uri
認可後のリダイレクト先URI。クライアントアプリケーションのURIを指定します。クライアント登録時に指定したリダイレクト先(redirect_uris)の1つと一致する必要があります。

code_verifier
認可エンドポイントへのリクエスト時に送付したcode_challengeの基になったcode_verifierの値。

認可サーバーから以下のようなレスポンスが返ります。

レスポンス例：
{
 "access_token":"eyJh....",
 "expires_in":3599,
 "refresh_token":"......",
 "refresh_token_expires_in":2591999,
 "scope":".....",
 "token_type":"bearer"
}
access_token
アクセストークン

expires_in
アクセストークンの有効期限（期限切れまでの秒数）

refresh_token
リフレッシュトークン（リフレッシュトークンによる新しいアクセストークンの発行で使用することができます）

refresh_token_expires_in
リフレッシュトークンの有効期限（期限切れまでの秒数）

scope
スコープのリスト（スペース区切り）

token_type
トークンタイプ。 bearer に固定。

得られたアクセストークンを使ってクライアントがintdashのリソースにアクセスする方法については、 2. OAuth2アクセストークンを使用してリソースサーバーにアクセスするを参照してください。

注釈

このフローによるサンプルとして、 Type Scriptによるサンプルと Swiftによるサンプルも参照してください。

クライアントクレデンシャルによる認可 

クライアントIDとクライアントシークレットを使ってアクセストークンをリクエストする方法です。リソースオーナーとのインタラクションが発生しないアプリケーション（主な例としては、サーバーのバックグラウンドジョブアプリケーション）の場合に、この方法を使用します。

クライアントはあらかじめintdashの認可サーバーに登録しておく必要があります。クライアントの登録は、上述の認可コードによる認可の場合と同じエンドポイント POST /auth/users/me/clients にて行います。

注釈

現時点では、ウェブコンソールアプリケーション上でクライアントを登録することはできません。APIを使って行う必要があります。

以下は、クライアントを登録するリクエストの例です。

curl -X POST "https://example.intdash.jp/api/auth/users/me/clients" \
-H "Content-Type: application/json" \
-H "Accept: application/json; charset=utf-8" \
-H "X-Intdash-Token: ....." \
--data-raw "{
  \"name\": \"my-client-credentials-client\",
  \"grant_type\": \"client_credentials\",
  \"token_endpoint_auth_method\": \"client_secret_post\"
}"

X-Intdash-Tokenヘッダー: ユーザーのAPIトークン（My Pageで発行されるもの）を指定してください。
name: 任意の名前を指定してください。
grant_type: client_credentials を指定してください。
token_endpoint_auth_method: client_secret_post を指定してください。 [1]

レスポンス例:

上記のリクエストを行うと、クライアントが作成され、クライアントID(client_id)、クライアントシークレット(client_secret)が生成されます。

{
  "client_id": "3cdf....",
  "client_secret": "2akq....",
  "name": "my-client-credentials-client",
  "grant_types": [
    "client_credentials"
  ],
  "token_endpoint_auth_method": "client_secret_post",
  "redirect_uris": [],
  "response_types": [],
  "scopes": [
    // ...
  ],
  "audiences": [],
  "tls_client_auth_subject_dn": "",
  // ...
}

発行されたクライアントIDとクライアントシークレットを使用してintdashの認可サーバーにアクセストークンをリクエストするには以下のようにします。

$ curl -X POST https://example.intdash.jp/api/auth/oauth2/token \
-d "grant_type=client_credentials&client_id=3cdf....&client_secret=2akq...."

これにより、アクセストークンを含むレスポンスが返ります。

レスポンス例：

{
  "access_token": "eyJh....",
  "expires_in": 3599,
  "scope": ".....",
  "token_type": "bearer"
}

アクセストークンを使用する方法については、 2. OAuth2アクセストークンを使用してリソースサーバーにアクセスするを参照してください。

リフレッシュトークンは発行されませんので、有効期限が切れた後はもう一度同じようにアクセストークンをリクエストしてください。

リフレッシュトークンによる新しいアクセストークンの発行 

アクセストークンには有効期限があります。リフレッシュトークンを持っている場合、リフレッシュトークンを使ってアクセストークンを再度要求することができます。

$ curl -X POST https://example.intdash.jp/api/auth/oauth2/token \
-d "grant_type=refresh_token&refresh_token=${REFRESH_TOKEN}&client_id=${CLIENT_ID}"

新しいアクセストークンとリフレッシュトークンを含むレスポンスが返ります。レスポンスは認可コードによる認可の場合と同様です。

2. OAuth2アクセストークンを使用してリソースサーバーにアクセスする

上記の方法で得たOAuth2アクセストークンを使用して、intdashが管理するリソースにアクセスするには、以下のいずれかのようにします。

アクセストークンをAuthorizationヘッダーにセットしてリクエストする。

$ curl -X GET https://example.intdash.jp/api/v1/measurements \
-H "Authorization: Bearer ${ACCESS_TOKEN}"

アクセストークンをCookieにセットした状態でリクエストする。

$ curl -X GET https://example.intdash.jp/api/v1/measurements \
-H "Cookie: _bearer_token=${ACCESS_TOKEN}"