API と SPA の設定（SPA + API）

SPA + API アーキテクチャにおける API と SPA の設定

このセクションでは、このシナリオ向けのAPIをどのように実装するかを見ていきます。

簡単にするため、この実装では認証と認可のみに焦点を当てます。サンプルで示すように、入力されるタイムシートのエントリはハードコードされており、APIがそのエントリを永続化することはありません。代わりに、一部の情報をそのまま返すだけです。

​

API エンドポイントを定義する

まず、API のエンドポイントを定義する必要があります。

API エンドポイントとは？

API エンドポイントとは、オブジェクトを表す一意の URL のことです。このオブジェクトとやり取りするには、アプリケーションからその URL を指定する必要があります。たとえば、orders または customers を返す API がある場合は、/orders と /customers という 2 つのエンドポイントを設定できます。アプリケーションは、異なる HTTP メソッドを使ってこれらのエンドポイントとやり取りします。たとえば、POST /orders で新しい order を作成し、GET /orders で 1 件以上の order のデータセットを取得できます。

この実装では、定義するエンドポイントは 2 つだけです。1 つは従業員のすべてのタイムシートの一覧を取得するためのもの、もう 1 つは従業員が新しいタイムシートのエントリを作成するためのものです。

/timesheets エンドポイントへの HTTP GET リクエストで、ユーザーは自分のタイムシートを取得できます。また、/timesheets エンドポイントへの HTTP POST リクエストで、ユーザーは新しい timesheet を追加できます。

実装例は Node.js を参照してください。

​

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

API がヘッダーに bearer アクセストークン を含むリクエストを受け取った場合、最初に行うべきことはそのトークンを検証することです。これには一連の手順があり、そのいずれかで検証に失敗した場合は、呼び出し元のアプリに Missing or invalid token というエラーメッセージを返して、リクエストを拒否する必要があります。

API で行うべき検証は次のとおりです。

• JWT の形式が正しいことを確認する
• 署名を確認する
• 標準クレームを検証する

JWT.io では、JWT の解析、署名の検証、クレームの検証など、作業の大部分を行えるライブラリの一覧を提供しています。

検証プロセスの一環として、アプリケーションの権限 (スコープ) も確認する必要がありますが、これについてはこのドキュメントの次の段落で別途説明します。

アクセストークンの検証について詳しくは、アクセストークンを検証する を参照してください。

実装については Node.js を参照してください。

​

アプリケーションの権限を確認する

ここまでで、JWT が有効であることを確認できました。最後の手順は、保護されたリソースにアクセスするために必要な権限をアプリケーションが持っていることを確認することです。

そのため、API はデコードされた JWT の スコープ を確認する必要があります。このクレームはペイロードの一部で、スペース区切りの文字列のリストです。

実装については Node.js を参照してください。

​

ユーザーの識別

どちらのエンドポイントでも (タイムシート一覧の取得と新しいタイムシートの追加) 、ユーザーの識別が必要になります。

タイムシート一覧を取得する場合は、リクエストを行ったユーザーに属するタイムシートだけを返すためです。また、新しいタイムシートを追加する場合は、そのタイムシートがリクエストを行ったユーザーに紐付けられるようにするためです。

標準的な JWT クレームの 1 つに sub クレームがあり、これはクレームの対象となる主体を識別します。Implicit Grant フローでは、このクレームにユーザーの識別情報、つまり Auth0 ユーザーの一意の識別子が含まれます。これを使えば、外部システム内の任意の情報を特定のユーザーに関連付けることができます。

また、カスタムクレームを使って、ユーザーの別の属性 (メールアドレスなど) をアクセストークンに追加し、それによってユーザーを一意に識別することもできます。

実装は Node.js で確認してください。

​

SPAを実装する

このセクションでは、このシナリオでSPAをどのように実装するかを見ていきます。

​

ユーザーを認証する

ユーザーを認証するには、auth0.js ライブラリ を使用します。Auth0 アプリケーションの新しいインスタンスは、次のように初期化できます。

次の設定値を渡す必要があります。

• clientID: Auth0 の Client Id の値です。Dashboard にある Application の Settings から取得できます。
• domain: Auth0 Domain の値です。Dashboard にある Application の Settings から取得できます。
• responseType: 使用する認証フローを指定します。Implicit Flow を使用する SPA の場合は、token id_token に設定する必要があります。token の部分は、フローによって URL フラグメントでアクセストークンが返されることを意味し、id_token の部分は、ID Token も返されることを意味します。
• audience: API Identifier の値です。Dashboard にある API の Settings から取得できます。
• redirectUri: ユーザーの認証後に Auth0 がリダイレクトする URL です。
• scope: ID Token とアクセストークンで返される情報を決定する スコープ です。openid profile という scope を指定すると、ID Token にユーザープロファイル情報がすべて返されます。また、API を呼び出すために必要な スコープ (この場合は read:timesheets create:timesheets) もリクエストする必要があります。これにより、アクセストークンにこれらの スコープ が含まれるようになります。

