Drive and Photo Service:JWT アプリケーション連携

JWT アプリケーションの概要

本ドキュメントにおける JWT アプリケーションとは、JSON Web トークン（JWT） を用いて身分認証を行うカスタムアプリケーションです。

JWT アプリケーションは、サーバー側で秘密鍵を用いてデータに署名し、JWT 文字列を生成できます。この JWT 文字列は、対応する公開鍵が設定されたサーバーへのアクセス認証情報として機能します。

適用範囲／利用シーン

1. 企業が独立したアカウントシステムを備えた社内ソフトウェアシステムを保有しており、ユーザーが社内のログインページからログインした後、PDS の機能を利用できるようにしたい場合。

2. 企業が独立したアカウントシステムおよびログインポータルを保有しており、既存のログインポータルと PDS を連携させて、自社アカウント向けのクラウドストレージシステムを構築したい場合。

連携手順の概要

1. PDS コンソールでカスタムドメインおよび JWT アプリケーションを作成します。

2. RSA アルゴリズムを用いて公開鍵・秘密鍵ペアを作成します。公開鍵は PDS サーバー側に、秘密鍵は JWT アプリケーションのサーバー側に保存します。

3. JWT アプリケーションのサーバー側でデータをエンコードし、秘密鍵で署名して JWT アサーション文字列を生成し、PDS サーバー側に送信します。

4. PDS サーバー側は公開鍵を用いて JWT アサーション文字列を検証し、JWT アプリケーションのサーバー側にアクセストークンを返却します。その後、JWT アプリケーションのサーバー側は、このアクセストークンを用いて PDS サーバー側が提供する API を呼び出せます。

詳細な手順

1 キーの構成

1.1 ドメインの作成または選択

1.2 アプリケーションの作成または選択

ドメインの詳細ページに移動し、アプリケーション一覧ページでアプリケーションを作成または選択します。

1.3 公開鍵の設定

アプリケーションの作成または選択後、**[公開鍵の設定]** をクリックします。

公開鍵および秘密鍵を生成します。

公開鍵と秘密鍵を生成後、秘密鍵をコピーして保存し、**[OK]** をクリックします。

2 アクセストークン（access_token）の取得

2.1 アプリケーションサーバー側での JWT 文字列の計算

署名対象のデータをエンコードし、指定された暗号化アルゴリズムを用いて秘密鍵で署名して JWT 文字列を生成します。以下の Node.js サンプルコードは、この操作の実装例です。

const JWT = require('jsonwebtoken');

function signAssertion({ domain_id, client_id, user_id, privateKeyPEM }) {
  var now_sec = parseInt(Date.now() / 1000);
  var opt = {
    iss: client_id,
    sub: user_id,
    sub_type: "user",
    aud: domain_id,
    jti: Math.random().toString(36).substring(2),
    exp: now_sec + 60,
    // iat: 現在時刻（秒単位）
    // nbf: 有効開始時刻以前は使用不可
    auto_create: false,
  };
  return JWT.sign(opt, privateKeyPEM, {
    algorithm: "RS256",
  });
}

opt パラメーター

JWT のサードパーティ製ライブラリおよび計算方法の詳細については、「JWT 公式サイト」をご参照ください。

2.2 JWT 文字列を用いたアクセストークン（access_token）の取得

Authorize インターフェイスを呼び出して、アクセストークンを取得します。

POST /v2/oauth/token
Content-Type: application/x-www-form-urlencoded

grant_type=urn:ietf:params:oauth:grant-type:jwt-bearer&client_id=${APP_ID}&assertion=xxxxxxxxxx

リクエストパラメーター

レスポンスのサンプル

{
  "access_token": "eyJh****eQdnUTsEk4",
  "refresh_token": "kL***Lt",
  "expires_in": 7200,
  "token_type": "Bearer"
}

アプリケーションサーバー側がアクセストークンを取得した後、そのトークンをアプリケーションの Web クライアントに返却します。PDS の API を呼び出す際には、必ずこのアクセストークンを含めて、PDS 上のユーザー資源へアクセスしてください。

2.3 アクセストークン（access_token）のリフレッシュ

JWT を用いて取得したアクセストークンの有効期間は 2 時間です。アクセストークンの有効期限が切れた後は、新しいトークンを取得する必要があります。有効期限切れ後 7 日以内であれば、有効期限切れのアクセストークンを用いて PDS の API を呼び出し、新しいアクセストークンを取得できます。ただし、有効期限切れ後 7 日以上経過した場合は、ステップ 2.1 および 2.2 を再度実行する必要があります。

以下のコードは、Authorize インターフェイスを呼び出してアクセストークンを取得するリクエストのサンプルです：

POST /v2/oauth/token
Content-Type: application/x-www-form-urlencoded

client_id=${APPID}&refresh_token=${access_token}&grant_type=refresh_token&redirect_uri=${REDIRECT_URI}

3 Basic UI の利用（任意）

