API およびモバイルの設定（モバイルアプリ + API）

Mobile + 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 がヘッダーにベアラー アクセストークン を含むリクエストを受け取った場合、まず行うべきことはトークンの検証です。これには一連の手順があり、そのいずれかに失敗した場合は、呼び出し元のアプリに対して 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 とその生成に使用したメソッドを付けて、ユーザーを 認可 URL にリダイレクトする必要があります。

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

Parameter	Description
client_id	Auth0 のクライアントIDの値です。Auth0 Dashboard の Application の Settings から取得できます。
audience	API Identifier の値です。Auth0 Dashboard の API の Settings から取得できます。
scope	IDトークンとアクセストークンで返されるクレームを決定するスコープです。たとえば、openid スコープを指定すると、レスポンスに IDトークン が含まれます。このモバイルアプリの例では、次のスコープを使用します: create:timesheets read:timesheets openid profile email offline_access。これらのスコープにより、モバイルアプリは API を呼び出し、リフレッシュトークン を取得し、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 で有効なコールバック URL として設定する必要があります。

Android での実装を参照してください。

​

認証情報を取得する

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

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

パラメーター	説明
grant_type	authorization_code に設定する必要があります。
client_id	Auth0 クライアントID の値です。Auth0 Dashboard のアプリケーション設定から確認できます。
code_verifier	認可 URL (/authorize) に渡す code_challenge の生成に使用した、暗号学的にランダムなキーです。
code	前回の /authorize 呼び出しで受け取った authorization_code です。
redirect_uri	この URL は、前のセクションで /authorize に渡した redirect_uri と一致している必要があります。

トークンURLからのレスポンスには、次の内容が含まれます。

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

• access_token: API 用のアクセストークンです。audience で指定します。
• 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はすべてのスコープを含む文字列であるため、必要なscopeが含まれているかを確認し、その結果に応じて特定の UI 要素を表示するかどうかを判断します。

Android での実装を参照

​

API を呼び出す

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

Android での実装を参照してください。

​

トークンを更新する

リフレッシュトークンには有効期限がなく、ユーザーは実質的に無期限で認証済みの状態を維持できるため、アプリケーションで安全に保管する必要があります。リフレッシュトークンが漏えいした場合や不要になった場合は、Authentication API を使用して失効できます。

アクセストークンを更新するには、認可結果から取得した リフレッシュトークン を使用して、/oauth/token エンドポイントに POST リクエストを送信します。

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

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

パラメーター	説明
grant_type	refresh_token に設定する必要があります。
client_id	Auth0 のクライアントIDの値です。Auth0 Dashboard のアプリケーション設定から取得できます。
refresh_token	前回の認証結果から取得した、使用するリフレッシュトークンです。

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

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

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