README

一个用于支持 OpenID Connect OP 的 SimpleSAMLphp 模块。

此模块通过 SimpleSAMLphp 模块安装支持 OpenID Connect 协议中的 OpenID 提供者角色。它基于 PHP League 的 Oauth2 服务器

当前支持的流程包括

授权代码流，支持 PKCE（response_type 'code'）
隐式流（response_type 'id_token token' 或 'id_token'）
纯 OAuth2 隐式流（response_type 'token'）
刷新令牌流

版本兼容性

以下提到的 SimpleSAMLphp 的次要版本意味着该模块在模块开发过程中已经与该版本的 SimpleSAMLphp 进行了测试。SimpleSAMLphp 从版本 2.0 开始遵循语义版本控制。这意味着，例如，oidc 模块的 v5.* 应该能在任何 v2.* 的 SimpleSAMLphp 上工作。但是请注意，SimpleSAMLphp 的次要版本中 PHP 版本要求有所变化。

升级？

如果您要从旧版本升级，请查看升级指南。

安装

安装可以简单到只需执行

composer require simplesamlphp/simplesamlphp-module-oidc

配置模块

将模块配置模板文件复制到 SimpleSAMLphp 配置目录

cp modules/oidc/config-templates/module_oidc.php config/

选项是自我解释的，所以请确保查看该文件并根据需要编辑它们。

配置数据库

此模块使用 SimpleSAMLphp 的默认数据库功能来存储访问/刷新令牌、用户数据等。为了使此功能正常工作，请编辑您的 config/config.php 并检查与 'database' 相关的配置。请确保您至少设置了以下参数

'database.dsn' => 'mysql:host=server;dbname=simplesamlphp;charset=utf8',
'database.username' => 'user',
'database.password' => 'password',

创建 RSA 密钥对

在身份验证流程中，生成的 ID Token 和 Access Token 将以签名 JSON Web 令牌 (JWS) 的形式出现。由于签名部分，您需要创建一个公钥/私钥 RSA 密钥对。

要生成私钥，您可以在终端运行此命令

openssl genrsa -out cert/oidc_module.key 3072

如果您想为您的私钥提供密码，请运行此命令代替

openssl genrsa -passout pass:myPassPhrase -out cert/oidc_module.key 3072

现在您需要从私钥中提取公钥

openssl rsa -in cert/oidc_module.key -pubout -out cert/oidc_module.crt

或者使用提供的密码，如果生成了私钥

openssl rsa -in cert/oidc_module.key -passin pass:myPassPhrase -pubout -out cert/oidc_module.crt

如果您使用密码，请确保也在 module_oidc.php 配置文件中配置它。

启用模块

在此阶段，我们可以通过将 'oidc' => true 添加到主 simplesamlphp 配置文件 config/config.php 中启用的模块列表中来启用模块。

'module.enable' => [
    'exampleauth' => false,
    'core' => true,
    'admin' => true,
    'saml' => true,
    // enable oidc module
    'oidc' => true
],

这是在管理员 Web 界面的联邦选项卡上启用模块所必需的，该选项卡可以在以下两个步骤中用于完成安装。

运行数据库迁移

该模块包含一些默认的 SQL 迁移，这些迁移在配置的数据库中设置所需的表。要运行它们，从您的 SimpleSAMLphp 安装中打开联邦选项卡，并在工具部分中选择 OpenID Connect 安装 选项。一旦到达那里，您只需按安装按钮即可创建架构。

或者，在自动/脚本部署的情况下，您可以从命令行运行 'install.php' 脚本。

php modules/oidc/bin/install.php

受信任方（RP）管理

该模块允许您通过模块用户界面本身来管理（创建、读取、更新和删除）已批准的RP。

一旦创建了数据库模式，您可以从您的SimpleSAMLphp安装中打开联邦选项卡，然后在工具部分选择OpenID Connect客户端注册选项。

请注意，客户端可以被标记为机密或公开。如果客户端未标记为机密（它是公开的），并且使用授权代码流，它必须在流程中提供PKCE参数。

将生成客户端ID和密钥，并且可以在客户端创建后通过单击'显示'按钮查看。

Cron钩子

为了清除过期令牌，此模块需要启用并配置cron模块。

端点位置

一旦您部署了该模块，您将需要模块提供的精确端点URL来配置受信任方。您可以通过访问发现端点来了解这些信息

<basepath>/module.php/oidc/openid-configuration.php

此端点可用于设置.well-known URL（见下文）。

其他注意事项

私有作用域

