auth0-php-api

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Auth0 PHP API Integration

Auth0 PHP API 集成

Protect PHP API endpoints with JWT access token validation using

auth0/auth0-php

in API mode (

STRATEGY_API

使用

auth0/auth0-php

的API模式（

STRATEGY_API

），通过JWT访问令牌验证来保护PHP API端点。

Prerequisites

前置条件

PHP 8.2+ with extensions:
```
mbstring
```
,
```
openssl
```
,
```
json
```
Composer installed
Auth0 API resource configured (not an Application - must be an API)
If you don't have Auth0 set up yet, use the
```
auth0-quickstart
```
skill first

PHP 8.2+ 及扩展：
```
mbstring
```
、
```
openssl
```
、
```
json
```
已安装 Composer
已配置 Auth0 API 资源（不是应用程序，必须是API）
如果尚未设置 Auth0，请先使用
```
auth0-quickstart
```
技能

When NOT to Use

不适用于以下场景

PHP web applications with login/logout flows - Use
```
auth0-php
```
for session-based authentication
Laravel applications - Use
```
auth0/laravel-auth0
```
which has built-in API guard support
Symfony applications - Use
```
auth0/symfony
```
with its security bundle
Single Page Applications - Use
```
auth0-react
```
,
```
auth0-vue
```
, or
```
auth0-angular
```
for client-side auth
Issuing tokens - This skill is for validating access tokens, not issuing them

带有登录/登出流程的PHP Web应用 - 使用
```
auth0-php
```
进行基于会话的身份验证
Laravel 应用 - 使用
```
auth0/laravel-auth0
```
，它内置了API守卫支持
Symfony 应用 - 使用
```
auth0/symfony
```
及其安全 bundle
单页应用（SPA） - 使用
```
auth0-react
```
、
```
auth0-vue
```
或
```
auth0-angular
```
进行客户端身份验证
签发令牌 - 本技能用于验证访问令牌，而非签发令牌

Quick Start Workflow

快速开始流程

1. Install SDK

1. 安装SDK

bash

composer require auth0/auth0-php vlucas/phpdotenv guzzlehttp/guzzle guzzlehttp/psr7 "symfony/cache:^7.0"

```
auth0/auth0-php
```
- The Auth0 SDK (v8.x)
```
vlucas/phpdotenv
```
- Load
```
.env
```
files into
```
$_ENV
```
```
guzzlehttp/guzzle
```
+
```
guzzlehttp/psr7
```
- PSR-18 HTTP client required by the SDK
```
symfony/cache
```
- PSR-6 cache for JWKS key caching (recommended for production)

bash

composer require auth0/auth0-php vlucas/phpdotenv guzzlehttp/guzzle guzzlehttp/psr7 "symfony/cache:^7.0"

```
auth0/auth0-php
```
- Auth0 SDK（v8.x版本）
```
vlucas/phpdotenv
```
- 将
```
.env
```
文件加载到
```
$_ENV
```
中
```
guzzlehttp/guzzle
```
+
```
guzzlehttp/psr7
```
- SDK所需的PSR-18 HTTP客户端
```
symfony/cache
```
- 用于JWKS密钥缓存的PSR-6缓存（生产环境推荐使用）

2. Create Auth0 API

2. 创建Auth0 API

You need an API (not Application) in Auth0.

STOP - ask the user before proceeding.

Ask exactly this question and wait for their answer before doing anything else:
"How would you like to create the Auth0 API resource?
Automated - I'll run Auth0 CLI scripts that create the resource and write the exact values to your
.env
automatically.
Manual - You create the API yourself in the Auth0 Dashboard (or via
auth0 apis create
) and provide me the Domain and Audience.
Which do you prefer? (1 = Automated / 2 = Manual)"
Do NOT proceed to any setup steps until the user has answered. Do NOT default to manual.

If the user chose Automated, follow the Setup Guide for complete CLI scripts. The automated path writes

.env

for you - skip Step 3 below and proceed directly to Step 4.

If the user chose Manual, follow the Setup Guide (Manual Setup section) for full instructions. Then continue with Step 3 below.

Quick reference for manual API creation:

bash

undefined

你需要在Auth0中创建一个API（不是应用程序）。

暂停 - 继续前请询问用户。

请准确询问以下问题，等待用户回答后再进行下一步：
"你希望如何创建Auth0 API资源？
自动化 - 我将运行Auth0 CLI脚本创建资源，并自动将准确值写入你的
.env
文件。
手动 - 你在Auth0控制台自行创建API（或通过
auth0 apis create
命令），并提供Domain和Audience。
你偏好哪种方式？（1 = 自动化 / 2 = 手动）"
在用户回答前，请勿进行任何设置步骤。请勿默认选择手动方式。

如果用户选择自动化，请遵循设置指南中的完整CLI脚本。自动化流程会为你写入

.env

文件 - 跳过下方的步骤3，直接进入步骤4。

如果用户选择手动，请遵循设置指南（手动设置章节）中的完整说明。然后继续下方的步骤3。

手动创建API的快速参考：

bash

undefined

Using Auth0 CLI

使用Auth0 CLI

auth0 apis create
--name "My PHP API"
--identifier https://my-api.example.com
--json


Or create manually in Auth0 Dashboard -> Applications -> APIs

auth0 apis create
--name "My PHP API"
--identifier https://my-api.example.com
--json


或者在Auth0控制台手动创建 -> 应用程序 -> APIs

3. Configure Environment

3. 配置环境变量

Create

.env

bash

AUTH0_DOMAIN=your-tenant.us.auth0.com
AUTH0_AUDIENCE=https://your-api.example.com

AUTH0_DOMAIN

is your Auth0 tenant domain (without

https://

AUTH0_AUDIENCE

is the API identifier you set when creating the API resource in Auth0.

创建

.env

文件：

bash

AUTH0_DOMAIN=your-tenant.us.auth0.com
AUTH0_AUDIENCE=https://your-api.example.com

AUTH0_DOMAIN

是你的Auth0租户域名（不带

https://

）。

AUTH0_AUDIENCE

是你在Auth0中创建API资源时设置的API标识符。

4. Initialize Auth0 in API Mode

4. 以API模式初始化Auth0

Create

auth0.php

to initialize the SDK:

php

<?php

require 'vendor/autoload.php';

use Auth0\SDK\Auth0;
use Auth0\SDK\Configuration\SdkConfiguration;
use Symfony\Component\Cache\Adapter\FilesystemAdapter;

$dotenv = Dotenv\Dotenv::createImmutable(__DIR__);
$dotenv->load();

$configuration = new SdkConfiguration(
    strategy: SdkConfiguration::STRATEGY_API,
    domain: $_ENV['AUTH0_DOMAIN'],
    clientId: null,
    audience: [$_ENV['AUTH0_AUDIENCE']],
    tokenAlgorithm: 'RS256',
    tokenCache: new FilesystemAdapter('auth0_jwks', 600, __DIR__ . '/var/cache'),
    tokenCacheTtl: 600,
);

$auth0 = new Auth0($configuration);

Key differences from web app mode:

```
STRATEGY_API
```
- stateless, no sessions or cookies
```
clientId
```
is not required for RS256 validation (only needed for HS256)
```
audience
```
accepts an array of allowed audience strings
```
tokenCache
```
is a PSR-6
```
CacheItemPoolInterface
```
for JWKS caching

创建

auth0.php

文件来初始化SDK：

php

<?php

require 'vendor/autoload.php';

use Auth0\SDK\Auth0;
use Auth0\SDK\Configuration\SdkConfiguration;
use Symfony\Component\Cache\Adapter\FilesystemAdapter;

$dotenv = Dotenv\Dotenv::createImmutable(__DIR__);
$dotenv->load();

$configuration = new SdkConfiguration(
    strategy: SdkConfiguration::STRATEGY_API,
    domain: $_ENV['AUTH0_DOMAIN'],
    clientId: null,
    audience: [$_ENV['AUTH0_AUDIENCE']],
    tokenAlgorithm: 'RS256',
    tokenCache: new FilesystemAdapter('auth0_jwks', 600, __DIR__ . '/var/cache'),
    tokenCacheTtl: 600,
);

$auth0 = new Auth0($configuration);

与Web应用模式的主要区别：

```
STRATEGY_API
```
- 无状态，无会话或Cookie
RS256验证不需要
```
clientId
```
（仅HS256需要）
```
audience
```
接受允许的受众字符串数组
```
tokenCache
```
是用于JWKS缓存的PSR-6
```
CacheItemPoolInterface
```

5. Create Middleware Function

5. 创建中间件函数

Since the SDK does not include a built-in middleware, create a reusable guard function. Create

middleware.php

php

<?php

use Auth0\SDK\Auth0;
use Auth0\SDK\Token;
use Auth0\SDK\Exception\InvalidTokenException;

function requireAuth(Auth0 $auth0, ?array $requiredScopes = null): array
{
    $token = $auth0->getBearerToken(
        server: ['HTTP_AUTHORIZATION']
    );

    if ($token === null) {
        http_response_code(401);
        header('Content-Type: application/json');
        echo json_encode(['error' => 'unauthorized', 'message' => 'Missing or invalid Bearer token']);
        exit;
    }

    $claims = $token->toArray();

    if ($requiredScopes !== null) {
        $grantedScopes = isset($claims['scope']) ? explode(' ', $claims['scope']) : [];
        $missingScopes = array_diff($requiredScopes, $grantedScopes);

        if (!empty($missingScopes)) {
            http_response_code(403);
            header('Content-Type: application/json');
            echo json_encode(['error' => 'insufficient_scope', 'message' => 'Token lacks required scopes']);
            exit;
        }
    }

    return $claims;
}

getBearerToken()

searches for a Bearer token at the locations you specify, verifies the signature against the JWKS endpoint, and validates claims (issuer, audience, expiration). The

server

parameter is an array of

$_SERVER

key names to check (e.g.,

['HTTP_AUTHORIZATION']

) - not

$_SERVER

itself. Returns a

TokenInterface

on success or

null

if no valid token is found (does not throw).

由于SDK不包含内置中间件，创建一个可复用的守卫函数。创建

middleware.php

文件：

php

<?php

use Auth0\SDK\Auth0;
use Auth0\SDK\Token;
use Auth0\SDK\Exception\InvalidTokenException;

function requireAuth(Auth0 $auth0, ?array $requiredScopes = null): array
{
    $token = $auth0->getBearerToken(
        server: ['HTTP_AUTHORIZATION']
    );

    if ($token === null) {
        http_response_code(401);
        header('Content-Type: application/json');
        echo json_encode(['error' => 'unauthorized', 'message' => '缺少或无效的Bearer令牌']);
        exit;
    }

    $claims = $token->toArray();

    if ($requiredScopes !== null) {
        $grantedScopes = isset($claims['scope']) ? explode(' ', $claims['scope']) : [];
        $missingScopes = array_diff($requiredScopes, $grantedScopes);

        if (!empty($missingScopes)) {
            http_response_code(403);
            header('Content-Type: application/json');
            echo json_encode(['error' => 'insufficient_scope', 'message' => '令牌缺少所需权限范围']);
            exit;
        }
    }

    return $claims;
}

getBearerToken()

在你指定的位置搜索Bearer令牌，通过JWKS端点验证签名，并验证声明（签发者、受众、过期时间）。

server

参数是要检查的

$_SERVER

键名数组（例如

['HTTP_AUTHORIZATION']

）- 不是

$_SERVER

本身。成功时返回

TokenInterface

，如果未找到有效令牌则返回

null

（不会抛出异常）。

6. Create API Routes

6. 创建API路由

Create

index.php

as a front controller:

php

<?php

require 'auth0.php';
require 'middleware.php';

$method = $_SERVER['REQUEST_METHOD'];
$path = parse_url($_SERVER['REQUEST_URI'], PHP_URL_PATH);

header('Content-Type: application/json');

switch ($path) {
    case '/api/public':
        echo json_encode(['message' => 'Public endpoint - no authentication required']);
        break;

    case '/api/private':
        $claims = requireAuth($auth0);
        echo json_encode(['message' => 'Private endpoint', 'sub' => $claims['sub']]);
        break;

    case '/api/private-scoped':
        $claims = requireAuth($auth0, ['read:messages']);
        echo json_encode(['messages' => [], 'sub' => $claims['sub']]);
        break;

    default:
        http_response_code(404);
        echo json_encode(['error' => 'not_found']);
        break;
}

创建

index.php

作为前端控制器：

php

<?php

require 'auth0.php';
require 'middleware.php';

$method = $_SERVER['REQUEST_METHOD'];
$path = parse_url($_SERVER['REQUEST_URI'], PHP_URL_PATH);

header('Content-Type: application/json');

switch ($path) {
    case '/api/public':
        echo json_encode(['message' => '公开端点 - 无需身份验证']);
        break;

    case '/api/private':
        $claims = requireAuth($auth0);
        echo json_encode(['message' => '私有端点', 'sub' => $claims['sub']]);
        break;

    case '/api/private-scoped':
        $claims = requireAuth($auth0, ['read:messages']);
        echo json_encode(['messages' => [], 'sub' => $claims['sub']]);
        break;

    default:
        http_response_code(404);
        echo json_encode(['error' => 'not_found']);
        break;
}

7. Access Token Claims

7. 访问令牌声明

The decoded JWT claims are returned as an associative array:

php

$claims = requireAuth($auth0);

$userId = $claims['sub'];       // user/client ID
$scopes = $claims['scope'];     // space-separated granted scopes
$issuer = $claims['iss'];       // issuer (your Auth0 domain URL)
$audience = $claims['aud'];     // audience (string or array)
$expiration = $claims['exp'];   // expiration timestamp

You can also use the

Token

object's typed accessor methods:

php

$token = $auth0->getBearerToken(server: ['HTTP_AUTHORIZATION']);
if ($token !== null) {
    $subject = $token->getSubject();     // returns ?string
    $issuer = $token->getIssuer();       // returns ?string
    $audience = $token->getAudience();   // returns ?array
    $expiration = $token->getExpiration(); // returns ?int
}

解码后的JWT声明以关联数组形式返回：

php

$claims = requireAuth($auth0);

$userId = $claims['sub'];       // 用户/客户端ID
$scopes = $claims['scope'];     // 空格分隔的已授权权限范围
$issuer = $claims['iss'];       // 签发者（你的Auth0域名URL）
$audience = $claims['aud'];     // 受众（字符串或数组）
$expiration = $claims['exp'];   // 过期时间戳

你也可以使用

Token

对象的类型化访问器方法：

php

$token = $auth0->getBearerToken(server: ['HTTP_AUTHORIZATION']);
if ($token !== null) {
    $subject = $token->getSubject();     // 返回 ?string
    $issuer = $token->getIssuer();       // 返回 ?string
    $audience = $token->getAudience();   // 返回 ?array
    $expiration = $token->getExpiration(); // 返回 ?int
}

8. Add CORS Headers

8. 添加CORS头

When your API receives requests from a browser-based SPA, add CORS headers. Create

cors.php

php

<?php

function handleCors(array $allowedOrigins): void
{
    $origin = $_SERVER['HTTP_ORIGIN'] ?? '';

    if (in_array($origin, $allowedOrigins, true)) {
        header("Access-Control-Allow-Origin: $origin");
        header('Access-Control-Allow-Methods: GET, POST, PUT, DELETE, OPTIONS');
        header('Access-Control-Allow-Headers: Authorization, Content-Type');
        header('Access-Control-Max-Age: 86400');
    }

    if ($_SERVER['REQUEST_METHOD'] === 'OPTIONS') {
        http_response_code(204);
        exit;
    }
}

Then add these lines at the top of

index.php

, before the existing

require 'auth0.php'

line:

php

require 'cors.php';
handleCors(['https://your-spa-domain.com']);

The updated

index.php

head should be:

php

<?php

require 'cors.php';
handleCors(['https://your-spa-domain.com']);

require 'auth0.php';
require 'middleware.php';

// ... rest of index.php

CORS must be handled before auth so that preflight

OPTIONS

requests short-circuit without triggering token validation.

当你的API接收来自浏览器端SPA的请求时，添加CORS头。创建

cors.php

文件：

php

<?php

function handleCors(array $allowedOrigins): void
{
    $origin = $_SERVER['HTTP_ORIGIN'] ?? '';

    if (in_array($origin, $allowedOrigins, true)) {
        header("Access-Control-Allow-Origin: $origin");
        header('Access-Control-Allow-Methods: GET, POST, PUT, DELETE, OPTIONS');
        header('Access-Control-Allow-Headers: Authorization, Content-Type');
        header('Access-Control-Max-Age: 86400');
    }

    if ($_SERVER['REQUEST_METHOD'] === 'OPTIONS') {
        http_response_code(204);
        exit;
    }
}

然后在

index.php

的顶部添加以下代码，放在现有的

require 'auth0.php'

之前：

php

require 'cors.php';
handleCors(['https://your-spa-domain.com']);

更新后的

index.php

头部应为：

php

<?php

require 'cors.php';
handleCors(['https://your-spa-domain.com']);

require 'auth0.php';
require 'middleware.php';

// ... index.php 的其余部分

CORS必须在身份验证之前处理，以便预请求

OPTIONS

在触发令牌验证前提前结束。

9. Test the API

9. 测试API

Agent instruction: Start the PHP built-in server and verify the basic endpoints work without credentials:
bash
php -S localhost:8000 index.php &
sleep 1
curl -s http://localhost:8000/api/public
curl -s -o /dev/null -w "%{http_code}" http://localhost:8000/api/private
/api/public
should return
{"message":"Public endpoint - no authentication required"}
/api/private
should return HTTP 401
If both pass, the middleware is working. Kill the background server when done:
bash
kill %1 2>/dev/null
Failcheck: If the server fails to start or
/api/public
errors, check for PHP syntax issues or missing
.env
. After 5-6 failed iterations, use
AskUserQuestion
to ask the user for more details about their environment.

Agent instruction: STOP - ask after basic tests pass.

Once public/401 tests pass, ask the user:

"Your API is set up and the middleware is working (public returns 200, private returns 401 without a token). Would you like me to help you set up testing with a real access token?

Yes - I'll help you configure an M2M application to get test tokens.

No - I'm done for now.

Which do you prefer?"

Do NOT proceed with M2M/token setup unless the user says yes. If they say no, summarize what was done and stop.

Agent instruction (M2M app setup - only if user wants testing):

If the user chose to set up testing, ask:

"To test your protected endpoints, you need a Machine-to-Machine (M2M) application authorized to request tokens for this API.

Create new - I'll create a new M2M application and authorize it for this API.

Use existing - You already have an M2M application. Provide the Client ID and I'll authorize it for this API.

Which do you prefer? (1 = Create new / 2 = Use existing)"

Do NOT proceed until the user answers. Do NOT silently pick an existing application from the tenant.

If the user chose "Create new":
bash
auth0 apps create \
  --name "${PWD##*/} (Test App)" \
  --type m2m \
  --no-input --json
Parse the JSON with
jq
to extract
client_id
. Do NOT use
--reveal-secrets
- never expose client secrets in agent context. Then create a client grant:
bash
auth0 api post "client-grants" --data '{
  "client_id": "<CLIENT_ID>",
  "audience": "<API_IDENTIFIER>",
  "scope": ["<SCOPES>"]
}'
If the user chose "Use existing": Ask for the Client ID. Then create a client grant to authorize it for this API:
bash
auth0 api post "client-grants" --data '{
  "client_id": "<USER_PROVIDED_CLIENT_ID>",
  "audience": "<API_IDENTIFIER>",
  "scope": ["<SCOPES>"]
}'
If the grant already exists (409 conflict), that's fine - the app is already authorized.

