Node.js API 実装（モバイルアプリ + API）

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": {
    "start": "node index.js",
    "test": "echo \"Error: no test specified\" && exit 1"
  },
  "dependencies": {
    "body-parser": "^1.20.0",
    "cors": "^2.8.5",
    "express": "^4.18.0",
    "express-oauth2-jwt-bearer": "^1.6.0"
  },
  "author": "Auth0",
  "license": "MIT"
}

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

次に、以下のモジュールを使って依存関係を設定します。

express: このモジュールは Express web application framework を追加します。
cors: このモジュールは、CORS を有効にするためのサポートを追加します。API は、Web ブラウザー内の別ドメインで動作するシングルページアプリケーションから呼び出されるため、これが必要です。
jwks-rsa: このライブラリは、JWKS (JSON Web Key Set) endpoint から 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 のボディ解析ミドルウェアです。受信したリクエストストリームのボディ全体を取り出し、より扱いやすい形で req.body として利用できるようにします。

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

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

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

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

依存関係を追加する。
エンドポイントを実装する。
APIサーバーを起動する。

以下はサンプル実装です。

const express = require('express');
const app = express();
const { expressjwt: jwt } = require('express-jwt');
const jwksRsa = require('jwks-rsa');
const cors = require('cors');
const bodyParser = require('body-parser');

// CORSを有効にする
app.use(cors());

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

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

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

node serverでAPIサーバーを起動し、localhost:8080/timesheetsにHTTPのPOSTリクエストを送信します。This is the POST /timesheets endpointというメッセージを含むJSONレスポンスが返されるはずです。これでエンドポイントはできましたが、現状では誰でも呼び出せてしまいます。これをどう改善するかは、次の手順に進んで確認してください。

2 APIエンドポイントを保護する

トークンを検証するには、express-jwt middleware が提供する jwt 関数と、シークレットを取得するための jwks-rsa を使用します。これらのライブラリは次の処理を行います。

express-jwt はトークンをデコードし、リクエスト、ヘッダー、ペイロードを jwksRsa.expressJwtSecret に渡します。
jwks-rsa は JWKS エンドポイントからすべての署名鍵をダウンロードし、その中に JWT のヘッダー内の kid と一致するものがあるかを確認します。一致する署名鍵がなければエラーがスローされます。一致するものがあれば、正しい署名鍵を express-jwt に渡します。
express-jwt は続いて、トークンの署名、有効期限、audience、および issuer を検証します。

コードで行う手順は次のとおりです。

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

また、実際にタイムシートをデータベースに保存するコードを記述することもできます。以下はサンプル実装です (一部のコードは簡潔にするため省略しています) 。この時点でサーバーを起動し、localhost:8080/timesheets に HTTP POST を送信すると、Missing or invalid token というエラーメッセージが返されるはずです (リクエストでアクセストークンを送信していないため、これは正しい結果です) 。動作するケースもテストするには、次のことを行う必要があります。

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

3 アプリの権限を確認する

このステップでは、アプリケーションに権限 (またはスコープ) があるかどうかを確認し、タイムシートを作成するためにエンドポイントを利用できるようにします。特に、トークンに正しいスコープ、つまり batch:upload が含まれていることを確認します。そのために、express-jwt-authz Node.js パッケージを使用するので、これをプロジェクトに追加してください。

npm install express-jwt-authz --save

次に、特定のエンドポイントを実行するには JWT に特定のスコープが含まれている必要があることを確認するため、ミドルウェアに jwtAuthz(...) の呼び出しを追加します。依存関係をもう 1 つ追加します。express-jwt-authz ライブラリは express-jwt と組み合わせて使用され、JWT を検証するとともに、目的のエンドポイントを呼び出すための適切な権限が含まれていることを確認します。詳しくは、express-jwt-authz GitHub repository を参照してください。以下がサンプル実装です (簡潔にするため、一部のコードは省略しています) :

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

// CORSを有効化 - コードは省略

// JWTを検証するミドルウェアの作成 - コードは省略

// リクエストボディ解析ミドルウェアの使用を有効化 - コードは省略

// タイムシートAPIエンドポイントの作成
app.post('/timesheets', checkJwt, jwtAuthz(['create:timesheets'], { customUserKey: 'auth' }), function(req, res){
  var timesheet = req.body;

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

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

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

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

4 ユーザーの本人確認

JWT の検証に使用される express-jwt ミドルウェアでは、JWT に含まれる情報を使って req.user も設定されます。ユーザーを一意に識別するために sub claim を使いたい場合は、req.user.sub を使用できます。timesheets アプリケーションでは、一意の識別子としてユーザーのメールアドレスを使用します。

Action を作成する

まず、ユーザーのメールアドレスを access token に追加する新しい Action を作成します。

Auth0 Dashboard > Actions > Library に移動し、Build Custom を選択します。
Action のわかりやすい Name を入力し (たとえば Add email to access token) 、Login / Post Login トリガーを選択して、Create を選択します。
Actions Code Editor で、次の JavaScript コードをコピーして貼り付け、変更内容を保存するために Save Draft を選択します。
exports.onExecutePostLogin = async (event, api) => { const namespace = 'https://my-app.example.com'; api.accessToken.setCustomClaim(`${namespace}/email`, event.user.email); }
namespace は、claim 名が標準の OIDC claim や内部サービスと競合しないよう、一意にするために使用されます。名前空間付きおよび名前空間なしの claim に関する制限やガイドラインについて詳しくは、Create Custom Claims を参照してください。
Actions Code Editor のサイドバーで Test (再生アイコン) を選択し、Run を選択してコードをテストします。
Action を公開する準備ができたら、Deploy を選択します。

Action を Post-Login Trigger に追加する

次に、作成した Action を Post-Login Trigger に追加します。Action を Trigger に関連付ける方法については、Write Your First Action を参照してください。

一意の識別子を取得する

最後に、API 内で req.auth から claim の値を取得します。その値を、timesheet エントリに関連付ける一意のユーザー識別子として使用します。

app.get('/timesheets', checkJwt, jwtAuthz(['read:timesheets'], { customUserKey: 'auth' }), function(req, res) {
  var timesheet = req.body;

  // タイムシートエントリを現在のユーザーに関連付ける
  var userId = req.auth['https://api.exampleco.com/email'];
  timesheet.user_id = userId;

  // タイムシートをデータベースに保存する...

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

Quickstarts

Auth0 の概要

Auth0 を設定する

アプリケーション