README

通过 OpenID Connect Discovery 文档（https://openid.net/specs/openid-connect-discovery-1_0.html）配置 OpenID Connect 的 Composer 包。

此库是为与 Azure AD B2C 一起使用而制作和测试的，但应可用于其他 OpenID Connect 提供商。

参考

• OpenID Connect 隐式客户端实现指南 1.0
• Azure Active Directory B2C 文档
• 在 Azure Active Directory B2C 中使用 OpenID Connect 进行 Web 登录

用法

框架

如果您想在 Symfony 或 Drupal 项目中使用此库，您应该使用以下之一

• Symfony: itk-dev/openid-connect-bundle
• Drupal: itk-dev/itkdev_openid_connect_drupal

直接安装

要直接安装此库，请运行

composer require itk-dev/openid-connect

要使用此库，您必须提供 PSR-6：缓存接口的缓存实现。请参阅 PHP Cache 的文档和实现。

直接使用

流程

当用户想要进行身份验证时，我们创建一个 OpenIdConfigurationProvider 实例，并将他们重定向到该实例提供的授权 URL。在这里，用户可以进行身份验证，如果成功，将被重定向回提供的重定向 URI。在验证授权者的响应时，我们可以从 id_token 中提取有关用户的信息，具体取决于哪些声明受到支持。

配置

要使用此包，请导入命名空间，创建并配置一个提供者

require_once __DIR__.'/vendor/autoload.php';

use ItkDev\OpenIdConnect\Security\OpenIdConfigurationProvider;

$provider = new OpenIdConfigurationProvider([
    'redirectUri' => 'https://some.url', // Absolute url to where the user is redirected after a successful login
    'openIDConnectMetadataUrl' => 'https:/.../openid-configuration', // url to OpenId Discovery document
    'cacheItemPool' => 'Psr6/CacheItemPoolInterface', // Implementation of CacheItemPoolInterface for caching above discovery document
    'clientId' => 'client_id', // Client id assigned by authorizer
    'clientSecret' => 'client_secret', // Client password assigned by authorizer
    // optional values
    'leeway' => 30, // Defaults to 10 (seconds)
    'cacheDuration' => 3600, // Defaults to 86400 (seconds)
    'allowHttp' => true, // Defaults to false. Allow OIDC urls with http scheme. Use only during development!
]);

宽容度

为了解决签名服务器和验证服务器之间的时钟偏差时间，您可以在配置提供者时设置宽容度。建议宽容度不应超过几分钟。

默认为 10 秒

有关更多信息，请参阅以下内容

• firebase/php-jwt 示例中的最后一条提到宽容度选项。

• JWT 文档

未授权请求

未授权请求应重定向到授权 URL。

要生成授权 URL，您必须提供 "state" 和 "nonce"。

State: "请求中包含的值也返回在令牌响应中。它可以是你想要的任何内容的字符串。通常使用随机生成的唯一值来防止跨站请求伪造攻击。状态还用于在身份验证请求之前编码有关用户状态的信息，例如他们在哪个页面。"

Nonce: "请求中包含的值（由应用程序生成）包含在生成的 ID 令牌中作为声明。然后应用程序可以验证此值以减轻令牌重放攻击。该值通常是用于识别请求来源的随机唯一字符串。"

参见：发送身份验证请求

您必须在本地上持久化这些值，以便在用户被重定向回您的应用程序时验证令牌。

// Get "state" and "nonce"
$state = $provider->generateState();
$nonce = $provider->generateNonce();

// Save to session
$session->set('oauth2state', $state);
$session->set('oauth2nonce', $nonce);

$authUrl = $provider->getAuthorizationUrl(['state' => $state, 'nonce' => $nonce]);

// redirect to $authUrl

请注意，默认响应类型和模式在 OpenIdConfigurationProvider.php 中设置

'response_type' => 'id_token',
'response_mode' => 'query',

验证授权请求

授权服务会将用户重定向回 redirectUri。这应该是您应用程序中一个用于验证令牌和用户的端点。

从本地存储中加载“state”和“nonce”，并与请求值进行验证

// Validate that the request state and session state match
$sessionState = $this->session->get('oauth2state');
$this->session->remove('oauth2state');
if (!$sessionState || $request->query->get('state') !== $sessionState) {
    throw new ValidationException('Invalid state');
}

// Validate the id token. This will validate the token against the keys published by the
// provider (Azure AD B2C). If the token is invalid or the nonce doesn't match an
// exception will thrown.
try {
    $claims = $provider->validateIdToken($request->query->get('id_token'), $session->get('oauth2nonce'));
    // Authentication successful
} catch (ItkOpenIdConnectException $exception) {
    // Handle failed authentication
} finally {
    $this->session->remove('oauth2nonce');
}

开发设置

本项目包含一个使用 PHP 7.4 镜像的 docker-compose.yml 文件。要安装依赖项，您可以运行

docker compose up -d
docker compose exec phpfpm composer install

单元测试

此库包含 PhpUnit/Mockery 设置。要运行单元测试

docker compose exec phpfpm composer install
docker compose exec phpfpm ./vendor/bin/phpunit

测试套件使用 Mockery 来模拟第三方库（如来自 firebase/jwt 的 JWT::decode 方法）中的公共静态方法。

Pslam 静态分析

在静态分析中使用 Psalm。要运行 Psalm，请执行

docker compose exec phpfpm composer install
docker compose exec phpfpm ./vendor/bin/psalm

检查编码标准

以下命令可让您测试代码是否遵循项目的编码标准。

• PHP 文件（PHP-CS-Fixer）

  docker compose exec phpfpm composer check-coding-standards

• Markdown 文件（markdownlint 标准规则）

  docker run -v ${PWD}:/app itkdev/yarn:latest install
  docker run -v ${PWD}:/app itkdev/yarn:latest check-coding-standards

应用编码标准

尝试自动修复编码风格

• PHP 文件（PHP-CS-Fixer）

  docker compose exec phpfpm composer apply-coding-standards

• Markdown 文件（markdownlint 标准规则）

  docker run -v ${PWD}:/app itkdev/yarn:latest install
  docker run -v ${PWD}:/app itkdev/yarn:latest check-coding-standards

CI

使用 GitHub Actions 在所有 PR 上运行测试套件和代码风格检查。

如果您希望在本地测试作业，您可以安装 act。然后执行

act -P ubuntu-latest=shivammathur/node:latest pull_request

版本控制

我们使用 SemVer 进行版本控制。有关可用版本，请参阅此存储库的 标签。

许可

本项目采用 MIT 许可证 - 有关详细信息，请参阅 LICENSE.md 文件