メインコンテンツへスキップ
このセクションでは、当社シナリオでAPIを実装する方法を説明します。
分かりやすくするために、実装では認証と認可に焦点をあてています。サンプルからも分かるとおり、入力のタイムシートエントリーはハードコードされるため、APIはタイムシートエントリーを保持しません。代わりに、情報の一部をエコーバックします。

​
APIエンドポイントの定義

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

APIエンドポイントとは

APIエンドポイントはたとえば、レストランAPIには/ordersや/customersなどのエンドポイントがあるかもしれません。このAPIに接続するアプリケーションは、関連するHTTPメソッド（POST、GET、PUT、PATCH、DELETE）を使ってAPIエンドポイントを呼び出すことにより、CRUD操作（作成、読み取り、更新、削除）を実行することができます。
この実装では、2つのエンドポイントのみ定義します。1つは従業員の全タイムシートのリストを取得するため、もう1つは従業員がタイムシートエントリーを新規作成できるようにするためのものです。 /timesheetsエンドポイントへのHTTP GET要求は、ユーザーがタイムシートを取得できるようにし、/timesheetsへのHTTP POST要求は、ユーザーが新たなタイムシートを追加できるようにします。 Node.js

​
エンドポイントのセキュリティ確保

APIがヘッダーの一部にBearerアクセストークンのある要求を受け取った場合、最初にすべきことはトークンの検証です。これは複数の手順で構成され、そのうち1つでも失敗した場合、要求は、Missing or invalid tokenという呼び出し元アプリへのエラーメッセージとともに拒否されなければなりません。 APIは以下の検証を実行すべきです。
  • が整形式であることを確認する
  • 署名を確認する
  • 標準クレームを検証する
JWT.ioは、JWTの解析から署名・クレームの検証まで、ほとんどの作業に役立つライブラリーのリストを提供します。
検証プロセスにはクライアント権限（スコープ）の確認も含まれますが、これに関しては次の段落で別に説明します。 アクセストークン検証の詳細については、「アクセストークンを検証する」を参照してください。 Node.js

​
クライアントの権限の確認

この段階ではJWTの有効性が検証されています。最後の手順は、クライアントが保護されたリソースにアクセスするために必要な権限を持っているかどうかを検証することです。 そのためには、APIがデコードされたJWTのスコープを確認する必要があります。このクレームはペイロードの一部で、スペースで区切られた文字列のリストです。 Node.js

​
ユーザーIDの判断

どちらのエンドポイント（タイムシートのリスト取得用と新規タイムシート追加用）でも、ユーザーのIDを判断する必要があります。 これは、タイムシートのリスト取得に関しては、要求元のユーザーのタイムシートのみを返すようにするためです。一方の新規タイムシートの追加に関しては、タイムシートがその要求元のユーザーと関連付けられていることを確認するためです。 標準JWTクレームの1つは、クレームの対象である本人を識別するsubクレームです。暗黙的付与フローの場合、このクレームにはAuth0ユーザーの一意の識別子であるIDが含まれます。これを使って、外部システムのいかなる情報でも、特定ユーザーに関連付けることができます。 また、カスタムクレームを使って、メールアドレスなど別のユーザー属性をアクセストークンに追加し、ユーザーを一意に識別することもできます。 Node.js

​
モバイルアプリの実装

このセクションでは、当社シナリオでモバイルアプリケーションを実装する方法を説明します。 Androidでの実装を参照してください。

​
ユーザーの認可

ユーザーを認可するには、Proof Key for Code Exchange（PKCE）での認可コードフローを実装します。モバイルアプリケーションは最初に、code_challengeおよび生成するために使用するメソッドと一緒に、ユーザーを認可URLに送信する必要があります。 認可URLへのGET要求は、以下の値を含める必要があります。
パラメーター説明
client_idAuth0クライアントIDの値です。Auth0 Dashboardにあるアプリケーションの設定から取得できます。
audienceAPI識別子の値です。Auth0 DashboardにあるAPIの設定から取得できます。
scopeIDトークンとアクセストークンで返されるクレームを決定するスコープ です。たとえば、openidスコープではIDトークンが返されます。提供しているモバイルアプリの例では、次のスコープを使用しています：create:timesheets read:timesheets openid profile email offline_access。これらのスコープによって、モバイルアプリはAPIを呼び出し、を取得して、IDトークンでユーザーのname、picture、emailクレームを返すことができます。
response_type使用する認証フローです。PKCEを使用するモバイルアプリケーションの場合は、これをcodeに設定します。
code_challengeコード検証が生成したコードチャレンジです。コードチャレンジの生成方法については、こちらを参照してください。
code_challenge_methodチャレンジの生成方法です。Auth0はS256のみに対応しています。
redirect_uriユーザーが認可された後に、Auth0がブラウザーをダイレクトするURLです。認可コードはURLパラメーターのcodeにあります。このURLは、有効なコールバックURLとしてアプリケーションの設定で指定されなければなりません。
Androidでの実装を参照してください。

