API とモバイルの構成（モバイルアプリ + API）

モバイル + API アーキテクチャ シナリオ向けの API とモバイルの構成

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

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

​

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

まず、API のエンドポイントを定義します。

API エンドポイントとは何ですか？

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

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

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

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

​

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

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

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

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

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

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

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

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

​

クライアントの権限を確認する

ここまでで、JWT が有効であることを検証しました。最後の手順は、保護されたリソースへのアクセスに必要な権限をクライアントが持っていることを確認することです。

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

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

​

ユーザーの識別

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

タイムシート一覧を取得する際は、リクエストを行っているユーザーに属するタイムシートのみを返すために必要です。また、新しいタイムシートを追加する際は、そのタイムシートをリクエスト元のユーザーに関連付けるために必要です。

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

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

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

​

モバイルアプリを実装する

このセクションでは、このシナリオに対応するモバイルアプリケーションの実装方法を見ていきます。

Android での実装を見る

​

ユーザーを認可する

ユーザーを認可するには、Authorization Code Flow with Proof Key for Code Exchange (PKCE) を実装します。モバイルアプリケーションはまず、code_challenge とその生成に使用したメソッドを指定して、ユーザーを authorization URL にリダイレクトする必要があります。

認可 URL への GET リクエストには、次の値を含める必要があります。

Parameter	Description
client_id	Auth0 Client Id の値です。Auth0 Dashboard のアプリケーションの Settings から取得できます。
audience	API Identifier の値です。Auth0 Dashboard の API の Settings から取得できます。
scope	IDトークン と アクセストークン で返される クレーム を決定する スコープ です。たとえば、scope に openid を指定すると、レスポンスに IDトークン が含まれます。このモバイルアプリの例では、次の スコープ を使用します: create:timesheets read:timesheets openid profile email offline_access。これらの スコープ により、モバイルアプリは API を呼び出し、Refresh Token を取得し、IDトークン 内でユーザーの name、picture、email の クレーム を受け取ることができます。
response_type	使用する認証フローを示します。PKCE を使用するモバイルアプリケーションでは、code に設定する必要があります。
code_challenge	code verifier から生成した code challenge です。code challenge の生成方法については、こちらを参照してください。
code_challenge_method	challenge の生成に使用するメソッドです。Auth0 がサポートしているのは S256 のみです。
redirect_uri	ユーザーが認可を許可した後に、Auth0 がブラウザーをリダイレクトする先の URL です。認可コードは URL パラメーター code から取得できます。この URL は、Application’s Settings で有効な callback URL として指定する必要があります。

Android での実装を見る

​

認証情報を取得する

認可 URL へのリクエストが成功すると、以下のレスポンスが返されます。

次に、レスポンスで返されたauthorization_codeを、APIの呼び出しに使用できるアクセストークンと交換できます。以下のデータを含めて、Token URLにPOSTリクエストを送信します。

Parameter	説明
grant_type	authorization_code に設定する必要があります。
client_id	Auth0 Client Id の値です。Auth0 Dashboard の Application の Settings から確認できます。
code_verifier	authorization URL (/authorize) に渡す code_challenge の生成に使用した、暗号学的にランダムなキーです。
code	直前の authorize 呼び出しで受け取った authorization_code です。
redirect_uri	この URL は、前のセクションで /authorize に渡した redirect_uri と一致している必要があります。

Token URL からのレスポンスには、次が含まれます。

{
  "access_token": "eyJz93a...k4laUWw",
  "refresh_token": "GEbRxBN...edjnXbL",
  "id_token": "eyJ0XAi...4faeEoQ",
  "token_type": "Bearer",
  "expires_in":86400
}

• access_token: audience で指定した API のアクセストークン。
• refresh_token: Refresh Token は、offline_access スコープを含め、さらに Dashboard で API の Allow Offline Access を有効にした場合にのみ含まれます。
• id_token: ユーザープロフィール情報を含む IDトークン JWT。
• token_type: トークンの種類を示す文字列で、常に Bearer トークンです。
• expires_in: アクセストークンの有効期限が切れるまでの秒数。

API の呼び出しやユーザープロフィールの取得に使うため、上記の認証情報をローカルストレージに保存する必要があります。

Android での実装を見る。

​

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

ユーザープロファイルを取得するには、モバイルアプリケーションで JWTライブラリ のいずれかを使って IDトークン をデコードできます。これは、トークンの署名を検証することと、クレームを検証することによって行います。IDトークンを検証した後は、ユーザー情報を含むペイロードにアクセスできます。

{
  "email_verified": false,
  "email": "[e-mail]",
  "clientID": "q2hnj2iu...",
  "updated_at": "2016-12-05T15:15:40.545Z",
  "name": "[e-mail]",
  "picture": "https://s.gravatar.com/avatar/dummy.png",
  "user_id": "auth0|58454...",
  "nickname": "test.account",
  "created_at": "2016-12-05T11:16:59.640Z",
  "sub": "auth0|58454..."
}

Android での実装については、こちらを参照してください。

​

スコープに基づいて UI 要素を条件付きで表示する

ユーザーのscopeに応じて、特定の UI 要素を表示または非表示にしたい場合があります。ユーザーに発行されたスコープを確認するには、ユーザーの認証時に付与されたscopeを調べる必要があります。これはすべてのスコープを含む文字列であるため、この文字列に必要なscopeが含まれているかどうかを確認し、その結果に基づいて特定の UI 要素を表示するかどうかを判断する必要があります。

Android での実装を見る

​

API を呼び出す

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

Android での実装を見る。

​

トークンを更新する

Refresh Token には有効期限がないため、ユーザーを実質的に半永久的に認証済みの状態にしておくことができます。したがって、アプリケーションで安全に保管する必要があります。Refresh Token が漏えいした場合や不要になった場合は、Authentication API を使用して失効できます。

アクセストークン を更新するには、認可結果に含まれる Refresh Token を使用して、/oauth/token エンドポイントに POST リクエストを送信します。

Refresh Token が含まれるのは、前回の認可リクエストに offline_access スコープを含め、Auth0 Dashboard で API に対して Allow Offline Access を有効にしている場合のみです。

リクエストには次を含める必要があります。

パラメータ	説明
grant_type	refresh_token に設定する必要があります。
client_id	Auth0 Client Id の値です。Auth0 Dashboard の アプリケーション の Settings から取得できます。
refresh_token	前回の認証結果に含まれる Refresh Token です。

レスポンスには、新しい アクセストークン が含まれます。

{
  "access_token": "eyJz93a...k4laUWw",
  "refresh_token": "GEbRxBN...edjnXbL",
  "id_token": "eyJ0XAi...4faeEoQ",
  "token_type": "Bearer",
  "expires_in":86400
}

Android での実装はこちらをご覧ください。