README

与官方版本的主要区别

实现日志记录
使用PSR-12风格指南

spid-php-lib

SPID身份验证的PHP包。

此PHP包旨在实现SPID 服务提供商。 SPID 是意大利的数字身份系统，允许公民使用一组凭证访问所有公共服务。该包通过仅暴露实现SPID身份验证所需的SAML协议子集，为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目录提供了一个基本的演示应用程序。

从packagist的生产版本中不提供/example和/tests文件夹，请记住需要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。
访问https://idp.example.com/metadata以获取IdP元数据，然后将其保存为example/idp_metadata/testenv.xml以在SP中注册IdP。
访问：https://sp.example.com并点击login。

演示应用程序

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

特性

提供了一个不依赖外部SAML包的lean implementation。
routing-agnostic，可以集成在任何Web框架/内容管理系统（CMS）中。
使用session存储认证结果和接收到的属性。
目前不支持属性权威（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: 编码风格指南。

确保您位于包目录中，然后使用以下命令对代码进行lint检查：

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

贡献

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

另请参阅

开发者意大利的SPID页面

作者

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

许可证

许可证：BSD 3-Clause，见LICENSE文件。

intervieweb / spid-php-lib

维护者

详情