tab API ドキュメント

はじめに

tab APIサーバはOAuth2の署名無しトークン(Bearer Tokens)を利用して認証状態を維持する仕様となっています。 ここではトークンの取得方法および認証状態を維持する方法について説明します。

なおOAuth2関連の仕様は下記ページを参考にしてください。

用語説明

Client ID, Client Secret

OAuth2の認証手順において、あらかじめサーバ側にアクセスするクライアントを登録しておく必要があります。 tabは、クライアント登録の際にClient IDとClient Secretのペアを発行します。

クライアントは、このペアと他に必要な認証情報を送信することでAccess Tokenを得ることができます。

Redirect URI

クライアントの登録時に必要です。

認可コードによるAccess Token取得の際には、tabからクライアント側に認可コードを付与するため、このURIにリダイレクトを行います。

Access Token

Access Tokenは一定の認証手順を行なうことで得られます。

取得した後は、リクエストヘッダにこのAccess Tokenを埋め込んで通信することで認証済みの状態となります。

有効期限について

Access Tokenは短い時間の有効期限しか持ちません。（数十分程度）

Access Tokenが有効期限を超過して無効になった場合は、後述のRefresh Tokenを用いて新しいAccess Tokenを再発行する必要があります。

Refresh Token

Access Tokenと同時に得られます。Refresh Tokenを利用して新しいAccess Tokenを得る事ができます。

Access Tokenの有効期限が短いのでRefresh Tokenは頻繁に利用することになります。Refresh Tokenの有効期限は数日間程度です。

Access Tokenの取得方法

tab APIサーバは認可コードによる認証方式を提供します。

認可コード

認可コードによる認証は、以下の方法で実現します。

クライアント側にはユーザの認証情報を持つ必要がないので、よりセキュアな方法だと言えます。

注意事項

ユーザ認証のためブラウザでのアクセスを必要とするため、クライアント側からブラウザベースの制御が必要となります。

下記ではWEBアプリケーションの場合を例に説明しています。WEBアプリケーション以外のクライアントによる開発を行なう場合は、 こちら をご参照ください。

用語説明

以下の説明中には下記用語が現れます。

用語 説明
tab WEB版tabサーバを指す
tab API tab APIサーバを指す
client APIを利用するクライアントを指す

実際のフロー

  1. client: こちら より、Client ID, Client Secret, Redirect URIを事前に発行しておく
    • 以後それぞれ、 CID, CSECRET, https://example.com/oauth2_callback と表記する
  2. client: tabに対して認可コードフローを開始するため、 エントリポイントにユーザを誘導する
    • https://tab.do/oauth2/authorize?response_type=code&client_id=CID&redirect_uri=https%3A%2F%2Fexample.com%2Foauth2_callback
    • この時、ユーザがログイン状態でなければ一旦ログイン画面が表示され、ログイン成功後に3へ進む
  3. tab: ユーザに対してクライアントの情報（クライアント名など）を提示し、アクセスを与えるかどうかを尋ねる
    • ユーザが許可した場合は4へ
    • ユーザが許可しなかった場合、クライアントにはエラーが返却される
      • https://example.com/oauth2_callback?error=<エラーメッセージ>&error_description=<エラー内容詳細> にリダイレクトされる
  4. tab: クライアントが登録したRedirect URIに対してリダイレクトを行なう
    • その際認可コードが付与される。下記 code が認可コードとなる
    • https://example.com/oauth2_callback?code=cb532e8a1684140516d864c0424978d4
  5. client: 取得した認可コードを元に、 認可コードによるAccess Token取得 を呼び出す
  6. tab API: 受け取った認可コードを検証し、問題がなければAccess Tokenを返却する
  7. client: 取得したAccess Tokenを元に、認証情報が必要なAPI、例えば 自分自身の情報を取得 などを呼び出す

Refresh Tokenを利用したAccess Tokenの取得方法

以下のAPIを用いて、Access Tokenを再発行することができます。

認可成功時のレスポンス

認可に成功してAccess Tokenが発行された場合、以下のような応答が返されます。ここでAccess Tokenとその有効期限、Refresh Tokenを得ることができます。

{
  "access_token": "787e93ce1abfdd8e96542bd224974360",
  "token_type": "bearer",
  "expires_in": 899,
  "refresh_token": "8846013e3add33718eb59633298ef5dd"
}
キー名 説明
access_token 発行されたAccess Token
token_type 発行されたトークンの種別。bearer固定
expires_in access_tokenの有効期限(秒)。この秒数の間のみ有効
refresh_token 発行されたRefresh Token。このトークンを用いてAccess Tokenの再発行を行なうことができる

Access Tokenの送信方法

下記の形式でHTTPリクエストヘッダに追加して送信することで、tab APIサーバに認証情報を渡すことができます。

Authorization: Bearer <Access Token>

詳細はこちら を参照してください。

注意事項

OAuth2では署名無しAccess Tokenを利用するため、Access Tokenを通信する経路は暗号化されていなければなりません。

具体的にはTLS(https)を利用します。

サンプルプログラム

こちら でOAuth2認可コードの実装サンプルを見ることができます。