README

CURRENT VERSION: v0.35

spid-php-lib

PHP包用于SPID认证。

此PHP包旨在实现SPID 服务提供商。 SPID 是意大利数字身份系统，允许公民使用一组凭证访问所有公共服务。此包通过仅公开实现SPID认证所需的子集，在Web应用程序中提供SAML协议的抽象层。

PHP的替代方案

spid-php 基于 SimpleSAMLphp
spid-php2 基于 php-saml

基于spid-php-lib的特定框架库和示例

其他语言的替代方案

使用composer安装

composer require italia/spid-php-lib
(可选) 手动为您的服务提供商（SP）生成密钥和证书文件。

示例： openssl req -x509 -nodes -sha256 -days 365 -newkey rsa:2048 -subj "/C=IT/ST=Italy/L=Milan/O=myservice/CN=localhost" -keyout sp.key -out sp.crt

此步骤可以跳过：如果声明了可选的 sp_key_cert_values 键，则库会自动处理此步骤。有关详细信息，请参阅用法部分的示例。
下载身份提供者（IdP）元数据文件，并将其放置在项目中的一个目录中，例如 idp_metadata。提供了一个方便的工具来下载生产IdP的元数据： vendor/italia/spid-php-lib/bin/download_idp_metadata.php，示例用法
```
mkdir idp_metadata
php vendor/italia/spid-php-lib/bin/download_idp_metadata.php ./idp_metadata
```
测试环境：如果您正在使用 spid-testenv2，请手动下载 IdP 元数据并将其放置在您的 idp_metadata 文件夹中
使您的服务提供者 (SP) 被身份提供者 (IdP) 所知：对于生产环境，请遵循 https://www.spid.gov.it/come-diventare-fornitore-di-servizi-pubblici-e-privati-con-spid 的指南

测试环境：只需下载您的服务提供者 (SP) 元数据并将其放置在测试环境的适当文件夹中。每次更改 SP 元数据后都必须重新启动测试环境。

用法

此包提供的所有类都位于 Italia\Spid 命名空间中。更详细的文档可在 SAMLInterface.php 文件中找到。

使用 composer 生成的自动加载器来加载它们

require_once(__DIR__ . "/vendor/autoload.php");

主类是 Italia\Spid\Sp（服务提供者）。

按照此指南生成设置数组

$settings = array(
    'sp_entityid' => SP_BASE_URL, // preferred: https protocol, no trailing slash, example: https://sp.example.com/
    'sp_key_file' => '/path/to/sp.key',
    'sp_cert_file' => '/path/to/sp.crt',
    'sp_comparison' => 'exact', // one of: "exact", "minimum", "better" or "maximum"
    'sp_assertionconsumerservice' => [
        // order is important ! the 0-base index in this array will be used as ID in the calls
        SP_BASE_URL . '/acs',
        ...
    ],
    'sp_singlelogoutservice' => [
        // order is important ! the 0-base index in this array will be used as ID in the calls
        [SP_BASE_URL . '/slo', 'POST'],
        [SP_BASE_URL . '/slo', 'REDIRECT']
        ...
    ],
    'sp_org_name' => 'your organization full name',
    'sp_org_display_name' => 'your organization display name',
    'sp_key_cert_values' => [ // Optional: remove this if you want to generate .key & .crt files manually
        'countryName' => 'Your Country',
        'stateOrProvinceName' => 'Your Province or State',
        'localityName' => 'Locality',
        'commonName' => 'Name',
        'emailAddress' => 'your@email.com',
    ]
    'idp_metadata_folder' => '/path/to/idp_metadata/',
    'sp_attributeconsumingservice' => [
        // order is important ! the 0-base index in this array will be used as ID in the calls
        ["fiscalNumber"],
        ["name", "familyName", "fiscalNumber", "email", "spidCode"],
        ...
    ],
    // Time in seconds of skew that is acceptable between client and server when checking OnBefore and NotOnOrAfter
    // assertion condition validity timestamps, and IssueInstant response / assertion timestamps. Optional.
    // Default is 0. Acceptable range: 0-300 (inclusive)
    'accepted_clock_skew_seconds' => 100
);