Agent instruction (TOKEN ISOLATION - CRITICAL):

The agent MUST NEVER directly see or display access token values. Token security rules:
Do NOT run
auth0 test token
on its own - it outputs the token to stdout
Do NOT ask the user to paste their token into the conversation

Do NOT echo, print, or log the token value

Do NOT store the token in a file
Secure testing approach (single-command chain):

If the user explicitly asks to test the protected endpoints, use a single-command chain that captures the token into a shell variable and immediately uses it:
bash
php -S localhost:8000 index.php &
sleep 1
TEST_TOKEN=$(auth0 test token <M2M_CLIENT_ID> --audience <AUDIENCE> --scopes <SCOPE1,SCOPE2> 2>/dev/null | grep -o 'ey[A-Za-z0-9_-]*\.[A-Za-z0-9_-]*\.[A-Za-z0-9_-]*') && \
[ -n "$TEST_TOKEN" ] && echo "Token acquired (${#TEST_TOKEN} chars)" && \
echo "=== GET /api/private ===" && \
curl -s http://localhost:8000/api/private -H "Authorization: Bearer $TEST_TOKEN" && \
echo "" && echo "=== GET /api/private-scoped ===" && \
curl -s http://localhost:8000/api/private-scoped -H "Authorization: Bearer $TEST_TOKEN"
kill %1 2>/dev/null
Rules:
ONLY use when the user explicitly asks to test
Always chain token acquisition + curl in a SINGLE
&&
command
NEVER add
echo $TEST_TOKEN
or any command that would print the raw token value
If the token acquisition fails (empty variable), report that the M2M app may not be authorized