此模块支持基本的OIDC作用域：openid、email、address、phone和profile。但是，您可以在module_oidc.php配置文件中添加自己的私有作用域，例如

<?php

$config = [
    \SimpleSAML\Module\oidc\ModuleConfig::OPTION_AUTH_CUSTOM_SCOPES => [
        'private' => [
            'description' => 'private scope',
            'claim_name_prefix' => '', // Optional prefix for claim names
            'are_multiple_claim_values_allowed' => false, // Allow or disallow multiple values for claims
            'attributes' => ['national_document_id']
        ],
    ],
];

属性翻译

默认的SAML属性到OIDC声明的翻译表基于REFEDS维基百科文章："将SAML属性映射到OIDC声明"。

您可以在module_oidc.php配置文件中更改或扩展此表，例如

<?php

$config = [
    \SimpleSAML\Module\oidc\ModuleConfig::OPTION_AUTH_SAML_TO_OIDC_TRANSLATE_TABLE => [
        // Overwrite default translation
        'sub' => [
            'uid', // added
            'eduPersonPrincipalName',
            'eduPersonTargetedID',
            'eduPersonUniqueId',
        ],
        // Remove default translation
        'family_name' => [
        ],

        // New claim created from SAML attribute
        // Used in previus private scope
        'national_document_id' => [
            'schacPersonalUniqueId',
        ],
    ],
];

认证处理过滤器

此模块不会执行在常规SAML认证期间使用的标准认证处理过滤器，原因在于并非所有预期实体都参与认证过程（最明显的是服务提供商- SP）。因此，OIDC模块提供了自己的'authproc.oidc'配置选项，可以用来指定仅在OIDC认证期间运行的特定认证处理过滤器。

然而，有一些考虑。OIDC认证状态数组将不包含SAML认证期间可用的所有键，例如服务提供商元数据。如果您正在使用现有的过滤器，请确保它不依赖于一些不存在的状态数据。目前，以下SAML认证数据将可用

['Attributes']
['Authority']
['AuthnInstant']
['Expire']

源和目标将具有与OP发行者ID和客户端ID对应的实体ID。

['Source']['entityid'] - 包含OpenId提供者发行者ID
['Destination']['entityid'] - 包含受信任方（OIDC客户端）ID

除此之外，以下与OIDC相关的数据将在状态数组中可用

['Oidc']['OpenIdProviderMetadata'] - 包含从OIDC配置URL可用的信息。
['Oidc']['RelyingPartyMetadata'] - 包含有关发起认证请求的OIDC客户端的信息。
['Oidc']['AuthorizationRequestParameters'] - 包含相关的授权请求查询参数。

注意：目前不支持在过滤器中显示用户页面，然后继续过滤。仅支持常见的过滤器用例，如属性处理、日志记录等。

您可以通过与认证处理文档中描述的相同方式，在'authproc.oidc'配置选项中添加认证处理过滤器。

<?php

$config = [
    \SimpleSAML\Module\oidc\ModuleConfig::OPTION_AUTH_PROCESSING_FILTERS => [
        50 => [
            'class' => 'core:AttributeAdd',
            'groups' => ['users', 'members'],
        ],
    ],
];

客户端注册权限

您可以为用户注册自己的客户端。这通过 module_oidc.php 中的 permissions 设置来控制。

权限允许模块向特定用户公开功能。在下面的配置中，检查用户的 eduPersonEntitlement 属性。如果用户尝试执行需要 client 权限的操作（例如注册自己的客户端），则需要 client 权限数组中的一个 eduPersonEntitlement。

可以通过注释掉权限来禁用权限。

     \SimpleSAML\Module\oidc\ModuleConfig::OPTION_ADMIN_UI_PERMISSIONS => [
        // Attribute to inspect to determine user's permissions
        'attribute' => 'eduPersonEntitlement',
        // Which entitlements allow for registering, editing, delete a client. OIDC clients are owned by the creator
        'client' => ['urn:example:oidc:manage:client'],
    ],

用户可以访问 https://example.com/simplesaml/module.php/oidc/clients/ 来创建和查看他们的客户端。

OIDC 发现

模块在以下 URL 提供了一个 OpenID Connect 发现端点：

https://yourserver/simplesaml/module.php/oidc/openid-configuration.php

.well-known URL

您可以配置您的 Web 服务器（Apache、Nginx），以 '.well-known' 形式提供所提到的自动发现 URL。以下是一些示例配置：

nginx

location = /.well-known/openid-configuration {
    rewrite ^(.*)$ /simplesaml/module.php/oidc/openid-configuration.php break;
    proxy_pass https://localhost;
}

