README

OAuth 1 客户端是一个符合 OAuth RFC 5849 标准 的库，用于对 OAuth 1 服务器进行身份验证。

它内置了对以下服务的支持

• Bitbucket
• Magento
• Trello
• Tumblr
• Twitter
• Uservoice
• Xing

添加其他提供者的支持非常简单。该库需要 PHP 7.1+，并且与 PSR-2 兼容。

第三方提供者

如果您想支持其他提供者，请将它们作为 Composer 包提供，然后在下文中链接到它们。

这些提供者允许与其他不被 oauth1-client 支持的提供者集成。它们可能需要较旧版本，如果您注意到这一点，请通过拉取请求帮助他们。

• Intuit
• 500px
• Etsy
• Xero
• Garmin
• Goodreads

术语（根据 RFC 5849 规范）

client
    An HTTP client (per [RFC2616]) capable of making OAuth-
    authenticated requests (Section 3).

server
    An HTTP server (per [RFC2616]) capable of accepting OAuth-
    authenticated requests (Section 3).

protected resource
    An access-restricted resource that can be obtained from the
    server using an OAuth-authenticated request (Section 3).

resource owner
    An entity capable of accessing and controlling protected
    resources by using credentials to authenticate with the server.

credentials
    Credentials are a pair of a unique identifier and a matching
    shared secret.  OAuth defines three classes of credentials:
    client, temporary, and token, used to identify and authenticate
    the client making the request, the authorization request, and
    the access grant, respectively.

token
    A unique identifier issued by the server and used by the client
    to associate authenticated requests with the resource owner
    whose authorization is requested or has been obtained by the
    client.  Tokens have a matching shared-secret that is used by
    the client to establish its ownership of the token, and its
    authority to represent the resource owner.

The original community specification used a somewhat different
terminology that maps to this specifications as follows (original
community terms provided on left):

Consumer:  client

Service Provider:  server

User:  resource owner

Consumer Key and Secret:  client credentials

Request Token and Secret:  temporary credentials

Access Token and Secret:  token credentials

安装

通过 Composer

$ composer require league/oauth1-client

用法

Bitbucket

$server = new League\OAuth1\Client\Server\Bitbucket([
    'identifier' => 'your-identifier',
    'secret' => 'your-secret',
    'callback_uri' => "http://your-callback-uri/",
]);

Trello

$server =  new League\OAuth1\Client\Server\Trello([
    'identifier' => 'your-identifier',
    'secret' => 'your-secret',
    'callback_uri' => 'http://your-callback-uri/',
    'name' => 'your-application-name', // optional, defaults to null
    'expiration' => 'your-application-expiration', // optional ('never', '1day', '2days'), defaults to '1day'
    'scope' => 'your-application-scope' // optional ('read', 'read,write'), defaults to 'read'
]);

Tumblr

$server = new League\OAuth1\Client\Server\Tumblr([
    'identifier' => 'your-identifier',
    'secret' => 'your-secret',
    'callback_uri' => "http://your-callback-uri/",
]);

Twitter

$server = new League\OAuth1\Client\Server\Twitter([
    'identifier' => 'your-identifier',
    'secret' => 'your-secret',
    'callback_uri' => "http://your-callback-uri/",
    'scope' => 'your-application-scope' // optional ('read', 'write'), empty by default
]);

Xing

$server = new League\OAuth1\Client\Server\Xing([
    'identifier' => 'your-consumer-key',
    'secret' => 'your-consumer-secret',
    'callback_uri' => "http://your-callback-uri/",
]);

显示登录按钮

首先，建议您在网站上包含一个登录按钮。大多数服务器（如 Twitter、Tumblr 等）都提供可供用户熟悉的使用按钮的资源。有些服务器实际上要求您使用它们的按钮作为其条款的一部分。

<a href="authenticate.php">Login With Twitter</a>

检索临时凭证

使用 OAuth 1 进行身份验证的第一步是检索临时凭证。在 OAuth 1 的早期版本中，这些被称作 请求令牌。