Client ID is REQUIRED - if M2M setup was not completed, ask the user first
If the user does NOT ask to test, just provide the commands for them to run manually:
auth0 test token <CLIENT_ID> --audience <AUDIENCE> --scopes <SCOPE1,SCOPE2>
curl http://localhost:8000/api/private -H "Authorization: Bearer <PASTE_TOKEN_HERE>"

Start the server:

bash

php -S localhost:8000 index.php

Test public endpoint (no token needed):

bash

curl http://localhost:8000/api/public

Test protected endpoint without token (should return 401):

bash

curl http://localhost:8000/api/private

Test protected endpoint with token:

bash

curl http://localhost:8000/api/private \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

Test scoped endpoint:

bash

curl http://localhost:8000/api/private-scoped \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

Get a test token via Auth0 Dashboard -> APIs -> Test tab, or via the M2M flow described above.

Agent指令： 启动PHP内置服务器，验证基础端点在无凭据情况下是否正常工作：
bash
php -S localhost:8000 index.php &
sleep 1
curl -s http://localhost:8000/api/public
curl -s -o /dev/null -w "%{http_code}" http://localhost:8000/api/private
/api/public
应返回
{"message":"公开端点 - 无需身份验证"}
/api/private
应返回HTTP 401
如果两者都通过，说明中间件工作正常。完成后终止后台服务器：
bash
kill %1 2>/dev/null
故障检查： 如果服务器无法启动或
/api/public
报错，请检查PHP语法问题或缺失的
.env
文件。经过5-6次失败尝试后，使用
AskUserQuestion
询问用户更多关于其环境的细节。

