README

此软件包为PHP League的OAuth 2.0客户端提供Blackbaud SKY OAuth 2.0支持

有关用法示例，请参阅此处。

此软件包符合PSR-1、PSR-2、PSR-4和PSR-7标准。如果您发现不符合标准的地方，请通过pull request发送补丁。如果您有兴趣为此库做出贡献，请查看我们的贡献指南。

要求

以下版本的PHP受支持。

• PHP 5.6
• PHP 7.0
• PHP 7.1
• PHP 7.2
• PHP 7.3
• PHP 7.4
• PHP 8.0

用法

有关示例用法，请参阅此项目。

授权代码授权

以下示例使用此库提供的内置GenericProvider。如果您正在寻找特定的提供者（例如Facebook、Google、GitHub等），请参阅我们的提供者客户端库列表。提示：您可能正在寻找特定的提供者。

授权代码授权类型是在使用第三方服务对用户进行身份验证时最常用的授权类型。此授权类型利用客户端（此库）、服务器（服务提供者）和资源所有者（拥有受保护或拥有资源的凭证的用户）来请求访问用户拥有的资源。这通常被称为3方OAuth，因为涉及三个方。

以下示例使用Brent Shaffer的演示OAuth 2.0应用程序Lock'd In来说明。当运行此代码时，您将被重定向到Lock'd In，您将提示授权客户端代表您对资源进行请求。

现在，您实际上并没有在Lock'd In上拥有账户，但为了本例的目的，假设您在重定向到Lock'd In时已经登录。

$sky = new \GrotonSchool\OAuth2\Client\Provider\BlackbaudSKY([
  BlackbaudSKY::ACCESS_KEY => 'key', // A Blackbaud SKY API subscription access key
  'clientId' => 'demoapp', // The client ID assigned to your app by Blackbaud
  'clientSecret' => 'demopass', // The client password assigned to your app by Blackbaud
  'redirectUri' => 'http://example.com/your-redirect-url/',
]);

// If we don't have an authorization code then get one
if (!isset($_GET['code'])) {
  // Fetch the authorization URL from the provider; this returns the
  // urlAuthorize option and generates and applies any necessary parameters
  // (e.g. state).
  $authorizationUrl = $sky->getAuthorizationUrl();

  // Get the state generated for you and store it to the session.
  $_SESSION['oauth2state'] = $sky->getState();

  // Redirect the user to the authorization URL.
  header('Location: ' . $authorizationUrl);
  exit();

  // Check given state against previously stored one to mitigate CSRF attack
} elseif (
  empty($_GET['state']) ||
  (isset($_SESSION['oauth2state']) &&
    $_GET['state'] !== $_SESSION['oauth2state'])
) {
  if (isset($_SESSION['oauth2state'])) {
    unset($_SESSION['oauth2state']);
  }

  exit('Invalid state');
} else {
  try {
    // Try to get an access token using the authorization code grant.
    $accessToken = $sky->getAccessToken('authorization_code', [
      'code' => $_GET['code'],
    ]);

    // We have an access token, which we may use in authenticated
    // requests against the service provider's API.
    echo 'Access Token: ' . $accessToken->getToken() . '<br>';
    echo 'Refresh Token: ' . $accessToken->getRefreshToken() . '<br>';
    echo 'Expired in: ' . $accessToken->getExpires() . '<br>';
    echo 'Already expired? ' .
      ($accessToken->hasExpired() ? 'expired' : 'not expired') .
      '<br>';

    // The provider provides a way to get an authenticated API request for
    // the service, using the access token; it returns an object conforming
    // to Psr\Http\Message\RequestInterface.
    $request = $sky->getAuthenticatedRequest(
      'GET',
      'https://api.sky.blackbaud.com/school/v1/academics/departments',
      $accessToken
    );

    // For convenience, the provider also wraps endpoints with a Guzzle client
    $school = $sky->endpoint('school/v1');
    var_export($school->get('levels'));

    // ...and those endpoints can also nest further endpoints
    $academics = $school->endpoint('academics');
    var_export($academics->get('departments'));
  } catch (\League\OAuth2\Client\Provider\Exception\IdentityProviderException $e) {
    // Failed to get the access token or user details.
    exit($e->getMessage());
  }
}

刷新令牌

一旦您的应用程序获得授权，您可以使用刷新令牌而不是通过整个获取新令牌的过程来刷新过期的令牌。要这样做，只需从您的数据存储中重新使用此刷新令牌来请求刷新。

此示例使用Brent Shaffer的演示OAuth 2.0应用程序Lock'd In。有关更多详细信息，请参阅上面的授权代码示例。

$sky = new \League\OAuth2\Client\Provider\GenericProvider([
  BlackbaudSKY::ACCESS_KEY => 'key', // A Blackbaud SKY API subscription access key
  'clientId' => 'demoapp', // The client ID assigned to your app by Blackbaud
  'clientSecret' => 'demopass', // The client password assigned to your app by Blackbaud
]);

$existingAccessToken = getAccessTokenFromYourDataStore();

if ($existingAccessToken->hasExpired()) {
  $newAccessToken = $sky->getAccessToken('refresh_token', [
    'refresh_token' => $existingAccessToken->getRefreshToken(),
  ]);

  // Purge old access token and store new access token to your data store.
}

使用代理

可以使用代理来调试对提供者做出的HTTP调用。您只需在创建Provider实例时设置proxy和verify选项即可。确保您在代理中启用SSL代理。

$sky = new \League\OAuth2\Client\Provider\GenericProvider([
    BlackbaudSKY::ACCESS_KEY  => 'key',        // A Blackbaud SKY API subscription access key
    'clientId'                => 'demoapp',    // The client ID assigned to your app by Blackbaud
    'clientSecret'            => 'demopass',   // The client password assigned to your app by Blackbaud
    'redirectUri'             => 'http://example.com/your-redirect-url/'
    'proxy'                   => '192.168.0.1:8888',
    'verify'                  => false
]);

安装

通过Composer

$ composer require groton-school/oauth2-blackbaudsky

许可证

麻省理工学院许可证（MIT）。请参阅许可证文件以获取更多信息。