認証フローを開始するには、authorize() メソッドを呼び出します。

auth0.authorize();

認証後、Auth0 は Auth0 アプリケーションの新しいインスタンスの設定時に指定した redirectUri にリダイレクトします。この時点で、URL のハッシュフラグメントを解析し、Auth0 の認証レスポンスの結果を取り出す parseHash() メソッドを呼び出す必要があります。

parseHash が返す authResult オブジェクトの内容は、使用した認証パラメーターによって異なります。含まれる可能性があるのは次のとおりです。

• idToken: ユーザープロファイル情報を含む ID トークン JWT
• accessToken: audience で指定された API 用のアクセストークン。
• expiresIn: アクセストークンの有効期限 (秒数) を表す文字列。

トークンをどこに保存するのが最適かを判断してください。シングルページアプリにバックエンドサーバーがある場合、トークンは Authorization Code Flow または Authorization Code Flow with Proof Key for Code Exchange (PKCE) を使用して、サーバー側で扱う必要があります。

対応するバックエンドサーバーのないシングルページアプリ (SPA) の場合、SPA はログイン時に新しいトークンをリクエストし、永続化せずメモリ内に保存する必要があります。API 呼び出しを行う際は、そのメモリ内のトークンのコピーを使用します。

SPA でセッションを処理する方法の例については、JavaScript Single-Page App Quickstart の Handle Authentication Tokens セクションを参照してください。

実装例は Angular 2 をご覧ください。

​

ユーザープロフィールを取得する

トークンから情報を取得する

このセクションでは、アクセストークンと/userinfo エンドポイントを使ってユーザー情報を取得する方法を説明します。この API 呼び出しを避けたい場合は、ID トークンをライブラリを使ってデコードすることもできます (その前に必ず検証してください) 。追加のユーザー情報が必要な場合は、バックエンドからManagement APIを使用することを検討してください。

client.userInfoメソッドは、返されたauthResult.accessTokenを渡して呼び出すことで、ユーザーのプロフィール情報を取得できます。これにより/userinfo エンドポイントへリクエストが送信され、以下の例のようにユーザー情報を含むuserオブジェクトが返されます。

{
    "email_verified": "false",
    "email": "[e-mail]",
    "clientID": "AAAABBBBCCCCDDDDEEEEFFFFGGGGHHHH",
    "updated_at": "2017-02-07T20:50:33.563Z",
    "name": "[e-mail]",
    "picture": "https://gravatar.com/avatar/example.png",
    "user_id": "auth0|123456789012345678901234",
    "nickname": "tester9",
    "created_at": "2017-01-20T20:06:05.008Z",
    "sub": "auth0|123456789012345678901234"
}

userInfo 関数の呼び出し時に渡すコールバック関数では、これらのプロパティのいずれにもアクセスできます。

const accessToken = authResult.accessToken;

auth0.client.userInfo(accessToken, (err, profile) => {
  if (profile) {
    // ユーザーのニックネームとプロフィール画像を取得する
    var nickname = profile.nickname;
    var picture = profile.picture;
  }
});

実装については Angular 2 をご覧ください。

​

scope に応じて UI 要素を条件付きで表示する

ユーザーのscopeに応じて、特定の UI 要素を表示または非表示にすることがあります。ユーザーに付与されたscopeを確認するには、認可プロセスで最初にリクエストしたscopeを保存しておく必要があります。ユーザーの認可が完了すると、scopeはauthResultにも返されます。

authResult内のscopeが空であれば、リクエストしたすべてのスコープが付与されたことを意味します。authResult内のscopeが空でない場合は、別のスコープのセットが付与されたことを意味するため、authResult.scopeに含まれるものを使用してください。

実装例は Angular 2 を参照してください。

​

API を呼び出す

API の保護されたリソースにアクセスするには、認証済みユーザーのアクセストークンを、その API に送信するリクエストに含める必要があります。これを行うには、Bearer スキームを使用して、アクセストークンを Authorization ヘッダーで送信します。

実装については Angular 2 を参照してください。

​

アクセストークンを更新する

セキュリティ対策として、ユーザーのアクセストークンの有効期間は短く設定しておくことをおすすめします。Auth0 Dashboard で API を作成すると、デフォルトの有効期間は 7200 秒 (2 時間) ですが、これは API ごとに設定できます。

有効期限が切れると、アクセストークンは API へのアクセスに使用できなくなります。再度アクセスするには、新しいアクセストークンを取得する必要があります。

新しいアクセストークンは、最初のアクセストークンを取得したときと同じ認証フローを再度実行することで取得できます。SPA では、認証フローをもう一度完了するために、ユーザーを現在の作業から離れてリダイレクトしたくない場合もあるため、これは理想的ではありません。

このような場合は、Silent Authentication を利用できます。Silent Authentication では、Auth0 はリダイレクトのみを返し、ログインページは表示しない認証フローを実行できます。ただし、これを利用するには、ユーザーがすでに Single Sign-on (SSO) を通じてログインしている必要があります。

実装については Angular 2 を参照してください。