Agent指令：基础测试通过后暂停并询问用户。

一旦公开端点/401测试通过，请询问用户：

"你的API已设置完成，中间件工作正常（公开端点返回200，无令牌时私有端点返回401）。你是否需要我帮助你设置使用真实访问令牌的测试？

是 - 我将帮助你配置M2M应用以获取测试令牌。

否 - 我已完成当前操作。

你偏好哪种方式？"

除非用户同意，否则请勿进行M2M/令牌设置。如果用户选择否，总结已完成的操作并停止。

Agent指令（仅当用户需要测试时才进行M2M应用设置）：

如果用户选择设置测试，请询问：

"要测试受保护的端点，你需要一个被授权为此API请求令牌的机器到机器（M2M）应用。

创建新应用 - 我将创建一个新的M2M应用并授权其访问此API。

使用现有应用 - 你已有M2M应用，请提供客户端ID，我将授权其访问此API。

你偏好哪种方式？（1 = 创建新 / 2 = 使用现有）"

在用户回答前请勿继续。请勿从租户中静默选择现有应用。

如果用户选择"创建新应用"：
bash
auth0 apps create \
  --name "${PWD##*/} (Test App)" \
  --type m2m \
  --no-input --json
使用
jq
解析JSON以提取
client_id
。请勿使用
--reveal-secrets
- 切勿在Agent上下文中暴露客户端密钥。然后创建客户端授权：
bash
auth0 api post "client-grants" --data '{
  "client_id": "<CLIENT_ID>",
  "audience": "<API_IDENTIFIER>",
  "scope": ["<SCOPES>"]
}'
如果用户选择"使用现有应用"： 请求用户提供客户端ID。然后创建客户端授权以允许其访问此API：
bash
auth0 api post "client-grants" --data '{
  "client_id": "<USER_PROVIDED_CLIENT_ID>",
  "audience": "<API_IDENTIFIER>",
  "scope": ["<SCOPES>"]
}'
如果授权已存在（409冲突），无需处理 - 应用已被授权。

