Use API with php

For general information about using the OpenConext API, please have a look at the OpenConext API page.

Like the JAVA client, a VOOT client written in PHP can be found here: https://github.com/frkosurf/php-voot-client

Using Composer, the dependencies can be installed with the command shown below. Composer is a dependency manager that automates many of the tasks you have to deal with when installing extensions. More information can be found here: http://getcomposer.org/doc/01-basic-usage.md

$ php /path/to/composer.phar install

By modifying the configuration file below, and saving it as config.php, the VOOT client will be operational. You have to configure to following parameters:

• Log_file: path to the log file;
• Base_uri: url of the VOOT client index.php site accessible from the server;
• Scope: ‘read’, for you can only request information using the API;
• Api_uri: contains the API calls. Overview of the available API calls is given below;
• Authorize_endpoint: change the url “openconext.nl”-part so that it matches with your OpenConext instance;
• Redirect_uri: change to the location of your VOOT installation url;
• client_id: the client name / ID as configured in OpenConext;
• client_secret: client secret value as configured in OpenConext;
• token_endpoint: change url to your OpenConext installation;

<?php
$config = array(
    'log_file' => '/tmp/php-voot-client.log',
    'base_uri' => 'http://localhost/php-voot-client/index.php',
    'scope' => 'read',
    'api_uri' => 'https://api.demo.openconext.nl/v1/social/rest/groups/@me',
    'client' => array(
        'authorize_endpoint' => 'https://api.demo.openconext.nl/v1/oauth2/authorize',
        'redirect_uri' => 'http://localhost/php-voot-client/callback.php',
        'client_id' => 'MY_OPENCONEXT_CLIENT_ID',
        'client_secret' => 'MY_OPENCONEXT_CLIENT_SECRET',
        'token_endpoint' => 'https://api.demo.openconext.nl/v1/oauth2/token',
        'credentials_in_request_body' => true
    )
);

Making calls

With the script below, API calls can be made. The script can be found in index.php. The following API calls are available:

• Get personal information:
  • This call retrieves the user’s personal information:
    • /people/@me
    • or /people/{userId}
• Get a user’s group membership:
  • This call retrieves a list of groups the user is member of:
    • /groups/@me
    • or /groups/{
• Get members of a group:
  • This call retrieves a list of all members of a group:
    • /people/@me/{groupId}
    • /people/{userId}/{groupId}
• Get group information:
  • This call retrieves basic information on a group:
    • /groups/@me/{groupId}
    • /groups/{userId}/{groupId}

try {
    $client = new Client();
    $client->addSubscriber($logPlugin);
    $bearerAuth = new BearerAuth($accessToken->getAccessToken());
    $client->addSubscriber($bearerAuth);
    $response = $client->get($config['api_uri'])->send();
    header("Content-Type: application/json");
    echo $response->getBody();
} catch (BearerErrorResponseException $e) {
    if ("invalid_token" === $e->getBearerReason()) {
        // the token we used was invalid, possibly revoked, we throw it away
        $api->deleteAccessToken($context);
        $api->deleteRefreshToken($context);
        /* no valid access token available, go to authorization server */
        header("HTTP/1.1 302 Found");
        header("Location: " . $api->getAuthorizeUri($context));
        exit;
    }
    throw $e;
} catch (Exception $e) {
    die(sprintf('ERROR: %s', $e->getMessage()));
}

The JSON response includes all of the following keys for the user:

• id: The unique identifier of the user in OpenConext
• nickname: The name of the user. Equivalent to the user's common name
• emails: The email addresses of the user. Is multi-valued (but usually only contains one) and each email entry contains:
  • type: set to email
  • value: the actual email address
• name: Contains sub-elements for the user's name:
  • formatted: The user's displayname
  • familyName: User's surname
  • givenName: User's first name
• tags: Contains the status of the user, i.e. guest or member and depends on if the user auhtenticated at a guest Identity Provider or not. Is multi-valued.
• accounts: The UID of the user at the Identity Provider. Is multi-valued (but usually only contains one) and each account entry contains:
  • username: The UID
  • userId: The UID
• displayname: The user's name for display purposes
• voot_membership_role: The user's membership role in a group. Is null when you use this call.
• organizations: The user's organizations. Is multi-valued and each organization contains:
  • name: The organization's domain name
  • type: Is null
  • department: Is null
  • title: Contains the user's affiliation with the organization. See eduPersonAffiliation from the SAML attributes.
• phonenumbers: Is null
• error: Is null

The OpenConext API calls can have three optional parameters that manipulate the result:

• startIndex
• count
• sortBy

The sortBy parameter determines the key in the result that is used for sorting groups. Default sorting for groups is by id. It can be any of these keys:

• id
• title
• description