https://github.com/xauth-ecosystem/oauth2-xauthconnect
An OAuth 2.0 client provider for integrating with an XAuthConnect authorization server. This library is built to work with the popular league/oauth2-client package.
https://github.com/xauth-ecosystem/oauth2-xauthconnect
identity-provider league-oauth2 library oauth2-client php xauth-connect xauth-ecosystem
Last synced: 6 months ago
JSON representation
An OAuth 2.0 client provider for integrating with an XAuthConnect authorization server. This library is built to work with the popular league/oauth2-client package.
- Host: GitHub
- URL: https://github.com/xauth-ecosystem/oauth2-xauthconnect
- Owner: xauth-ecosystem
- License: other
- Created: 2025-10-14T19:05:17.000Z (9 months ago)
- Default Branch: main
- Last Pushed: 2025-12-30T06:15:21.000Z (6 months ago)
- Last Synced: 2026-01-02T16:37:28.105Z (6 months ago)
- Topics: identity-provider, league-oauth2, library, oauth2-client, php, xauth-connect, xauth-ecosystem
- Language: PHP
- Homepage: https://packagist.org/packages/xauth/oauth2-xauthconnect
- Size: 74.2 KB
- Stars: 0
- Watchers: 0
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
# XAuthConnect Provider for The PHP League OAuth 2.0 Client
[](https://packagist.org/packages/xauth/oauth2-xauthconnect)
[](https://packagist.org/packages/xauth/oauth2-xauthconnect)
[](https://packagist.org/packages/xauth/oauth2-xauthconnect)
[](https://github.com/xauth-ecosystem/oauth2-xauthconnect/actions/workflows/phpunit.yml)
[](https://app.codecov.io/gh/xauth-ecosystem/oauth2-xauthconnect)
This package provides an OAuth 2.0 client provider for integrating with an XAuthConnect authorization server. It is built to work with the popular [`league/oauth2-client`](https://github.com/thephpleague/oauth2-client) package.
This provider allows you to easily implement the "Login with XAuthConnect" functionality in any PHP application that uses `league/oauth2-client`.
## Features
- **OIDC Discovery:** Automatically configure endpoints from a single `issuer` URL.
- Implements the standard **Authorization Code Grant** flow.
- Supports **PKCE** (Proof Key for Code Exchange) for enhanced security.
- Provides helper methods for XAuthConnect-specific features:
- **Token Introspection** (`introspectToken`)
- **Token Revocation** (`revokeToken`)
- Fully compliant with the `league/oauth2-client` `AbstractProvider`.
- Exposes user data (`ID`, `Nickname`) through a `ResourceOwner` object.
## Installation
Install the package via Composer:
```bash
composer require xauth/oauth2-xauthconnect
```
This package now requires `guzzlehttp/guzzle` v7.0 or greater.
### Installing from a local path (for development)
If you're developing this library locally or need to use it as a path repository:
1. Place this library in a directory within your project (e.g., `oauth_libs/oauth2-xauthconnect`).
2. Add the following to your main `composer.json` file:
```json
{
"require": {
"xauth/oauth2-xauthconnect": "@dev"
},
"repositories": [
{
"type": "path",
"url": "./path/to/your/oauth2-xauthconnect"
}
],
"minimum-stability": "dev"
}
```
3. Run `composer update` to install the dependencies.
## Usage
Follow these steps to integrate XAuthConnect into your application.
### 1. Initialization
You can initialize the provider in two ways.
#### Method 1: OIDC Discovery (Recommended)
Provide the `issuer` URL of your XAuthConnect server. The provider will automatically discover all the required endpoint URLs.
> [!IMPORTANT]
> The `issuer` URL must be publicly accessible and resolvable from the environment where your application is running for OIDC discovery to succeed. If the issuer is not accessible, you must use Method 2 for manual configuration.
```php
require_once 'vendor/autoload.php';
$provider = new ChernegaSergiy\XAuthConnect\OAuth2\Client\Provider\XAuthConnect([
'clientId' => 'your-client-id',
'clientSecret' => 'your-client-secret',
'redirectUri' => 'https://your-redirect-uri.com',
'issuer' => 'https://xauth-server.com' // Base URL of your XAuthConnect server
]);
```
#### Method 2: Manual Configuration
If your OIDC `issuer` is not publicly accessible, or if you need to specify or override specific endpoint URLs manually, you can do so by providing them in the constructor options. This method is also useful for overriding a specific endpoint URL discovered via the `issuer`.
The following options are available for manual configuration:
- `baseAuthorizationUrl`
- `baseAccessTokenUrl`
- `resourceOwnerDetailsUrl`
- `introspectUrl`
- `revokeUrl`
For example, if the discovery document provides a wrong `token_endpoint`, you can override it:
```php
$provider = new ChernegaSergiy\XAuthConnect\OAuth2\Client\Provider\XAuthConnect([
'clientId' => 'your-client-id',
'clientSecret' => 'your-client-secret',
'redirectUri' => 'https://your-redirect-uri.com',
'issuer' => 'https://xauth-server.com', // Still recommended
// Manually override the token endpoint
'baseAccessTokenUrl' => 'httpa://new-token-url.com/token',
]);
```
### 2. Authorization
Redirect the user to the XAuthConnect server to authorize your application.
```php
// 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 URL and generates and stores the state value in the session.
$authorizationUrl = $provider->getAuthorizationUrl();
$_SESSION['oauth2state'] = $provider->getState();
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');
}
```
### 3. Getting an Access Token
After the user authorizes, they will be redirected back to your `redirectUri` with a `code`. Use this code to get an access token.
```php
try {
// Try to get an access token using the authorization code grant.
$accessToken = $provider->getAccessToken('authorization_code', [
'code' => $_GET['code']
]);
// We have an access token, let's use it!
echo 'Access Token: ' . $accessToken->getToken() . "
";
echo 'Refresh Token: ' . $accessToken->getRefreshToken() . "
";
echo 'Expired in: ' . $accessToken->getExpires() . "
";
echo 'Already expired? ' . ($accessToken->hasExpired() ? 'Yes' : 'No') . "
";
} catch (\League\OAuth2\Client\Provider\Exception\IdentityProviderException $e) {
// Failed to get the access token or user details.
exit($e->getMessage());
}
```
### 4. Getting Resource Owner Details
With the access token, you can now fetch the user's profile information.
```php
try {
// Returns a XAuthConnectUser instance.
$user = $provider->getResourceOwner($accessToken);
printf('Hello, %s!', $user->getNickname());
echo 'Your UUID is: ' . $user->getId();
// Get all user data as an array.
var_dump($user->toArray());
} catch (Exception $e) {
// Failed to get user details
exit('Oh dear...');
}
```
## Extra Features
This provider includes methods for XAuthConnect-specific endpoints.
### Introspecting a Token
You can check if a token is active and view its metadata.
```php
$introspectionResult = $provider->introspectToken($accessToken->getToken());
if ($introspectionResult['active']) {
echo "Token is active.\n";
echo "Expires at: " . date('Y-m-d H:i:s', $introspectionResult['exp']);
} else {
echo "Token is not active.";
}
```
### Revoking a Token
You can invalidate an access or refresh token on the server.
```php
// Revoke the access token
$provider->revokeToken($accessToken->getToken());
// Revoke the refresh token
$provider->revokeToken($accessToken->getRefreshToken());
echo "Tokens have been revoked.";
```
## Contributing
Contributions are welcome and appreciated! Here's how you can contribute:
1. Fork the project on GitHub.
2. Create your feature branch (`git checkout -b feature/AmazingFeature`).
3. Commit your changes (`git commit -m 'Add some AmazingFeature'`).
4. Push to the branch (`git push origin feature/AmazingFeature`).
5. Open a Pull Request.
Please make sure to update tests as appropriate and adhere to the existing coding style.
## License
This library is licensed under the CSSM Unlimited License v2.0 (CSSM-ULv2). See the [LICENSE](LICENSE) file for details.