README

SimpleSAMLphp 模块，为 OIDC OP 提供支持。

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

当前支持的流程包括

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

版本兼容性

以下 SimpleSAMLphp 的次要版本意味着在模块开发期间已测试过该版本的 SimpleSAMLphp。SimpleSAMLphp 从 2.0 版本开始遵循语义版本规范。这意味着，例如，oidc 模块的 v5.* 应该可以在 SimpleSAMLphp 的任何 v2.* 版本上运行。但是，请注意，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 Token (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',
        ],
    ],
];

Auth Proc过滤器

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

但是，有一些考虑因素。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'] - 包含相关的授权请求查询参数。

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

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

<?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 Discovery

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

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

.well-known URL

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

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 checkout 中的代码所做的任何更改都会在容器中“实时”更新，允许您测试和迭代不同的内容。

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。

rediris-es / simplesamlphp-module-oidc

维护者

详细信息