simplesamlphp / simplesamlphp-module-oidc
A SimpleSAMLphp 模块,用于添加对 OpenID Connect 协议的支持
Requires
- php: ^8.1
- ext-curl: *
- ext-json: *
- ext-openssl: *
- ext-pdo: *
- guzzlehttp/guzzle: ^7.0
- laminas/laminas-diactoros: ^2.25.2
- laminas/laminas-httphandlerrunner: ^2
- lcobucci/jwt: ^4.1
- league/oauth2-server: ^8.5.3
- nette/forms: ^3
- psr/container: ^2.0
- psr/log: ^3
- simplesamlphp/composer-module-installer: ^1.3
- spomky-labs/base64url: ^2.0
- symfony/expression-language: ^6.3
- web-token/jwt-framework: ^3
Requires (Dev)
This package is auto-updated.
Last update: 2024-09-20 14:44:24 UTC
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
运行一致性测试
还有更多问题吗?
请查看 FAQ。