README

This package provides Authentik OAuth 2.0 support for the PHP League's OAuth 2.0 Client.

Installation

To install, use Composer (via Packagist [chez14/oauth2-authentik][packagist:chez14/oauth2-authentik]):

composer require chez14/oauth2-authentik

[packagist:chez14/oauth2-authentik]:

https://packagist.org/packages/chez14/oauth2-authentik

Usage

Usage is similar to the League's OAuth client, using \CHEZ14\OAuth2\Client\Provider\AuthentikProvider as the provider.

$provider = new \CHEZ14\OAuth2\Client\Provider\AuthentikProvider([
    'clientId'     => '{authentik-client-id}',
    'clientSecret' => '{authentik-client-secret}',
    'redirectUri'  => 'https://example.com/callback-url',
    'authentikUri' => 'https://authentik.example.com',  // Your Authentik instance URL
    'pkce'         => true,  // Optional: Enable PKCE (recommended for security)
]);

if (!isset($_GET['code'])) {
    // If we don't have an authorization code then get one
    $authUrl = $provider->getAuthorizationUrl();
    $_SESSION['oauth2state'] = $provider->getState();
    header('Location: ' . $authUrl);
    exit;

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

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

    // Optional: Now you have a token you can look up a user's profile data
    try {
        // We got an access token, let's now get the user's details
        $user = $provider->getResourceOwner($token);

        // The $user object is an instance of \CHEZ14\OAuth2\Client\Provider\AuthentikUser
        // You can access user data using the getter methods:
        echo 'Hello ' . $user->getName() . "!\n"; // "Hello Yuuma Kuga!"
        echo 'Your user ID is ' . $user->getId() . ".\n"; // "Your user ID is 12345."
        echo 'Your email is ' . $user->getEmail() . ".\n"; // "Your email is yuuma.kuga@example.com."

        // Use this to interact with an API on the users behalf
        echo $token->getToken();

    } catch (\Exception $e) {
        // Failed to get user details
        exit('Something went wrong: ' . $e->getMessage());
    }
}

Working with User Data

Once you have an access token, you can retrieve the user's profile data. The getResourceOwner() method returns an \CHEZ14\OAuth2\Client\Provider\AuthentikUser object, which provides convenient methods for accessing the user's claims.

// Assuming you have a $provider and $token from the previous example
$user = $provider->getResourceOwner($token);

// Access standard claims
echo 'User ID: ' . $user->getId() . "\n"; // "12345"
echo 'Name: ' . $user->getName() . "\n"; // "Yuuma Kuga"
echo 'Email: ' . $user->getEmail() . "\n"; // "yuuma.kuga@example.com"
echo 'Username: ' . $user->getUsername() . "\n"; // "kuga"
echo 'Groups: ' . implode(', ', $user->getGroups()) . "\n"; // "border-agents, tamakoma-2"
echo 'Email Verified: ' . ($user->isEmailVerified() ? 'Yes' : 'No') . "\n"; // "Yes"

// Access custom claims using the get() method
$customClaim = $user->get('custom_claim'); // "custom_value"

// You can also access nested claims using dot notation
$nestedValue = $user->get('nested.key'); // "value"

// Check if a claim exists
if ($user->has('nickname')) {
    echo 'Nickname: ' . $user->getNickname() . "\n"; // "Black Trigger"
}

// Get all user data as an array
$userData = $user->toArray();
var_dump($userData);
/*
array(13) {
  ["sub"]=>
  string(5) "12345"
  ["name"]=>
  string(10) "Yuuma Kuga"
  ["given_name"]=>
  string(5) "Yuuma"
  ["family_name"]=>
  string(4) "Kuga"
  ["preferred_username"]=>
  string(4) "kuga"
  ["email"]=>
  string(22) "yuuma.kuga@example.com"
  ["email_verified"]=>
  bool(true)
  ["nickname"]=>
  string(13) "Black Trigger"
  ["groups"]=>
  array(2) {
    [0]=>
    string(13) "border-agents"
    [1]=>
    string(10) "tamakoma-2"
  }
  ["iss"]=>
  string(24) "https://auth.example.com"
  ["acr"]=>
  string(36) "goauthentik.io/providers/oauth2/default"
  ["custom_claim"]=>
  string(12) "custom_value"
  ["nested"]=>
  array(1) {
    ["key"]=>
    string(5) "value"
  }
}
*/

Managing Scopes

When creating your Authentik authorization URL, you can specify the state and scopes your application may authorize.

$options = [
    'scope' => ['openid', 'email', 'profile']
];

$authorizationUrl = $provider->getAuthorizationUrl($options);

If neither are defined, the provider will utilize the defaults defined in the provider.

PKCE Support

This provider supports PKCE (Proof Key for Code Exchange) which is recommended for additional security. You can enable it by setting the pkce option to true in the provider configuration:

$provider = new \CHEZ14\OAuth2\Client\Provider\AuthentikProvider([
    // ... other options
    'pkce' => true,
]);

When PKCE is enabled, the provider uses the S256 code challenge method by default. Currently, this provider does not support changing the code challenge method.

Testing

composer test

License

The MIT License (MIT). Please see License File for more information.

chez14 / oauth2-authentik

Maintainers

Details