CILogon Provider for the OAuth 2.0 Client

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

CILogon facilitates federated authentication for CyberInfrastructure (CI). For more information, see http://www.cilogon.org/oidc . Note that CILogon is used primarily by NSF-funded projects. All client registrations are vetted and approved manually.

This package is compliant with PSR-1, PSR-2 and PSR-4. If you notice compliance oversights, please send a patch via pull request.

Requirements

The following versions of PHP are supported.

• PHP 7.1
• PHP 7.2
• PHP 7.3
• PHP 7.4
• PHP 8.0
• PHP 8.1

Installation

To install, use composer:

composer require cilogon/oauth2-cilogon

Usage

Authorization Code Flow

$provider = new League\OAuth2\Client\Provider\CILogon([
    'clientId'     => '{cilogon-client-id}',
    'clientSecret' => '{cilogon-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'])) {

    // If we don't have an authorization code then get one with all 
    // possible CILogon-specific scopes.
    $authUrl = $provider->getAuthorizationUrl([
        'scope' => ['openid','email','profile','org.cilogon.userinfo']
    ]);
    $_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 'Full name              : ' . $user->getName() . "\n";
        echo 'Email                  : ' . $user->getEmail() . "\n";
        echo 'eduPersonPrincipalName : ' . $user->getEPPN() . "\n";
        echo 'eduPersonTargetedId    : ' . $user->getEPTID() . "\n";
        echo 'IdP entityId           : ' . $user->getIdP() . "\n";
        echo 'IdP Display Name       : ' . $user->getIdPName() . "\n";
        echo 'Org Unit               : ' . $user->getOU() . "\n";
        echo 'Affiliation            : ' . $user->getAffiliation() . "\n";
        echo '</xmp>';

    } catch (Exception $e) {

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

    }
}

Managing Scopes

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

$options = [
    'state' => 'OPTIONAL_CUSTOM_CONFIGURED_STATE',
    'scope' => ['openid','email','profile','org.cilogon.userinfo']
];

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

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

At the time of authoring this documentation, the following scopes are available.

• openid - Required/Default - gives the CILogon-specific identifier of the user
• email - gives the user's email address
• profile - gives the user's name (given, family, and display, if available)
• org.cilogon.userinfo - gives Identity Provider SAML attributes, e.g., ePPN (eduPersonPrincipalName), ePTID (eduPersonTargetedID), eduPersonScopedAffiliation, ou (organizationalUnitName)

Two additional CILogon-specific options are available.

• selected_idp - the SAML entityId of the user's pre-selected Identity Provider. If given, CILogon UI will present the user with this IdP and ask for consent for release of information. See https://cilogon.org/include/idplist.xml for the list of Identity Providers supported by CILogon (those desginated as <Whitelisted>).
• skin - a pre-defined custom CILogon interface skin to change the look of the CILogon site. Contact [email protected] to reqeust a custom skin.

Example:

$options = [
    'scope' => ['openid','email','profile','org.cilogon.userinfo'],
    'selected_idp' => 'urn:mace:incommon:uiuc.edu', // UIUC
    'skin' => 'globusonline' // For globus.org
];

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

Using the "test" or "dev" Server

Typically, you would use the production server https://cilogon.org . However, you can specify a 'server' parameter when creating the provider to use the "test" server https://test.cilogon.org or "dev" server https://dev.cilogon.org .

// Use the "test" server https://test.cilogon.org

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

Refreshing a Token

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

License

The University of Illinois/NCSA Open Source License (NCSA). Please see License File for more information.