> ## Documentation Index
> Fetch the complete documentation index at: https://auth0.com/llms.txt
> Use this file to discover all available pages before exploring further.

# PHP API

##### Evan Sims による

このガイドでは、Auth0 PHP SDK を使用して Auth0 を PHP バックエンド API に統合する方法を説明します。ご自身のアカウント向けに設定されたサンプルを使ってこの Quickstart を進められるよう、あらかじめログインしておくことをお勧めします。

> [!NOTE]
>
> **Auth0 を初めてご利用ですか？** [Auth0 の仕組み](https://auth0.com/docs/ja-jp/get-started/auth0-overview)を確認し、OAuth 2.0 フレームワークを使用した [API の認証と認可の実装方法](https://auth0.com/docs/ja-jp/get-started/authentication-and-authorization-flow) についてご覧ください。

## Auth0 API を設定する

### API を作成する

Auth0 Dashboard の [APIs](https://manage.auth0.com/#/apis) セクションで、**Create API** をクリックします。API の名前と identifier を入力します。たとえば `https://quickstarts/api` です。この identifier は、後でアクセストークンの検証を設定する際に `audience` として使用します。**Signing Algorithm** は **RS256** のままにします。

![API を作成する](https://cdn2.auth0.com/docs/1.14550.0/media/articles/server-apis/create-api.png)

デフォルトでは、API はトークンの署名アルゴリズムとして RS256 を使用します。RS256 は秘密鍵と公開鍵のキーペアを使用するため、Auth0 アカウントの公開鍵を使ってトークンを検証します。公開鍵は [JSON Web Key Set (JWKS)](https://auth0.com/docs/ja-jp/secure/tokens/json-web-tokens/json-web-key-sets.md) 形式で提供されており、[こちら](https://\{yourDomain}/.well-known/jwks.json) からアクセスできます。

### 権限を定義する

権限を使用すると、特定のアクセストークンを持つユーザーに代わって、リソースにどのようにアクセスできるかを定義できます。たとえば、ユーザーがマネージャーのアクセスレベルを持っている場合は `messages` リソースへの読み取りアクセスを許可し、管理者のアクセスレベルを持っている場合はそのリソースへの書き込みアクセスを許可する、といった設定が可能です。

許可する権限は、Auth0 Dashboard の [APIs](https://manage.auth0.com/#/apis) セクションにある **Permissions** ビューで定義できます。

![権限を設定する](https://cdn2.auth0.com/docs/1.14550.0/media/articles/server-apis/configure-permissions.png)

> [!NOTE]
>
> この例では `read:messages` スコープを使用します。

この例では、次の内容を示します。

* 受信した HTTP リクエストの `Authorization` ヘッダーに JSON Web トークン (JWT) が含まれているかどうかを確認する方法。
* Auth0 アカウントの [JSON Web Key Set (JWKS)](https://auth0.com/docs/ja-jp/secure/tokens/json-web-tokens/json-web-key-sets.md) を使用して、トークンが有効かどうかを確認する方法。アクセストークンの検証について詳しくは、[Validate Access Tokens](https://auth0.com/docs/ja-jp/secure/tokens/access-tokens/validate-access-tokens.md) を参照してください。

## PHP Backend API との連携

Auth0 が署名したトークンを、PHP で作成したバックエンド API で認可するサンプルアプリケーションを作成してみましょう。ここでは、ドキュメントに適したシンプルな方法で進めます。より堅牢な例については、GitHub 上の [Quickstart app](https://github.com/auth0-samples/auth0-php-api-samples/) もあわせてご確認ください。

### HTTPクライアントとメッセージファクトリーのインストール

Auth0 PHP SDK は、プロジェクトのアーキテクチャとの高い相互運用性を実現するために、多くの PHP-FIG 標準をサポートしています。中でも特に重要なのが [PSR-17](https://www.php-fig.org/psr/psr-17/) と [PSR-18](https://www.php-fig.org/psr/psr-18/) です。これらの標準により、メッセージ処理やリクエスト処理を担うネットワークコンポーネントとして、任意のものを組み込めるようになります。SDK で利用するには、互換性のあるライブラリをプロジェクトにインストールする必要があります。

PHP で最も広く使われているネットワークライブラリは Guzzle ですが、PHP コミュニティには他にも多くの選択肢があります。このサンプルアプリケーションでは Guzzle を使用しましょう。

```bash theme={null}
composer require guzzlehttp/guzzle guzzlehttp/psr7 http-interop/http-factory-guzzle
```

### PHP SDK のインストール

Auth0 PHP SDK を使用するには、PHP の依存関係管理ツールである [Composer](https://getcomposer.org/doc/00-intro.md#installation-linux-unix-macos) が必要です。Composer を使うと、プロジェクトに必要なライブラリを定義し、それらをインストールできます。先に進む前に、Composer がインストールされており、シェルから利用できることを確認してください。

Auth0 PHP SDK をインストールするには、プロジェクトのディレクトリで次のシェルコマンドを実行します。

```bash theme={null}
composer require auth0/auth0-php
```

これにより、プロジェクト内に `vendor` フォルダーが作成され、Auth0 PHP SDK の使用に必要な依存関係がすべてダウンロードされます。さらに、サンプル内で使用される `vendor/autoload.php` ファイルも作成され、このファイルによってアプリケーションの動作に必要なすべてのクラスが読み込まれます。SDK を動作させるには、この autoload ファイルをプロジェクト内で `require` することが重要です。

### SDKを設定する

まず、サンプルアプリケーションの設定を保存するために、プロジェクトのルートディレクトリに `.env` ファイルを作成し、環境変数を入力しましょう。

PHP は `.env` ファイルを単体では読み込めないため、そのためのライブラリをインストールします。サンプルアプリケーションでは特定のライブラリを使用しますが、実際のアプリケーションでは任意の `dotenv` ローダーを使用できます。プロジェクトディレクトリから、次のシェルコマンドを実行してライブラリをインストールしましょう。

```bash lines theme={null}
composer require vlucas/phpdotenv
```

次に、これらのコードサンプルで使用する PHP ソースファイル `index.php` を作成し、サンプルアプリケーション用に Auth0 PHP SDK のインスタンスを設定しましょう。

```php lines theme={null}
<?php

// Composer AutoloaderをインポートしてSDKクラスを使用できるようにする:
require 'vendor/autoload.php';

// .envファイルから環境変数を読み込む:
(Dotenv\Dotenv::createImmutable(__DIR__))->load();

// Auth0クラスを設定でインスタンス化する:
$auth0 = new \Auth0\SDK\Auth0([
    'strategy' => \Auth0\SDK\Configuration\SdkConfiguration::STRATEGY_API,
    'domain' => $_ENV['AUTH0_DOMAIN'],
    'clientId' => $_ENV['AUTH0_CLIENT_ID'],
    'clientSecret' => $_ENV['AUTH0_CLIENT_SECRET'],
    'audience' => ($_ENV['AUTH0_AUDIENCE'] ?? null) !== null ? [trim($_ENV['AUTH0_AUDIENCE'])] : null,
]);
```

### ユーザーを認証する

このサンプルアプリケーションでは、[認可](https://auth0.com/intro-to-iam/authentication-vs-authorization/) に重点を置いています。認可のためにユーザーがバックエンド API にアクセスする前に認証する方法はいくつもあり、たとえば [Auth0 の SPA.js ライブラリ](https://github.com/auth0/auth0-spa-js) を使用できます。このアプローチは、[GitHub プロジェクトに付属するこの Quickstart アプリ](https://github.com/auth0-samples/auth0-php-api-samples/) で紹介されています。どの方法を採用する場合でも、このサンプルアプリケーションを動作させるには、リクエストパラメーターまたはヘッダーを通じてアクセストークンを渡す必要があります。

### アクセストークンの認可

まず、受信した HTTP リクエストから JSON Web トークン (JWT) を取り出す必要があります。GET リクエストの `?token` パラメーター、または `HTTP_AUTHORIZATION` か `Authorization` ヘッダーに含まれているかを確認しましょう。

```php lines theme={null}
// 👆 上記の手順からの続きです。index.phpファイルに追記してください。

$jwt = $_GET['token'] ?? $_SERVER['HTTP_AUTHORIZATION'] ?? $_SERVER['Authorization'] ?? null;
```

次に、token がある場合はデコードしてみましょう：

```php lines theme={null}
// 👆 上記の手順から続きます。index.php ファイルに追記してください。

// トークンが存在する場合、処理します。
if ($jwt !== null) {
    // トークン文字列の前後の空白を除去します。
    $jwt = trim($jwt);

    // Authorization ヘッダーに 'Bearer ' プレフィックスが含まれている場合は削除します。
    if (substr($jwt, 0, 7) === 'Bearer ') {
        $jwt = substr($jwt, 7);
    }

    // トークンのデコードを試みます:
    try {
        $token = $auth0->decode($jwt, null, null, null, null, null, null, \Auth0\SDK\Token::TYPE_TOKEN);
        define('ENDPOINT_AUTHORIZED', true);
    } catch (\Auth0\SDK\Exception\InvalidTokenException $exception) {
        // トークンが無効でした。Auth0 SDK のエラーメッセージを表示します。
        // 実際のアプリケーションでは、独自のエラーメッセージを表示するとよいでしょう。
        die($exception->getMessage());
    }
}
```

API ルーティングの設定によって、これらのチェックの組み込み方は多少異なりますが、原則は同じです。token を確認し、API エンドポイントで認可が必要な場合は、その token が有効でない、または許容できないものであればアクセスを拒否します。

```php lines theme={null}
// 👆 上記の手順から続きます。index.phpファイルに追記してください。

// リクエストは認可されていますか？
if (defined('ENDPOINT_AUTHORIZED')) {
    // JSONレスポンスを返します：
    echo json_encode([
        'authorized' => true,
        'data' => $token->toArray()
    ], JSON_PRETTY_PRINT);

    exit;
}

// HTTP 401 Unauthorizedステータスを発行します：
http_response_code(401);

// JSONレスポンスを返します：
echo json_encode([
    'authorized' => false,
    'error' => [
        'message' => 'You are NOT authorized to be here!'
    ]
], JSON_PRETTY_PRINT);
```

### キャッシュ

これでも動作しますが、実際のアプリケーションでは、Auth0 のレート制限に達したり、不要なネットワークリクエストでアプリケーションの動作が遅くなったりしないよう、キャッシュを使用するのが一般的です。Auth0 PHP SDK は [PSR-6](https://www.php-fig.org/psr/psr-6) と呼ばれるキャッシュインターフェースをサポートしており、[互換性のある任意のキャッシュライブラリ](https://packagist.org/providers/psr/cache-implementation) を組み込むことで、SDK をアーキテクチャに自然に適合させることができます。

このサンプルでは、[Symfony Cache コンポーネント](https://symfony.com/doc/current/components/cache.html) ライブラリを使用します。プロジェクトのルートディレクトリから、次のシェルコマンドを実行してください。

```bash lines theme={null}
composer require symfony/cache
```

次に、それを使用するようSDKに指示するため、SdkConfigurationを更新する必要があります:

```php lines theme={null}
// ✋ SDKがキャッシュを使用できるよう、上記のステップで追加したトークン処理の前にこれを挿入してください。

$tokenCache = new \Symfony\Component\Cache\Adapter\FilesystemAdapter();
$auth0->configuration()->setTokenCache($tokenCache);
```

これで、サンプルアプリケーションはトークン関連のネットワークリクエストをキャッシュするようになります。

> [!NOTE]
>
> ##### 次にできること
>
> | [他のアイデンティティプロバイダーを設定する](https://auth0.com/docs/ja-jp/authenticate/identity-providers) | [多要素認証を有効にする](https://auth0.com/docs/ja-jp/secure/multi-factor-authentication.md) |
> | - | - |
> | [攻撃対策について学ぶ](https://auth0.com/docs/ja-jp/secure/attack-protection.md) | [ルールについて学ぶ](https://auth0.com/docs/ja-jp/customize/rules.md) |
> | [GitHubで編集する](https://github.com/auth0/docs/edit/master/articles/quickstart/backend/aspnet-core-webapi/01-authorization.md) | |

***