Agent指令（令牌隔离 - 关键）：

Agent绝对不能直接查看或显示访问令牌值。令牌安全规则：
请勿单独运行
auth0 test token
- 它会将令牌输出到标准输出
请勿要求用户将令牌粘贴到对话中

请勿回显、打印或记录令牌值

请勿将令牌存储在文件中
安全测试方法（单命令链）：

如果用户明确要求测试受保护的端点，请使用单命令链将令牌捕获到shell变量中并立即使用：
bash
php -S localhost:8000 index.php &
sleep 1
TEST_TOKEN=$(auth0 test token <M2M_CLIENT_ID> --audience <AUDIENCE> --scopes <SCOPE1,SCOPE2> 2>/dev/null | grep -o 'ey[A-Za-z0-9_-]*\.[A-Za-z0-9_-]*\.[A-Za-z0-9_-]*') && \
[ -n "$TEST_TOKEN" ] && echo "已获取令牌（${#TEST_TOKEN} 字符）" && \
echo "=== GET /api/private ===" && \
curl -s http://localhost:8000/api/private -H "Authorization: Bearer $TEST_TOKEN" && \
echo "" && echo "=== GET /api/private-scoped ===" && \
curl -s http://localhost:8000/api/private-scoped -H "Authorization: Bearer $TEST_TOKEN"
kill %1 2>/dev/null
规则：
仅在用户明确要求测试时使用
始终将令牌获取+curl放在单个
&&
命令链中
切勿添加
echo $TEST_TOKEN
或任何会打印原始令牌值的命令
如果令牌获取失败（变量为空），报告M2M应用可能未被授权

