Server Apps + API: API の Node.js 実装

Server Client + API アーキテクチャシナリオ向けの API の Node.js 実装

Server + API Architecture Scenarioの一環として、Node.jsでTimesheets APIを実装します。実装するソリューションの詳細については、このシナリオを参照してください。

Node.js API実装の完全なソースコードは、このGitHubリポジトリで確認できます。

​

ステップ 1. API エンドポイントを定義する

Node.js API の構築には、Express Webアプリケーションフレームワーク を使用します。

​

package.json ファイルを作成する

API 用のフォルダーを作成し、そのフォルダーに移動して npm init を実行します。これにより、package.json ファイルが作成されます。

設定はデフォルトのままでも、必要に応じて変更してもかまいません。

このサンプルの package.json は次のようになります。

{
  "name": "timesheets-api",
  "version": "1.0.0",
  "description": "API used to add timesheet entries for employees and contractors",
  "main": "index.js",
  "scripts": {
    "test": "echo \"Error: no test specified\" && exit 1"
  },
  "repository": {
    "type": "git",
    "url": "git+https://github.com/auth0-samples/auth0-pnp-timesheets.git"
  },
  "author": "Auth0",
  "license": "MIT",
  "bugs": {
    "url": "https://github.com/auth0-samples/auth0-pnp-timesheets/issues"
  },
  "homepage": "https://github.com/auth0-samples/auth0-pnp-timesheets#readme"
}

​

依存関係をインストールする

次に、必要な依存関係を設定します。使用するモジュールは次のとおりです。

• express: このモジュールは Express Webアプリケーションフレームワーク を追加します。
• jwks-rsa: このライブラリは、JWKS (JSON Web Key Set) エンドポイントから RSA 署名鍵を取得します。expressJwtSecret を使用すると、JWT ヘッダー内の kid に基づいて、適切な署名鍵を express-jwt に渡すシークレットプロバイダーを生成できます。詳しくは、node-jwks-rsa GitHub repository を参照してください。
• express-jwt: このモジュールを使うと、Node.js アプリケーションで JWT トークンを使用して HTTP リクエストを認証できます。JWT を扱いやすくするための関数もいくつか用意されています。詳しくは、express-jwt GitHub repository を参照してください。
• body-parser: これは Node.js のリクエストボディを解析するミドルウェアです。受信した request ストリームからボディ全体を取り出し、req.body として扱いやすい形で利用できるようにします。詳しい情報や代替手段については、body-parser GitHub repository を参照してください。

これらの依存関係をインストールするには、次を実行します。

npm install express express-jwt jwks-rsa body-parser --save

​

エンドポイントを実装する

API のディレクトリに移動し、server.js ファイルを作成します。コードでは次のことを行う必要があります。

• 依存関係を設定する。
• リクエストボディを解析するミドルウェアを有効にする。
• エンドポイントを実装する。
• API サーバーを起動する。

以下は実装例です。

// 依存関係を設定する
const express = require('express');
const app = express();
const jwt = require('express-jwt');
const jwksRsa = require('jwks-rsa');
const bodyParser = require('body-parser');

// リクエストボディ解析ミドルウェアを有効にする
app.use(bodyParser.json());
app.use(bodyParser.urlencoded({
  extended: true
}));

// タイムシートアップロード用のAPIエンドポイントを作成する
app.post('/timesheets/upload', function(req, res){
  res.status(201).send({message: "This is the POST /timesheets/upload endpoint"});
})

// APIサーバーをlocalhost:8080で起動する
app.listen(8080);

node serverでAPIサーバーを起動し、localhost:8080/timesheets/uploadにHTTP POSTリクエストを送信します。This is the POST /timesheets/upload endpointというメッセージを含むJSONレスポンスが返ってくるはずです。

これでエンドポイントは用意できましたが、現状では誰でも呼び出せてしまいます。これをどう防ぐかは、次の段落で確認してください。

​

ステップ2. APIエンドポイントを保護する

トークンを検証するために、express-jwt middleware が提供する jwt 関数と、Auth0 から公開鍵を取得するための jwks-rsa パッケージを使用します。これらのライブラリの役割は次のとおりです。

1. express-jwt はトークンをデコードし、リクエスト、ヘッダー、ペイロードを jwksRsa.expressJwtSecret に渡します。
2. 次に jwks-rsa が JWKS エンドポイントからすべての署名鍵をダウンロードし、JWT のヘッダー内の kid と一致する署名鍵があるかどうかを確認します。受信した kid に一致する署名鍵がない場合はエラーがスローされます。一致するものが見つかった場合は、適切な署名鍵を express-jwt に渡します。
3. express-jwt は続いて、トークンの署名、有効期限、audience、issuer を独自のロジックで検証します。

コードでは、次の手順で進めます。

• アクセストークンを検証するミドルウェア関数を作成します。
• ルートでそのミドルウェアを使えるようにします。

また、タイムシートのエントリをローカルデータベースや任意のストレージに保存するロジックを実装するにも、ちょうどよいタイミングです。以下はサンプル実装です (一部のコードは簡潔にするため省略しています) 。

ここでサーバーを起動し、localhost:8080/timesheets/upload に HTTP POST リクエストを送信すると、Missing or invalid token というエラーメッセージが返されるはずです (リクエストでアクセストークンを送信していないため、これはまったく問題ありません) 。

正常に動作するケースもテストするには、次のことを行う必要があります。

• アクセストークンを取得します。取得方法の詳細については、Get an Access Token を参照してください
• リクエストに値 Bearer ACCESS_TOKEN の Authorization ヘッダーを追加して API を呼び出します (ACCESS_TOKEN は最初の手順で取得したトークンの値です) 。

​

ステップ 3. クライアントの権限を確認する

このステップでは、タイムシートをアップロードするために、クライアントがこのエンドポイントを利用する権限 (または scope) を持っているかどうかを確認できるように実装を追加します。特に、トークンに正しいスコープ、つまり batch:upload が含まれていることを確認したいと考えています。

そのために、express-jwt-authz という Node.js パッケージを使用するので、これをプロジェクトに追加してください。

npm install express-jwt-authz --save

これで、特定のエンドポイントを実行する際に JWT に特定のスコープが含まれていることを確認するには、ミドルウェアに jwtAuthz(...) の呼び出しを追加するだけです。以下はサンプル実装です (一部のコードは簡潔さのため省略しています) :

// 依存関係を設定 - 一部のコードは省略
const jwtAuthz = require('express-jwt-authz');

// JWTを検証するミドルウェアを作成

// リクエストボディ解析ミドルウェアを有効化
app.use(bodyParser.json());
app.use(bodyParser.urlencoded({
  extended: true
}));

// 一括アップロードエンドポイント
app.post('/timesheets/upload', checkJwt, jwtAuthz(['batch:upload']), function(req, res){
  var timesheet = req.body;

  // タイムシートエントリをデータベースに保存...

  //レスポンスを送信
  res.status(201).send(timesheet);
});

// localhost:8080 でAPIサーバーを起動 - コードは省略

このスコープを含まないトークンで API を呼び出すと、HTTP ステータスコード 403 とともに、Forbidden というエラーメッセージが返されるはずです。これを確認するには、API からこのスコープを削除してみてください。

以上です。これで完了です！