失効トークンの除去)アクセストークンの発行(クライアント管理トークンのリクエストトークンのリフレッシュ)パスワードグラントのトークン(パスワードグラントクライアントの作成トークンのリクエスト全スコープの要求)パーソナルアクセストークン(パーソナルアクセスクライアントの作成パーソナルアクセストークンの管理)ルート保護(ミドルウェアによる保護アクセストークンの受け渡し)トークンのスコープ(スコープの定義トークンへのスコープ割り付けスコープのチェック)APIをJavaScriptで利用イントロダクションLaravelでは古典的なログインフォームによる認証は、簡単に実行できるようになっています。通常APIでは、ユーザの認証にトークンを使用し、リクエスト間のセッション状態は保持されません。Passportを使えば、短時間で簡単にAPI認証ができます。OAuth2サーバ上に構築しています。このドキュメントは皆さんが、OAuth2に慣れていることを前提にしています。OAuth2について知らなければ、この先を続けて読む前に、一般的な用語とOAuth2の機能について予習してください。インストールComposerパッケージマネージャにより、Passportをインストールすることからはじめましょう。laravel/passport次に、config/app.php設定ファイルのproviders配列で、Passportサービスプロバイダを登録します。Laravel\Passport\PassportServiceProvider::class,Passportサービスプロバイダはフレームワークに対し、自身のマイグレーションディレクトリを登録します。そのためにプロバイダを登録後、データベースのマイグレーションを実行する必要があります。Passportのマイグレーションは、アプリケーションで必要となる、クライアントとアクセストークンを保存しておくテーブルを作成します。migrate次に、passport:installコマンドを実行します。このコマンドは安全なアクセストークンを生成するのに必要な暗号キーを作成します。アクセストークンを生成するために使用する、「パーソナルアクセス」クライアントと「パスワードグラント」クライアントも作成します。passport:installこのコマンドを実行後、App\UserモデルへLaravel\Passport\HasApiTokensトレイトを追加してください。このトレイトは認証済みユーザのトークンとスコープを確認するためのヘルパーメソッドをモデルに提供します。Notifiable;}次に、AuthServiceProviderのbootメソッドから、Passport::routesメソッドを呼び出す必要があります。このメソッドはアクセストークンの発行、アクセストークンの失効、クライアントとパーソナルアクセストークンの管理のルートを登録します。}}最後に、config/auth.php設定ファイル中で、ガードのapi認証のdriverオプションをpassportへ変更します。これにより、認証のAPIリクエストが送られてきた時に、パスポートのTokenGuardを使用するように、アプリケーションへ指示します。JavaScriptフレームワークを使用する必要があります。CSSフレームワークを使用しています。皆さんがこれらのツールを使用しない場合でも、フロントエンド実装の参考として、これらのコンポーネントは役立つでしょう。APIを初めから提供しています。したAPIに関連するフロントエンドをコーディングするには時間を要します。そこで、Passportは実装例、もしくは実装の開始地点として役立ててもらうため、Vueコンポーネントも用意しています。Artisanコマンドを使用します。--tag=passport-components公開されたコンポーネントは、resources/assets/js/componentsディレクトリへ設置されます。公開したコンポーネントは、resources/assets/js/app.jsファイルで登録してください。require(&#39;./components/passport/PersonalAccessTokens.vue&#39;));コンポーネントの公開後、クライアントとアクセストークンの作成を開始する前に、アプリケーションのテンプレートへ以下のコードをコピーしてください。&lt;passport-clients&gt;&lt;/passport-clients&gt;&lt;passport-authorized-clients&gt;&lt;/passport-authorized-clients&gt;&lt;passport-personal-access-tokens&gt;&lt;/passport-personal-access-tokens&gt;設定トークン持続時間デフォルトでPassportは、再生成する必要のない、長期間持続するアクセストークンを発行します。トークンの持続時間をもっと短くしたい場合は、tokensExpireInとrefreshTokensExpireInメソッドを使ってください。これらのメソッドは、AuthServiceProviderのbootメソッドから呼び出してください。Passport::refreshTokensExpireIn(Carbon::now()-&gt;addDays(30));}失効トークンの除去Passportはデフォルトとして、データベースから失効したアクセストークンを削除しません。長い間にこうしたトークンがデータベース上へ積み残り、莫大な数に成り得ます。失効トークンを自動的に削除するようにPassportを設定する場合は、AuthServiceProviderのbootメソッドから、pruneRevokedTokensメソッドを呼び出してください。Laravel\Passport\Passport;Passport::pruneRevokedTokens();このメソッドは、即時に全失効トークンを削除しません。代わりにユーザが新しいトークンを要求するか、存在するトークンをリフレッシュした場合に、失効トークンを削除します。アクセストークンの発行OAuth2で認証コードを使いこなせるかは、どの程度開発者がOAuth2に慣れているかによります。認証コードを使用する時、クライアントアプリケーションはそのクライアントに対するアクセストークン発行のリクエストが許可されようと、拒絶されようと、あなたのサーバにそのユーザをリダイレクトします。クライアント管理あなたのアプリケーションのAPIと連携する必要のある、アプリケーションを構築しようとしている開発者たちは、最初に「クライアント」を作成することにより、彼らのアプリケーションを登録しなくてはなりません。通常、アプリケーションの名前と、許可のリクエストをユーザが承認した後に、アプリケーションがリダイレクトされるURLにより、登録情報は構成されます。Artisanコマンドを使うことです。このコマンドは、OAuth2の機能をテストするため、皆さん自身のクライアントを作成する場合に使用できます。clientコマンドを実行すると、Passportはクライアントに関する情報の入力を促し、クライアントIDとシークレットを表示します。APIを提供しています。これにより、クライアントを作成、更新、削除するコントローラをわざわざコードする手間を省略できます。APIと、ユーザにクライアントを管理してもらうダッシュボードを提供する、皆さん自身のフロントエンドを組み合わせる必要はあります。以降では、クライアントを管理するための全APIエンドポイントを確認していきます。エンドポイントに対するHTTPリクエストの作成をデモンストレーションするのに便利なため、Vueを使っていきましょう。クライアント管理のフロントエンドを自分で実装したくなければ、フロントエンド・クイックスタートを使い、短時間で完全に機能するフロントエンドを用意できます。/oauth/clientsこのルートは認証されたユーザの全クライアントを返します。ユーザのクライアントの全リストは、主にクライアントを編集、削除する場合に役立ちます。/oauth/clientsこのルートは新クライアントを作成するために使用します。これには2つのデータが必要です。クライアントの名前(name)と、リダイレクト(redirect)のURLです。redirectのURLは許可のリクエストが承認されるか、拒否された後のユーザのリダイレクト先です。クライアントを作成すると、クライアントIDとクライアントシークレットが発行されます。これらの値はあなたのアプリケーションへリクエストし、アクセストークンを取得する時に使用されます。クライアント作成ルートは、新しいクライアントインスタンスを返します。/oauth/clients/{client-id}このルートはクライアントを更新するために使用します。それには2つのデータが必要です。クライアントのnameとredirectのURLです。redirectのURLは許可のリクエストが承認されるか、拒否されたあとのユーザのリダイレクト先です。このルートは更新されたクライアントインスタンスを返します。/oauth/clients/{client-id}このルートはクライアントを削除するために使用します。});トークンのリクエスト許可のリダイレクトクライアントが作成されると、開発者はクライアントIDとシークレットを使用し、あなたのアプリケーションへ許可コードとアクセストークンをリクエストするでしょう。API利用側アプリケーションは以下のように、あなたのアプリケーションの/oauth/authorizeルートへのリダイレクトリクエストを作成する必要があります。/oauth/authorizeルートは、既にPassport::routesメソッドが定義づけていることを覚えておいてください。このルートを自分で定義する必要はありません。許可のリクエストを受け取ると、Passportはユーザがその許可のリクエストを承認するか、拒絶するかのテンプレートを自動的に表示します。ユーザが許可した場合、API利用側アプリケーションが指定したredirect_uriへリダイレクトします。redirect_uriは、クライアントを作成した時に指定したredirectのURLと一致する必要があります。Artisanコマンドを使い、Passportのビューを公開(Laravel用語でリソースを用意すること)する必要があります。公開されたビューは、resources/views/vendor/passportへ設置されます。--tag=passport-views許可コードからアクセストークンへの変換ユーザが許可リクエストを承認したら、API使用側アプリケーションへリダイレクトされます。使用側はあなたのアプリケーションへ、アクセストークンをリクエストするため、POSTリクエストを送信する必要があります。そのリクエストには、ユーザが許可リクエストを承認した時に発行された許可コードを含める必要があります。HTTPライブラリでPOSTリクエストを作成してみましょう。true);});この/oauth/tokenルートは、access_token、refresh_token、expires_in属性を含むJSONレスポンスを返します。expires_in属性は、アクセストークンが無効になるまでの秒数を含んでいます。/oauth/authorizeルートと同様に、/oauth/tokenルートはPassport::routesメソッドが定義しています。このルートを自分で定義する必要はありません。トークンのリフレッシュアプリケーションが短い有効期限のアクセストークンを発行している場合に、ユーザはアクセストークンを発行する時に提供しているリフレッシュトークンを使用し、アクセストークンをリフレッシュする必要が起きます。HTTPライブラリを使用し、トークンをリフレッシュする例です。true);この/oauth/tokenルートは、access_token、refresh_token、expires_in属性を含むJSONレスポンスを返します。expires_in属性は、アクセストークンが無効になるまでの秒数を含んでいます。パスワードグラントのトークンOAuth2のパスワードグラントはモバイルアプリケーションのような、その他のファーストパーティクライアントへ、メールアドレス/ユーザ名とパスワードを使ったアクセストークンの取得を提供します。Codeリダイレクトフローに完全に従うことをユーザへ要求せずとも、アクセストークンを安全に発行できます。パスワードグラントクライアントの作成パスワードグラントによりあなたのアプリケーションがトークンを発行できるようにする前に、パスワードグラントクライアントを作成する必要があります。それには、passport:clientコマンドで--passwordを使用してください。passport:installコマンドを実行済みの場合、このコマンドを実行する必要はありません。--passwordトークンのリクエストパスワードグラントクライアントを作成したら、ユーザのメールアドレスとパスワードを指定し、/oauth/tokenルートへPOSTリクエストを発行することで、アクセストークンをリクエストできます。このルートは、Passport::routesメソッドが登録しているため、自分で定義する必要がないことを覚えておきましょう。リクエストに成功すると、サーバーからaccess_tokenとrefresh_tokenのJSONレスポンスを受け取ります。アクセストークンはデフォルトで、長期間有効であることを記憶しておきましょう。必要であれば自由に、アクセストークンの最長持続時間を設定できます。全スコープの要求パスワードグラントを使用時は、あなたのアプリケーションでサポートする、全スコープを許可するトークンを発行したいと考えるかと思います。*スコープをリクエストすれば可能です。*スコープをリクエストすると、そのトークンインスタンスのcanメソッドは、いつもtrueを返します。このスコープは「パスワード」グラントを使って発行されたトークのみに割り付けるのが良いでしょう。],]);パーソナルアクセストークンときどき、あなたのユーザが典型的なコードリダイレクションフローに従うのではなく、自分たち自身でアクセストークンを発行したがることもあるでしょう。あなたのアプリケーションのUIを通じて、ユーザ自身のトークンを発行を許可することにより、あなたのAPIをユーザに経験してもらう事ができますし、全般的なアクセストークン発行するシンプルなアプローチとしても役立つでしょう。パーソナルアクセストークンは常に長期間有効です。tokensExpireInやrefreshTokensExpireInメソッドを使用しても、有効期間を変更できません。パーソナルアクセスクライアントの作成あなたのアプリケーションでパーソナルアクセストークンを発行できるようにする前に、パーソナルアクセスクライアントを作成する必要があります。--personalオプションを付け、passport:clientコマンドを実行すれば、作成できます。passport:installコマンドを実行済みの場合、このコマンドを実行する必要はありません。--personalパーソナルアクセストークンの管理パーソナルアクセスクライアントを作成したら、UserモデルインスタンスのcreateTokenメソッドを使用し、指定ユーザに対しトークンを発行することができるようになります。createTokenメソッドは最初の引数として、トークンの名前を受け付けます。任意の第2引数として、スコープの配列を指定できます。APIも持っています。パーソナルアクセストークンを管理するダッシュボードをユーザへ提供するため、これを皆さんの自身のフロントエンドと組み合わせてください。以降で、パーソナルアクセストークンを管理する全APIエンドポイントを確認していきます。エンドポイントへのHTTPリクエストを作成するデモンストレーションのため、Vueを使っていきます。パーソナルアクセストークンのフロントエンドを自分自身で実装したくない場合は、フロントエンドクイックスタートを使用して、短時間に完全な機能を持つフロントエンドを用意できます。/oauth/scopesこのルートはあなたのアプリケーションで定義した、全スコープを返します。このルートを使い、ユーザがパーソナルアクセストークンに割り付けたスコープをリストできます。/oauth/personal-access-tokensこのルートは認証中のユーザが作成したパーソナルアクセストークンを全て返します。ユーザがトークンの編集や削除を行うため、全トークンをリストするために主に使われます。/oauth/personal-access-tokensこのルートは新しいパーソナルアクセストークンを作成します。トークンの名前(name)と、トークンに割り付けるスコープ(scope)の、2つのデータが必要です。/oauth/personal-access-tokens/{token-id}このルートはパーソナルアクセストークンを削除するために使用します。tokenId);ルート保護ミドルウェアによる保護Passportは送信されてきたリクエスト上のアクセストークンをバリデートする、認証ガードを用意しています。passportドライバをapiガードで使うように設定すれば、あとはアクセストークンをバリデートしたいルートに、auth:apiミドルウェアを指定するだけです。//})-&gt;middleware(&#39;auth:api&#39;);アクセストークンの受け渡しPassportにより保護されているルートを呼び出す場合、あなたのアプリケーションのAPI利用者は、リクエストのAuthorizationヘッダとして、アクセストークンをBearerトークンとして指定する必要があります。HTTPライブラリを使う場合を例として示します。],]);トークンのスコープスコープの定義スコープは、あるアカウントにアクセスする許可がリクエストされたとき、あなたのAPIクライアントに限定された一連の許可をリクエストできるようにします。eコマースアプリケーションを構築している場合、全API利用者へ発注する許可を与える必要はないでしょう。代わりに、利用者へ注文の発送状況にアクセスできる許可を与えれば十分です。言い換えれば、スコープはアプリケーションユーザに対し、彼らの代理としてのサードパーティアプリケーションが実行できるアクションを制限できるようにします。AuthServiceProviderのbootメソッドの中で、Passport::tokensCanメソッドを用い、皆さんのAPIのスコープを定義できます。tokenCanメソッドはスコープ名とスコープの説明の配列を引数に取ります。スコープの説明はお望み通りに記述でき、許可の承認ページでユーザに表示されます。許可コードグラントを用い、アクセストークンをリクエストする際、利用者はscopeクエリ文字列パラメータとして、希望するスコープを指定する必要があります。scopeパラメータはスコープを空白で区切ったリストです。redirect(&#39;http://your-app.com/oauth/authorize?&#39;.$query);});パーソナルアクセストークン発行時UserモデルのcreateTokenメソッドを使用し、パーソナルアクセストークンを発行する場合、メソッドの第2引数として希望するスコープを配列で渡します。[&#39;place-orders&#39;])-&gt;accessToken;スコープのチェックPassportには、指定されたスコープが許可されているトークンにより、送信されたリクエストが認証されているかを確認するために使用できる、2つのミドルウエアが用意されています。これを使用するには、app/Http/Kernel.phpファイルの$routeMiddlewareプロパティーへ、以下のミドルウェアを追加してください。\Laravel\Passport\Http\Middleware\CheckForAnyScope::class,全スコープの確認scopesミドルウェアは、リストしたスコープが全て、送信されてきたリクエストのアクセストークンに含まれていることを確認するため、ルートへ指定します。アクセストークンは&quot;check-status&quot;と&quot;place-orders&quot;、両スコープを持っている})-&gt;middleware(&#39;scopes:check-status,place-orders&#39;);一部のスコープの確認scopeミドルウエアは、リストしたスコープのうち、最低1つが送信されてきたリクエストのアクセストークンに含まれていることを確認するため、ルートへ指定します。Instanceアクセストークンが確認されたリクエストがアプリケーションにやってきた後でも、認証済みのUserインスタンスへtokenCanメソッドを使用し、トークンが指定したスコープを持っているかを確認できます。}});APIをJavaScriptで利用API構築時にJavaScriptアプリケーションから、自分のAPIを利用できたらとても便利です。このAPI開発のアプローチにより、世界中で共有されるのと同一のAPIを自身のアプリケーションで使用できるようになります。自分のWebアプリケーションやモバイルアプリケーション、サードパーティアプリケーション、そして様々なパッケージマネージャ上で公開するSDKにより、同じAPIが使用されます。通常、皆さんのAPIをJavaScriptアプリケーションから使用しようとするなら、アプリケーションに対しアクセストークンを自分で送り、それを毎回リクエストするたび、一緒にアプリケーションへ渡す必要があります。Passportにはこれを皆さんに変わって処理するミドルウェアが用意してあります。必要なのは、webミドルウェアグループにCreateFreshApiTokenミドルウェアを追加することだけです。\Laravel\Passport\Http\Middleware\CreateFreshApiToken::class,],このPassportミドルウェアはlaravel_tokenクッキーを送信するレスポンスへ付加します。このクッキーはPassportが、皆さんのJavaScriptアプリケーションからのAPIリクエストを認可するために使用する、暗号化されたJWTを含んでいます。これで、アクセストークンを明示的に渡さなくても、あなたのアプリケーションのAPIへリクエストを作成できるようになります。});この認証メソッド使う場合、全リクエストのX-CSRF-TOKENヘッダを通して、CSRFトークンを送る必要があります。フレームワークに含まれる、デフォルトのVue設定を使用すると、Laravelは自動的にこのヘッダを送信します。他のJavaScriptフレームワークを使用している場合は、確実にこのヘッダと共に、各リクエストを送信してください。readme.md).これは次期リリース版の翻訳で、コミュニティにより翻訳されています。