必须提供客户端ID - 如果未完成M2M设置，请先询问用户
如果用户未要求测试，仅提供供他们手动运行的命令：
auth0 test token <CLIENT_ID> --audience <AUDIENCE> --scopes <SCOPE1,SCOPE2>
curl http://localhost:8000/api/private -H "Authorization: Bearer <PASTE_TOKEN_HERE>"

启动服务器：

bash

php -S localhost:8000 index.php

测试公开端点（无需令牌）：

bash

curl http://localhost:8000/api/public

测试无令牌的受保护端点（应返回401）：

bash

curl http://localhost:8000/api/private

使用令牌测试受保护端点：

bash

curl http://localhost:8000/api/private \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

测试带权限范围的端点：

bash

curl http://localhost:8000/api/private-scoped \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

通过Auth0控制台 -> APIs -> 测试选项卡，或上述M2M流程获取测试令牌。

Common Mistakes

常见错误

Mistake	Fix
Hardcoding `domain` or `audience` in source	Always read from environment variables - never embed credentials in code
Using `STRATEGY_REGULAR` for an API	API mode must use `SdkConfiguration::STRATEGY_API` - it disables sessions and cookies
Installing without a PSR-18 HTTP client	Must have `guzzlehttp/guzzle` or another PSR-18 client or the SDK cannot fetch JWKS
Not caching JWKS keys	Without a PSR-6 cache, the SDK fetches JWKS on every request - always configure `tokenCache`
Passing `audience` as a string	`audience` must be an array: `['https://my-api.example.com']` not `'https://my-api.example.com'`
Passing `domain` as full URL with `https://`	`domain` should be the bare domain, e.g. `my-tenant.us.auth0.com` , not `https://my-tenant.us.auth0.com`
Using `decode()` without specifying token type	Always pass `tokenType: Token::TYPE_ACCESS_TOKEN` when manually calling `decode()`
Echoing exception messages to users	Use `error_log()` for the real error and return a generic JSON error message
Using an ID token instead of an access token	Must use the access token for API auth - ID tokens are for the client app
Created an Application instead of an API in Auth0	Must create an API resource (Applications -> APIs) - an Application doesn't issue access tokens with the right audience
Setting `clientId` and expecting RS256 to need it	For RS256, `clientId` is optional - the SDK validates against the JWKS endpoint
Using `clientSecret` for RS256 validation	`clientSecret` is only needed for HS256 - RS256 uses the public key from JWKS
Passing `$_SERVER` directly to `getBearerToken()`	The `server` param takes an array of key names to look up, e.g. `['HTTP_AUTHORIZATION']` - not `$_SERVER` itself

