README

此软件包为 PHP League 的 OAuth 2.0 客户端 提供了 ORCID OAuth 2.0 支持。

ORCID 为研究人员提供了一个持久的数字标识符。有关将您的应用程序与 ORCID 集成的信息，请参阅 入门指南。您最终需要 注册您的应用程序 以获取用于集成的 ORCID 客户端 ID 和客户端密钥。

此软件包符合 PSR-1、PSR-4 和 PSR-12。如果您发现合规性疏忽，请通过拉取请求发送补丁。

要求

以下版本的 PHP 受支持。

• PHP 7.1 (v1.x)
• PHP 7.2 (v1.x)
• PHP 7.3 (v1.x)
• PHP 7.4 (v2.x)
• PHP 8.0 (v2.x)
• PHP 8.1 (v2.x)

安装

要安装，请使用 composer

composer require cilogon/oauth2-orcid

用法

授权码流

$provider = new CILogon\OAuth2\Client\Provider\ORCID([
    'clientId'     => '{orcid-client-id}',
    'clientSecret' => '{orcid-client-secret}',
    'redirectUri'  => 'https://example.com/callback-url',
]);

if (!empty($_GET['error'])) {

    // Got an error, probably user denied access
    exit('Got error: ' . $_GET['error'] . 
         'Description: ' . $GET['error_description']);

} elseif (empty($_GET['code'])) {

    $authUrl = $provider->getAuthorizationUrl();
    $_SESSION['oauth2state'] = $provider->getState();
    header('Location: '.$authUrl);
    exit;

} elseif (empty($_GET['state']) || ($_GET['state'] !== $_SESSION['oauth2state'])) {

    // Check given state against previously stored one to mitigate CSRF attack
    unset($_SESSION['oauth2state']);
    exit('Invalid state');

} else {

    try {
        // Try to get an access token using the authorization code grant
        $token = $provider->getAccessToken('authorization_code', [
            'code' => $_GET['code']
        ]);

        // Print out the access token, which can be used in 
        // authenticated requests against the service provider's API.
        echo '<xmp>' . "\n";
        echo 'Token                  : ' . $token->getToken() . "\n";
        $expires = $token->getExpires();
        if (!is_null($expires)) {
            echo 'Expires                : ' . $token->getExpires();
            echo ($token->hasExpired() ? ' (expired)' : ' (active)') . "\n";
        }
        echo '</xmp>' . "\n";

        // Using the access token, get the user's details
        $user = $provider->getResourceOwner($token);

        echo '<xmp>' . "\n";
        echo 'User ID                : ' . $user->getId() . "\n";
        echo 'First name             : ' . $user->getGivenName() . "\n";   // or getFirstName()
        echo 'Last name              : ' . $user->getFamilyName() . "\n";  // or getLastName()
        echo 'Published name         : ' . $user->getName() . "\n";
        echo 'Also Known As          : ' . implode(',', $user->getOtherNames()) . "\n";
        echo 'Email                  : ' . $user->getEmail() . "\n";       // 'Primary' preferred
        echo 'Primary Email          : ' . $user->getPrimaryEmail() . "\n";// 'Primary' ONLY
        echo 'All Emails             : ' . implode(',', $user->getEmails()) . "\n";
        echo 'AuthnMethodRef         : ' . $user->getAmr() . "\n";         // Only for Member API
        echo '</xmp>';

    } catch (Exception $e) {

        // Failed to get access token or user details
        exit('Something went wrong: ' . $e->getMessage());

    }
}

沙箱与生产环境

为了验证 ORCID 用户并读取相关属性，您通常会使用生产注册表。但是，对于特殊集成，您可能想注册一个 沙箱应用程序。要使用沙箱环境，请在创建提供者时将 'sandbox' 参数设置为 true。

$provider = new CILogon\OAuth2\Client\Provider\ORCID([
    'clientId'     => '{orcid-client-id}',
    'clientSecret' => '{orcid-client-secret}',
    'redirectUri'  => 'https://example.com/callback-url',
    'sandbox'      => true
]);

请注意，您可以将其与下面的成员 API 结合使用。

公共 API 与成员 API

如果您是 ORCID 成员，则可以使用成员 API 而不是公共 API。要使用成员 API，请在创建提供者时将 'member' 参数设置为 true。成员 API 提供了一个额外的 id_token 字段 'amr'（AuthnMethodRef）。值是 'mfa'，对于已在他们的 ORCID 账户上启用了双因素认证的用户，否则是 'pwd'。当使用公共 API 时，getAmr() 返回 null。

$provider = new CILogon\OAuth2\Client\Provider\ORCID([
    'clientId'     => '{orcid-client-id}',
    'clientSecret' => '{orcid-client-secret}',
    'redirectUri'  => 'https://example.com/callback-url',
    'member'       => true
]);

请注意，您可以将其与上面的沙箱环境结合使用。

刷新令牌

刷新 ORCID 令牌 需要当前的访问令牌值作为认证的 Bearer 令牌。因此，您的应用程序需要同时使用当前的访问令牌和刷新令牌来获取新的访问令牌（及其相关的刷新令牌）。

$accesstoken  = $token->getToken();
$refreshtoken = $token->getRefreshToken();
$newtoken = $provider->getAccessToken('refresh_token', [
    'refresh_token' => $refreshtoken,
], $accesstoken);

许可

伊利诺伊大学/NCSA 开源许可证 (NCSA)。有关更多信息，请参阅 许可文件。