独自の UI を開発せず、公式の Basic UI が要件を満たす場合、Basic UI を直接利用できます。

方法 1：

window.open を用いて Basic UI を開き、postMessage でアクセストークンを渡します。

サンプルコード：

const endpoint = `https://${domain_id}.apps.aliyunpds.com`
const url = `${endpoint}/accesstoken?origin=${location.origin}`
var win = window.open(url)

window.addEventListener('message', onMessage, false)
async function onMessage(e) {
  if (e.data.code == 'token' && e.data.message == 'ready') {
    var result = await getToken(); // サーバー側からアクセストークンを取得
    //result = {"access_token": ...}
    win.postMessage({
      code: 'token',
      message: result
    }, endpoint || '*')

    window.removeEventListener('message', onMessage)
  }
}

方法 2：

Basic UI は iframe を用いてカスタムログインページを埋め込みます。

システム構成で、カスタムログインページの URL および JWT アプリケーション ID を設定すると、Basic UI がトークンを自動更新できます。

ユーザーがログインすると、Basic UI のデフォルトログインページではなく、iframe に埋め込まれたカスタムログインページが表示されます。

ユーザーが正常にログインした後、postMessage を用いてホストページにトークンを渡します。

if(parent!=self){
  let origin = ''
  parent.postMessage({
    code: 'token',
    message: {
       access_token: 'xxxx',
       refresh_token: 'xxxx',
       ...
    }
  }, endpoint || "*")
}

付録 1：Node.js コード実装例

以下のサンプルコードは、JWT アプリケーションがアクセストークンを取得およびリフレッシュする方法を示しています。

const fs = require('fs')
const JWT = require('jsonwebtoken');
const axios = require('axios')

const DOMAIN_ID = '' // ドメイン ID
const APP_ID = '' // アプリケーション ID
const USER_ID = '' // ユーザー UID
const PRIVATE_KEY_PEM = '' // 秘密鍵（ステップ 1.3 で設定）
const PRE = `https://${domain_id}.api.aliyunpds.com`

async function init() {
  try {
    // 実際の状況に応じて、以下の変数を適宜設定してください
    var params = {
      domain_id: DOMAIN_ID,
      client_id: APP_ID,
      user_id: USER_ID,
      privateKeyPEM: PRIVATE_KEY_PEM,
    };
    var assertion = signAssertion(params)
    var obj = await getToken(assertion)
    return obj.data
  } catch (e) {
    if (e.response) {
      console.log(e.response.status)
      console.log(e.response.headers)
      console.log(e.response.data)
    } else {
      console.error(e)
    }
  }
}

function signAssertion({ domain_id, client_id, user_id, privateKeyPEM }) {
  var now_sec = parseInt(Date.now()/1000)
  var opt = {
    iss: client_id,
    sub: user_id,
    sub_type: 'user',
    aud: domain_id,
    jti: Math.random().toString(36).substring(2),
    exp: now_sec + 300,
    // iat: 現在時刻（秒単位）
    // nbf: 有効開始時刻以前は使用不可
    auto_create: true,
  };
  return JWT.sign(opt, privateKeyPEM, {
    algorithm: 'RS256'
  });
}

async function getToken(assertion) {
  return await axios({
    method: 'post',
    url: PRE + '/v2/oauth/token',
    // 注意：リクエストの Content-Type を application/x-www-form-urlencoded に設定
    headers: {
      'Content-Type': 'application/x-www-form-urlencoded'
    },
    // 注意：リクエストパラメーターを本文に配置
    data: params({
      grant_type: 'urn:ietf:params:oauth:grant-type:jwt-bearer',
      client_id: APP_ID,
      assertion
    })
  })
}

async function refreshToken(refresh_token) {
  return await axios({
    method: 'post',
    url: PRE + '/v2/oauth/token',
    // 注意：リクエストの Content-Type を application/x-www-form-urlencoded に設定
    headers: {
      'Content-Type': 'application/x-www-form-urlencoded'
    },
    // 注意：リクエストパラメーターを本文に配置
    data: params({
      grant_type: 'refresh_token',
      client_id: APP_ID,
      refresh_token,
    })
  })
}

function params(m){
  const params = new URLSearchParams();
  for(var k in m){
     params.append(k, m[k]);
  }
  return params;
}

// テスト実行
;(async ()=>{
  let result = await init()
  console.log(result) // トークンオブジェクト {access_token:...} を返却。構造の詳細は「付録 2」を参照。
  // アクセストークンの有効期限が切れた後
  refreshToken(result.refreshToken) // 新しいトークンオブジェクト {access_token:...} を返却。構造の詳細は「付録 2」を参照。
})();

付録 2：トークンオブジェクトの構造

サンプルデータ

{
  access_token: 'eyJhbG.....g7M0p28',
  refresh_token: '62f1acc.......9b781f3',
  expires_in: 7200,
  token_type: 'Bearer',
  ......
}

各パラメーターの詳細については、「トークン - アクセストークンの取得」をご参照ください。