错误	修复方案
在代码中硬编码 `domain` 或 `audience`	始终从环境变量读取 - 切勿在代码中嵌入凭据
为API使用 `STRATEGY_REGULAR`	API模式必须使用 `SdkConfiguration::STRATEGY_API` - 它会禁用会话和Cookie
安装时未包含PSR-18 HTTP客户端	必须安装 `guzzlehttp/guzzle` 或其他PSR-18客户端，否则SDK无法获取JWKS
未缓存JWKS密钥	没有PSR-6缓存时，SDK会在每次请求时获取JWKS - 始终配置 `tokenCache`
将 `audience` 作为字符串传递	`audience` 必须是数组： `['https://my-api.example.com']` 而非 `'https://my-api.example.com'`
将 `domain` 作为带 `https://` 的完整URL传递	`domain` 应为裸域名，例如 `my-tenant.us.auth0.com` ，而非 `https://my-tenant.us.auth0.com`
调用 `decode()` 时未指定令牌类型	手动调用 `decode()` 时，始终传递 `tokenType: Token::TYPE_ACCESS_TOKEN`
向用户回显异常消息	使用 `error_log()` 记录真实错误，返回通用JSON错误消息
使用ID令牌而非访问令牌	API身份验证必须使用访问令牌 - ID令牌用于客户端应用
在Auth0中创建了应用程序而非API	必须创建API资源（应用程序 -> APIs）- 应用程序不会签发具有正确受众的访问令牌
设置了 `clientId` 并认为RS256需要它	对于RS256， `clientId` 是可选的 - SDK通过JWKS端点验证
使用 `clientSecret` 进行RS256验证	`clientSecret` 仅用于HS256 - RS256使用JWKS中的公钥
将 `$_SERVER` 直接传递给 `getBearerToken()`	`server` 参数接受要查找的键名数组，例如 `['HTTP_AUTHORIZATION']` - 不是 `$_SERVER` 本身

Key SDK Methods

关键SDK方法

Method	Returns	Purpose
`getBearerToken`	`?TokenInterface`	Searches specified `$_SERVER` keys for a Bearer token, verifies signature, validates claims. Returns `null` if no token found or validation fails (does not throw).
`decode`	`TokenInterface`	Manually decodes and validates a JWT string
`configuration`	`SdkConfiguration`	Access the SDK configuration instance
`Token::toArray`	`array`	Returns all token claims as an associative array
`Token::getSubject`	`?string`	Returns the `sub` claim (user/client ID)
`Token::getIssuer`	`?string`	Returns the `iss` claim
`Token::getAudience`	`?array`	Returns the `aud` claim
`Token::getExpiration`	`?int`	Returns the `exp` claim (Unix timestamp)

方法	返回值	用途
`getBearerToken`	`?TokenInterface`	在指定的 `$_SERVER` 键中搜索Bearer令牌，验证签名，验证声明。未找到令牌或验证失败时返回 `null` （不会抛出异常）。
`decode`	`TokenInterface`	手动解码并验证JWT字符串
`configuration`	`SdkConfiguration`	访问SDK配置实例
`Token::toArray`	`array`	返回所有令牌声明的关联数组
`Token::getSubject`	`?string`	返回 `sub` 声明（用户/客户端ID）
`Token::getIssuer`	`?string`	返回 `iss` 声明
`Token::getAudience`	`?array`	返回 `aud` 声明
`Token::getExpiration`	`?int`	返回 `exp` 声明（Unix时间戳）