Apache

Alias /.well-known/openid-configuration "/path/to/simplesamlphp/module.php/oidc/openid-configuration.php"

使用 Docker

使用当前 git 分支。

要使用 docker run 探索模块，请运行以下命令。这将运行一个 SSP 镜像，其中包含当前 oidc 模块以及一些配置文件。您在 git 检出中对代码的任何更改都将实时反映在容器中，允许您测试和迭代不同的事物。

docker run --name ssp-oidc-dev \
   --mount type=bind,source="$(pwd)",target=/var/simplesamlphp/staging-modules/oidc,readonly \
  -e STAGINGCOMPOSERREPOS=oidc \
  -e COMPOSER_REQUIRE="simplesamlphp/simplesamlphp-module-oidc:@dev" \
  -e SSP_ADMIN_PASSWORD=secret1 \
  --mount type=bind,source="$(pwd)/docker/ssp/module_oidc.php",target=/var/simplesamlphp/config/module_oidc.php,readonly \
  --mount type=bind,source="$(pwd)/docker/ssp/authsources.php",target=/var/simplesamlphp/config/authsources.php,readonly \
  --mount type=bind,source="$(pwd)/docker/ssp/config-override.php",target=/var/simplesamlphp/config/config-override.php,readonly \
  --mount type=bind,source="$(pwd)/docker/ssp/oidc_module.crt",target=/var/simplesamlphp/cert/oidc_module.crt,readonly \
  --mount type=bind,source="$(pwd)/docker/ssp/oidc_module.key",target=/var/simplesamlphp/cert/oidc_module.key,readonly \
  --mount type=bind,source="$(pwd)/docker/apache-override.cf",target=/etc/apache2/sites-enabled/ssp-override.cf,readonly \
   -p 443:443 cirrusid/simplesamlphp:v2.2.2

访问 https://localhost/simplesaml/ 并确认您得到了默认页面。然后导航到 OIDC 屏幕并可以添加一个客户端。

您可以在 https://localhost/.well-known/openid-configuration 查看OIDC配置端点。

构建部署用于一致性测试的镜像

构建一个包含预配置 sqlite 数据库的镜像。

GIT_BRANCH=$(git rev-parse --abbrev-ref HEAD)
# Replace invalid tag characters when doing build
IMAGE_TAG=$(tr '/' '_' <<< $GIT_BRANCH)
docker build -t "simplesamlphp/simplesamlphp-oidc:dev-$IMAGE_TAG" \
  --build-arg OIDC_VERSION=dev-${GIT_BRANCH} \
  -f docker/Dockerfile .

docker run --name ssp-oidc-dev-image \
  -e SSP_ADMIN_PASSWORD=secret1 \
  -p 443:443 simplesamlphp/simplesamlphp-oidc:dev-$IMAGE_TAG

在您能检索到的地方发布镜像。暂时，它将偶尔发布到 cirrusid Docker 命名空间中。

docker tag "simplesamlphp/simplesamlphp-oidc:dev-$IMAGE_TAG" "cirrusid/simplesamlphp-oidc:dev-$IMAGE_TAG"
docker push "cirrusid/simplesamlphp-oidc:dev-$IMAGE_TAG"

数据库目前不在共享卷上，因此如果容器重新启动，任何更改都将丢失。您可能需要备份它。要转储数据库

docker exec ssp-oidc-dev-image sqlite3  /var/simplesamlphp/data/mydb.sq3 '.dump' > docker/conformance.sql

一致性测试在本地运行更容易，请参阅 Docker compose 部分和 CONFORMANCE_TEST.md

Docker compose

Docker compose 将运行多个容器，以便更容易测试场景。它将构建一个包含 OIDC 模块的镜像。如果您想让 docker-compose 重用之前运行的容器，可以删除 --build 参数。

# Use the current branch/git checkout. Composer installs local checkout
OIDC_VERSION=@dev docker-compose -f docker/docker-compose.yml --project-directory . up --build

# Set OIDC_VERSION to a version that composer can install to use a different version of the module.
OIDC_VERSION=dev-master docker-compose -f docker/docker-compose.yml --project-directory . up --build

访问 OP 并确认已存在几个客户端。

一致性测试在本地运行更容易，请参阅 CONFORMANCE_TEST.md

运行一致性测试

请参阅 CONFORMANCE_TEST.md

还有更多问题吗？

请查看 FAQ。

simplesamlphp / simplesamlphp-module-oidc

维护者

详细信息