为此，我们将检索并存储临时凭证到会话中，然后将用户重定向到服务器

// Retrieve temporary credentials
$temporaryCredentials = $server->getTemporaryCredentials();

// Store credentials in the session, we'll need them later
$_SESSION['temporary_credentials'] = serialize($temporaryCredentials);
session_write_close();

// Second part of OAuth 1.0 authentication is to redirect the
// resource owner to the login screen on the server.
$server->authorize($temporaryCredentials);

用户将被重定向到服务器上熟悉的登录界面，在那里他们将登录到他们的账户并授权您的应用程序访问他们的数据。

检索令牌凭证

一旦用户已验证（或拒绝）您的应用程序，他们将被重定向到您在创建服务器时指定的 callback_uri。

注意，一些服务器（如 Twitter）要求您在验证时指定的回调 URI 与您向其应用程序注册的 URI 相匹配。这是为了阻止潜在的第三方冒充您。这实际上是协议的一部分，但一些服务器选择忽略这一点。

因此，我们实际上要求您为所有服务器指定一个回调 URI，无论服务器是否要求它。这是一种好习惯。

您需要处理用户被重定向回的情况。这将涉及检索令牌凭证，您可以使用这些凭证代表用户向服务器发起调用。在 OAuth 1 的早期版本中，这些被称作 访问令牌。

if (isset($_GET['oauth_token']) && isset($_GET['oauth_verifier'])) {
    // Retrieve the temporary credentials we saved before
    $temporaryCredentials = unserialize($_SESSION['temporary_credentials']);

    // We will now retrieve token credentials from the server
    $tokenCredentials = $server->getTokenCredentials($temporaryCredentials, $_GET['oauth_token'], $_GET['oauth_verifier']);
}

现在，您可以选择使用令牌凭证进行您需要的工作。您可以将它们存储在数据库中、会话中，或者一次性使用后忘记它们。

所有凭证（客户端凭证、临时凭证和令牌凭证）都实现了 League\OAuth1\Client\Credentials\CredentialsInterface，并公开了两套设置器和获取器。

var_dump($tokenCredentials->getIdentifier());
var_dump($tokenCredentials->getSecret());

在OAuth 1.0的早期版本中，令牌凭证标识符和令牌凭证密钥被称为访问令牌和访问令牌密钥。这里的新术语不要害怕——它们是相同的。本包使用RFC 5849 OAuth 1标准中的确切术语。

Twitter会通过denied查询字符串参数发送错误消息，让您提供反馈。一些服务器不会发送错误消息，而是不提供成功的oauth_token和oauth_verifier参数。

访问用户信息

现在您已经将令牌凭证存储在某处，您可以使用它们作为已认证用户对服务器进行调用。

虽然此包不是为每个服务器的API提供包装，但它确实包含了一些基本方法，您可以使用这些方法检索有限的信息。这可能有用的情况之一是，如果您使用社交登录，您只需要有限的信息来确认用户身份。

公开的四个方法是

// User is an instance of League\OAuth1\Client\Server\User
$user = $server->getUserDetails($tokenCredentials);

// UID is a string / integer unique representation of the user
$uid = $server->getUserUid($tokenCredentials);

// Email is either a string or null (as some providers do not supply this data)
$email = $server->getUserEmail($tokenCredentials);

// Screen name is also known as a username (Twitter handle etc)
$screenName = $server->getUserScreenName($tokenCredentials);

League\OAuth1\Client\Server\User公开了一些默认的公共属性，并在额外的数组$user->extra中存储任何其他数据。您还可以像数组一样遍历用户的属性，foreach ($user as $key => $value)。

示例

示例可以在resources/examples目录下找到，这些示例遵循此处所述的使用说明，并进行了更深入的介绍。它们是可工作的示例，您只需替换您的客户端凭证即可使用。

测试

$ phpunit

贡献

有关详细信息，请参阅CONTRIBUTING。

致谢

• Ben Corlett
• Steven Maguire
• 所有贡献者

许可

MIT许可（MIT）。有关更多信息，请参阅许可文件。