Related Skills

Quick Reference

快速参考

SdkConfiguration for APIs:

php

$configuration = new SdkConfiguration(
    strategy: SdkConfiguration::STRATEGY_API,       // required - stateless mode
    domain: $_ENV['AUTH0_DOMAIN'],                   // required
    audience: [$_ENV['AUTH0_AUDIENCE']],             // required - array of identifiers
    tokenAlgorithm: 'RS256',                        // default
    tokenCache: $psrCacheAdapter,                    // recommended for production
    tokenCacheTtl: 600,                             // JWKS cache TTL in seconds
);

Token validation:

php

$token = $auth0->getBearerToken(server: ['HTTP_AUTHORIZATION']);  // returns ?TokenInterface
$claims = $token->toArray();                         // all claims as array
$userId = $token->getSubject();                      // sub claim

Manual decode:

php

use Auth0\SDK\Token;

$token = $auth0->decode(
    $jwtString,
    tokenType: Token::TYPE_ACCESS_TOKEN,
);

Environment variables:

```
AUTH0_DOMAIN
```
- your Auth0 tenant domain (e.g.
```
tenant.us.auth0.com
```
)
```
AUTH0_AUDIENCE
```
- your API identifier (e.g.
```
https://api.example.com
```
)

Common Use Cases:

Protect routes ->
```
requireAuth($auth0)
```
(see Step 5)
Scope enforcement ->
```
requireAuth($auth0, ['read:messages'])
```
(see Step 5)
CORS setup -> Integration Guide
Multi-audience validation -> Integration Guide
Advanced configuration -> API Reference

API模式的SdkConfiguration：

php

$configuration = new SdkConfiguration(
    strategy: SdkConfiguration::STRATEGY_API,       // 必填 - 无状态模式
    domain: $_ENV['AUTH0_DOMAIN'],                   // 必填
    audience: [$_ENV['AUTH0_AUDIENCE']],             // 必填 - 标识符数组
    tokenAlgorithm: 'RS256',                        // 默认值
    tokenCache: $psrCacheAdapter,                    // 生产环境推荐
    tokenCacheTtl: 600,                             // JWKS缓存TTL（秒）
);

令牌验证：

php

$token = $auth0->getBearerToken(server: ['HTTP_AUTHORIZATION']);  // 返回 ?TokenInterface
$claims = $token->toArray();                         // 所有声明的数组形式
$userId = $token->getSubject();                      // sub声明

手动解码：

php

use Auth0\SDK\Token;

$token = $auth0->decode(
    $jwtString,
    tokenType: Token::TYPE_ACCESS_TOKEN,
);

环境变量：

```
AUTH0_DOMAIN
```
- 你的Auth0租户域名（例如
```
tenant.us.auth0.com
```
）
```
AUTH0_AUDIENCE
```
- 你的API标识符（例如
```
https://api.example.com
```
）

常见用例：

保护路由 ->
```
requireAuth($auth0)
```
（见步骤5）
权限范围强制 ->
```
requireAuth($auth0, ['read:messages'])
```
（见步骤5）
CORS设置 -> 集成指南
多受众验证 -> 集成指南
高级配置 -> API参考

Detailed Documentation

详细文档

Setup Guide - Auth0 CLI setup, environment configuration, getting test tokens
Integration Guide - Scopes, permissions, middleware, multi-audience, CORS, error handling
API Reference - Complete SDK API for API mode, configuration options, token methods

设置指南 - Auth0 CLI设置、环境配置、获取测试令牌
集成指南 - 权限范围、权限、中间件、多受众、CORS、错误处理
API参考 - API模式的完整SDK API、配置选项、令牌方法

auth0-php-api

Original

Translation

Auth0 PHP API Integration

Auth0 PHP API 集成

Prerequisites

前置条件

When NOT to Use

不适用于以下场景

Quick Start Workflow

快速开始流程

1. Install SDK

1. 安装SDK

2. Create Auth0 API

2. 创建Auth0 API

Using Auth0 CLI

使用Auth0 CLI

3. Configure Environment

3. 配置环境变量

4. Initialize Auth0 in API Mode

4. 以API模式初始化Auth0

5. Create Middleware Function

5. 创建中间件函数

6. Create API Routes

6. 创建API路由

7. Access Token Claims

7. 访问令牌声明

8. Add CORS Headers

8. 添加CORS头

9. Test the API

9. 测试API

Common Mistakes

常见错误

Key SDK Methods

关键SDK方法

Related Skills

相关技能

Quick Reference

快速参考

Detailed Documentation

详细文档

References

参考链接