​
資格情報の取得

認可URLへの要求が成功したら、以下の応答を受け取ります。 次に、応答の認可コードをAPIを呼び出すのに使用するアクセストークンと交換します。以下のデータを含めて、トークン URLへのPOST要求を実行します。
パラメーター説明
grant_typeauthorization_codeに設定する必要があります。
client_idAuth0クライアントIDの値です。これは、Auth0 Dashboardにあるアプリケーションの［Settings（設定）］で取得できます。
code_verifier認可URL（/authorize）に渡すcode_challengeの生成に使用された暗号的にランダムなキーです。
code前回の認可呼び出しで受け取ったauthorization_codeです。
redirect_uri前のセクションで/authorizeに渡されたredirect_uriとURLが一致しなければなりません。
トークン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 :リフレッシュトークンは、offline_accessスコープを含め、DashboardでAPIの**［Allow Offline Access（オフラインアクセスの許可）］** を有効にした場合にのみ表示されます。
  • id_token :ユーザープロファイル情報が入ったIDトークンJWT
  • token_type :トークンのタイプを含む文字列で、常にベアラートークンです。
  • expires_in :アクセストークンの有効期限が切れるまでの秒数。
APIの呼び出しとユーザープロファイルの取得に使用するために、上記の資格情報をローカルストレージに保存しておく必要があります。 Androidでの実装を参照してください。

​
ユーザープロファイルの取得

ユーザープロファイルを取得するために、モバイルアプリケーションはJWTライブラリーの１つを使用して、IDトークンをデコードすることができます。これは、署名を検証して、トークンのクレームを検証することで行えます。IDトークンを検証したら、ユーザー情報を含んだペイロードにアクセスできます。 
{
  "email_verified": false,
  "email": "test.account@userinfo.com",
  "clientID": "q2hnj2iu...",
  "updated_at": "2016-12-05T15:15:40.545Z",
  "name": "test.account@userinfo.com",
  "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から安全なリソースにアクセスするには、認証されたユーザーのアクセストークンを、送信される要求に入れる必要があります。これには、Bearerスキームを使用して、Authorizationヘッダー内でアクセストークンを送る必要があります。 Androidでの実装を参照してください。

​
トークンの更新

リフレッシュトークンは、有効期限がなく、ユーザーに対し、実質的に永久に承認された状態でいることを可能にするため、アプリケーションで安全に保管されなければなりません。リフレッシュトークンが侵害された場合、または不要になった場合は、Authentication APIを使用してリフレッシュトークンを取り消すことができます。
アクセストークンをリフレッシュするには、認可結果のリフレッシュトークンを使用して、/oauth/tokenエンドポイントへのPOST要求を実行します。 リフレッシュトークンは、offline_accessスコープを先行の認可要求に含め、DashboardでAPIの**［Allow Offline Access（オフラインアクセスの許可）］** を有効にした場合にのみ表示されます。 要求には以下を含める必要があります。
パラメーター説明
grant_typerefresh_tokenに設定する必要があります。
client_idAuth0クライアントIDの値。これはAuth0 Dashboardにある［Application（アプリケーション）］の［Settings（設定）］で取得できます。
refresh_token前回の認証結果から使用するリフレッシュトークン。
応答には、新しいアクセストークンが含まれます。 
{
  "access_token": "eyJz93a...k4laUWw",
  "refresh_token": "GEbRxBN...edjnXbL",
  "id_token": "eyJ0XAi...4faeEoQ",
  "token_type": "Bearer",
  "expires_in":86400
}
Androidでの実装を参照してください。