然后初始化主 Sp 类

$sp = new Italia\Spid\Sp($settings);

不希望库为您生成 .key 和 .crt 文件？那么从 settings 数组中删除 sp_key_cert_values 键，或者声明

// $autoconfiguration skips .key/.crt generation if set to false
$sp = new Italia\Spid\Sp($settings, null, $autoconfiguration = false);

执行登录

// shortname of IdP, same as the name of corresponding IdP metadata file, without .xml
$idpName = 'testenv';
// index of assertion consumer service as per the SP metadata (sp_assertionconsumerservice in settings array)
$assertId = 0;
// index of attribute consuming service as per the SP metadata (sp_attributeconsumingservice in settings array)
$attrId = 1;

// Generate the login URL and redirect to the IdP login page
$sp->login($idpName, $assertId, $attrId);

通过调用以下操作完成登录操作

$sp->isAuthenticated();

在断言消费者服务 URL。

然后调用

$userAttributes = $sp->getAttributes();

以接收请求的用户属性数组。

执行注销

调用

// index of single logout service as per the SP metadata (sp_singlelogoutservice in settings array)
$sloId = 0;

$sp->logout($sloId);

此方法将重定向到 IdP 单点退出页面，或者如果您未登录则返回 false。

完整API

示例

该存储库的 example/ 目录中提供了一个基本演示应用程序。

/example 和 /tests 文件夹不包括在从 packagist 提供的生产版本中，请记住要求 dev-develop 版本或直接克隆此存储库（建议）

要尝试它

使用以下命令生成测试证书和密钥对

openssl req -x509 -nodes -sha256 -days 365 -newkey rsa:2048 -subj "/C=IT/ST=Italy/L=Milan/O=myservice/CN=localhost" -keyout sp.key -out sp.crt

在 example/index.php 文件中更改 $base 变量的 SP 主机名；您将进行测试的浏览器必须能够解析 FQDN（默认为 https://sp.example.com）。强烈建议使用 HTTPS。
配置和安装测试 IdP spid-testenv2
从您首选的 Web 服务器提供 example 目录
访问 https://sp.example.com/metadata 获取 SP 元数据，然后将其复制到 IdP 并将 SP 注册到 IdP
访问 https://idp.example.com/metadata 获取 IdP 元数据，然后将其保存为 example/idp_metadata/testenv.xml 以将 IdP 注册到 SP
访问：https://sp.example.com 并单击 login。

演示应用程序

在 https://github.com/simevo/spid-php-lib-example 提供了一个基于 Docker 的演示应用程序。

功能

提供了一种不依赖于外部 SAML 包的 轻量级实现
无路由依赖，可以集成到任何 Web 框架/内容管理系统 (CMS)
使用会话存储身份验证结果和接收到的属性
目前不支持属性权威 (AA)

故障排除

建议安装浏览器插件以跟踪 SAML 消息

此外，您可以使用 onelogin 提供的 SAML 开发者工具来了解正在发生的事情

测试

为了测试和检查此包，您必须将其根目录设置为当前工作目录，然后按照提供的说明操作。

假设您已经使用composer遵循了安装说明，那么只需执行以下操作

cd vendor/italia/spid-php-lib

单元测试

使用composer安装先决条件，为SP生成密钥和证书，并下载所有当前生产IdP的元数据

composer install
bin/download_idp_metadata.php example/idp_metadata

然后使用PHPunit启动单元测试

./vendor/bin/phpunit --stderr --testdox tests

代码检查

本项目遵循PSR-2: 编码风格指南。

请确保您位于包目录中，然后使用以下命令检查代码

./vendor/bin/phpcs --standard=PSR2 xxx.php

贡献

对于您的贡献，请使用git-flow工作流程。

另请参阅

开发者意大利的SPID页面

作者

Lorenzo Cattaneo 和 Paolo Greppi，simevo s.r.l.

许可证

许可协议：BSD 3-Clause，详见LICENSE文件。

italia / spid-php-lib

维护者

详细信息