Skip to content
This repository has been archived by the owner on Dec 14, 2018. It is now read-only.

Home

Jump to bottom
ecrisostomo edited this page Oct 10, 2012 · 24 revisions

Stormpath PHP SDK

The Stormpath PHP SDK allows any PHP-based application to easily use the Stormpath cloud Identity Management service for all authentication and access control needs.

When you make SDK method calls, the calls are translated into HTTPS requests to the Stormpath REST+JSON API. The Stormpath PHP SDK therefore provides a clean object-oriented paradigm and alleviates the need to know how to make REST+JSON requests.

This SDK was implemented based on the 5.3.10 version of PHP.

Quick Start

  1. Follow the installation/configuration directions located on the README.md file.

  2. Ensure you have an API Key so your application can communicate with Stormpath.

    Because Stormpath generates an apiKey.properties file and PHP tends to work better with YAML files, you'll want to create an apiKey.yml file. Copy your existing apiKey.properties file to a new file and make sure it is readable only by you:

     > cd $HOME/.stormpath
 > cp apiKey.properties apiKey.yml
 > chmod go-rwx apiKey.yml

    Then open and edit apiKey.yml to change its contents to use a colon : delimiter for key/value pairs instead of the equals = delimiter to ensure it is YAML compliant:

     apiKey.id: 144JVZINOF5EBNCMG9EXAMPLE
 apiKey.secret: lWxOiKqKPNwJmSldbiSkEbkNjgh2uRSNAb+AEXAMPLE

    More information on different ways to configure and retrieve information from this file can be found in the Client Builder API documentation.

  3. Configure your application to create a Stormpath SDK Client instance based on your API Key. The Client instance is your starting point for all operations with the Stormpath service. For example:

     $path = '/home/myhomedir/.stormpath/apiKey.yml';
 $builder = new Services_Stormpath_Client_ClientBuilder;
 $client = $builder->setApiKeyFileLocation($path)->build();

  4. Use the Client instance to interact with your tenant data, such as Applications, Directories, and Accounts:

     $tenant = $client->getCurrentTenant();
 
 $applications = $tenant->getApplications();
 
 foreach ($applications as $application) {
    echo 'Application ' . $application->getName();
 }
 
 $directories = $tenant->getDirectories();
 
 foreach ($directories as $directory) {
     
     echo 'Directory ' . $directory->getName();

     $accounts = $directory->getAccounts();

     foreach ($accounts as $account) {
        echo 'Account ' . $account->getGivenName();
     }
 }

Client

The root entry point for SDK functionality is the Client instance. Using the Client instance, you can access all of your tenant's data, such as applications, directories, groups, accounts, etc.

Preferred Configuration

There are different ways to create a Client instance to interact with your resources. The preferred mechanism is by reading a secure apiKey.yml file as shown above in the Quick Start, sections 2 and 3, where the ClientBuilder implementation is being used:

$apiKeyFile = '/home/myhomedir/.stormpath/apiKey.yml';
$builder = new Services_Stormpath_Client_ClientBuilder;
$client = $builder->setApiKeyFileLocation($apiKeyFile)->build();

This is heavily recommended if you have access to the file system.

Single URL Configuration

The above QuickStart assumes you have easy access to an apiKey.yml file. Some applications however may not have access to the file system (such as Heroku) applications. In these cases, you can also create a Client instance using a single URL, where often the URL is available as an environment variable (e.g. $_ENV).

This technique requires embedding the API Key ID and Secret as components in a URL. This allows you to have a single URL that contains all necessary information required to construct a Client.

WARNING: Do not use this technique if you have access to a file system. Depending on the environment, environment variables are less secure than reading a permission-restricted file like apiKey.yml.

If you do not have access to the file system to read an apiKey.yml file, then this technique might be useful to you:

You can use the Services_Stormpath_Client_ClientApplicationBuilder instead of the Services_Stormpath_Client_ClientBuilder. The Services_Stormpath_Client_ClientApplicationBuilder accepts a single URL of your Application's Stormpath HREF with the API Key information embedded in the URL. For example:

$appHref = "https://apiKeyId:[email protected]/v1/applications/YOUR_APP_UID_HERE"

Ensure that the apiKeyId and apiKeySecret components are URL-encoded.

Then you can acquire the Client using the ClientApplicationBuilder:

$builder = new Services_Stormpath_Client_ClientApplicationBuilder;
$client = $builder->setApplicationHref($appHre)->build();

The ClientApplicationBuilder is a powerful utility that can be used in different ways, including all of the ClientBuilder functionalities. To learn more about its usage you can read the ClientApplicationBuilder API documentation.

API Key Configuration

Another way to create a Client is by creating an ApiKey instance with the API credentials and passing this instance to create the Client instance:

$apiKey = new Services_Stormpath_Client_ApiKey('apiKeyId', 'apiKeySecret');
$client =new Services_Stormpath_Client_Client($apiKey);

Or by using the static createClient function of the Services_Stormpath class:

$client = Services_Stormpath::createClient('apiKeyId', 'apiKeyId');

WARNING: DO NOT specify your actual apiKey.id and apiKey.secret values in source code! They are secure values associated with a specific person. You should never expose these values to other people, not even other co-workers.

Only use this technique if the values are obtained at runtime via a configuration mechanism that is not hard-coded into source code or easily-visible configuration files.

Error Handling

Errors thrown from the server are translated to a Services_Stormpath_Resource_ResourceError. This applies to all the requests to the Stormpath API endpoints.

For example, when getting the current tenant from the client you can catch any error that the request might produce the following way:

try {

    $client->getCurrentTenant();

} catch (Services_Stormpath_Resource_ResourceError $re)
{
    echo 'Message: ' . $re->getMessage();
    echo 'HTTP Status: ' . strval($re->getStatus()); 
    echo 'Developer Message: ' . $re->getDeveloperMessage();
    echo 'More Information: ' . $re->getMoreInfo();
    echo 'Error Code: ' . strval($re->getErrorCode());
}

Managing Directories

Retrieving a Directory

To retrieve a specific Directory you will need its UID. After you have the Directory's UID it can be loaded as an object instance by retrieving it from the server, using the data store:

$dataStore = $client->getDataStore();
$href = 'https://api.stormpath.com/v1/directories/DIR_UID_HERE';
$directory = $dataStore->getResource($href, Services_Stormpath::DIRECTORY); //the Services_Stormpath class provides the resources' classes' names

Listing Directories

To list all directories on the current tenant, we loop the directories aggregate that we get from the current tenant:

$tenant = $client->getCurrentTenant();

$directories = $tenant->getDirectories();

foreach($directories as $dir)
{
   echo 'Directory ' . $dir->getName();
   echo 'Directory Description ' . $dir->getDescription();
   echo 'Directory Status ' . $dir->getStatus();
}

Editing Directories

To edit directories, we use the "setters" of an existing Directory's instance to set the values we want and call the save method:

$directory->setStatus(Services_Stormpath::DISABLED); //the Services_Stormpath class provides the valid status' constants
$directory->setName('New Directory Name');
$directory->setDescription('New Directory Description');

$directory->save();

Managing Applications

Creating Applications

To edit applications, we use the "setters" of a new Application's instance to set the values we want. After this, we create the application from the tenant, the following way:

$tenant = $client->getCurrentTenant();

$application = $client->getDataStore()->instantiate(Services_Stormpath::APPLICATION); //the Services_Stormpath class provides the resources' classes' names
$application->setName('Application Name');
$application->setDescription('Application Description');

$application = $tenant->createApplication($application);

Retrieving an Application

To retrieve a specific Application you will need its UID. After you have the Application's UID it can be loaded as an object instance by retrieving it from the server, using the data store:

$dataStore = $client->getDataStore();
$href = 'https://api.stormpath.com/v1/applications/APP_UID_HERE';
$application = $dataStore->getResource($href, Services_Stormpath::APPLICATION); //the Services_Stormpath class provides the resources' classes' names

Listing Applications

To list all applications on the current tenant, we loop the applications aggregate that we get from the current tenant:

$tenant = $client->getCurrentTenant();

$applications = $tenant->getApplications();

foreach($applications as $app)
{
   echo 'Application ' . $app->getName();
   echo 'Application Description ' . $app->getDescription();
   echo 'Application Status ' . $app->getStatus();
}

Editing Applications

To edit applications, we use the "setters" of an existing Application's instance to set the values we want and call the save method:

$application->setStatus(Services_Stormpath::DISABLED); //the Services_Stormpath class provides the valid status' constants
$application->setName('New Application Name');
$application->setDescription('New Application Description');

$application->save();

Managing Accounts

Creating Accounts

To create accounts, we use the "setters" of a new Account's instance to set the values we want. Then, we create the account from a Directory the following way:

$href = 'https://api.stormpath.com/v1/directories/DIR_UID_HERE';
$directory = $client->getDataStore()->getResource($href, Services_Stormpath::DIRECTORY);

$account = $client->getDataStore()->instantiate(Services_Stormpath::ACCOUNT);
$account->setEmail('Email');
$account->setGivenName('Given Name');
$account->setPassword('Password');
$account->setSurname('Surname');
$account->setUsername('Username');

$account = $directory->createAccount($account);

If you want to override the registration workflow (account verification via email link) and have the account created with ENABLED status right away, you may pass false as second argument, the following way:

$account = $directory->createAccount($account, false);

If you want to associate the newly created account to a Group (groups will be detailed later in this document), you can do it the following way:

$account->addGroup($group);

Retrieving an Account

To retrieve a specific Account you will need its UID. After you have the Account's UID it can be loaded as an object instance by retrieving it from the server, using the data store:

$dataStore = $client->getDataStore();
$href = 'https://api.stormpath.com/v1/accounts/ACCOUNT_UID_HERE';
$account = $dataStore->getResource($href, Services_Stormpath::ACCOUNT); //the Services_Stormpath class provides the resources' classes' names

Verifying Accounts

To verify an Account (e.g. set status to ENABLED via link sent to account's email), when the account verification workflow is enabled for the account's directory, the token needs to be obtained from the link that the account's holder receives in his email inbox. This is achieved by implementing the following logic:

$verificationToken = // obtain it from query parameter, according to the workflow configuration of the link

$tenant = $client->getCurrentTenant();

// when the account is correctly verified it gets activated and that account is returned in this verification
$account = $tenant->verifyAccountEmail($verificationToken);

Authenticating Accounts

To authenticate an account we need to have the Application to where the account will be authenticated against. After we have the Application, the account is authenticated by providing the username and password the following way:

$href = 'https://api.stormpath.com/v1/applications/APP_UID_HERE';
$application = $client->getDataStore()->getResource($href, Services_Stormpath::APPLICATION);

// when the account is authenticated, it produces an Services_Stormpath_Authc_AuthenticationResult instance
$authResult = $application->authenticateAccount(new Services_Stormpath_Authc_UsernamePasswordRequest('username', 'password'));

// from the Services_Stormpath_Authc_AuthenticationResult instance we obtain the Account we just authenticated
$account = $authResult->getAccount();

Listing Accounts

To list accounts you need a directory or a group.

If you need to list the accounts that belong to a specific directory, this is how you do it:

$accounts = $directory->getAccounts();
foreach($accounts as $acc)
{
   echo 'Given Name ' . $acc->getGivenName();
   echo 'Surname ' . $acc->getSurname();
   echo 'Account Status ' . $acc->getStatus();
   echo 'Username ' . $acc->getUsername();
   echo 'Email ' . $acc->getEmail();
   echo 'Middle Name ' . $acc->getMiddleName();
}

Similarly, getting the accounts from a group works the following way:

$accounts = $group->getAccounts();

Editing Accounts

To edit accounts, we use the "setters" of an existing Account's instance to set the values we want and call the save method:

$account->setStatus(Services_Stormpath::DISABLED); //the Services_Stormpath class provides the valid status' constants
$account->setEmail('New Email');
$account->setGivenName('New Given Name');
$account->setPassword('New Password');
$account->setSurname('New Surname');
$account->setUsername('New Username');

$account->save();

If you want to add a group to an account, do the following:

$account->addGroup($group);

Reseting Account's Password

To use the password reset workflow you need to create a token that will be sent via email to the account's holder, and verify the token which returns the account where the password can be updated. This is done from the Application, like the following example:

$href = 'https://api.stormpath.com/v1/applications/APP_UID_HERE';
$application = $client->getDataStore()->getResource($href, Services_Stormpath::APPLICATION);

// creating the password reset token and sending the email
$application->sendPasswordResetEmail('username or email');

After the user clicks the link, the password reset token should be obtained from the query string according to the link's configurations that you set on the password reset workflow, and the password can be changed the following way:

$href = 'https://api.stormpath.com/v1/applications/APP_UID_HERE';
$application = $client->getDataStore()->getResource($href, Services_Stormpath::APPLICATION);

// getting the Account from the token and changing the password
$account = $application->verifyPasswordResetToken('PASS_RESET_TOKEN');
$account->setPassword('New Password');
$account->save();

Managing Groups

Retrieving a Group

To retrieve a specific Group you will need its UID. After you have the Group's UID it can be loaded as an object instance by retrieving it from the server, using the data store:

$dataStore = $client->getDataStore();
$href = 'https://api.stormpath.com/v1/groups/GROUP_UID_HERE';
$group = $dataStore->getResource($href, Services_Stormpath::GROUP); //the Services_Stormpath class provides the resources' classes' names

Listing Groups

To list all groups on a directory or an account, we loop the groups aggregate that we get from a directory or from an account:

$groups = // $directory->getGroups() or $account->getGroups()

foreach($groups as $group)
{
   echo 'Group ' . $group->getName();
   echo 'Group Description ' . $group->getDescription();
   echo 'Group Status ' . $group->getStatus();
   echo 'Group Tenant ' . $group->getTenant()->getName();
   echo 'Group Directory ' . $group->getDirectory()->getName();
}

Editing Groups

To edit groups, we use the "setters" of an existing Group's instance to set the values we want and call the save method:

$group->setStatus(Services_Stormpath::DISABLED); //the Services_Stormpath class provides the valid status' constants
$group->setName('New Group Name');
$group->setDescription('New Group Description');

$group->save();

If we want to add an existing account to the group, we just do the following:

$group->addAccount($account);

Group Membership

A group membership is the relationship between an Account and a Group

Deleting a group membership

A way to delete a group membership is by searching for it by looping the group membership aggregate of an account and, after it's found, retrieve it and delete it:

$groupHref = 'https://api.stormpath.com/v1/groups/GROUP_UID_HERE';
$group = $this->client->getDataStore()->getResource($groupHref, Services_Stormpath::GROUP);

$accountHref = 'https://api.stormpath.com/v1/accounts/ACCOUNT_UID_HERE';
$account = $this->client->getDataStore()->getResource($accountHref, Services_Stormpath::ACCOUNT);

$groupMembership = false;
// looping the group membership aggregate of the account
foreach($account->getGroupMemberShips() as $tmpGroupMembership)
{
    $tmpGroup = $tmpGroupMembership->getGroup();

    if ($tmpGroup and strrpos($tmpGroup->getHref(), $groupHref))
    {
        $groupMembership = $tmpGroupMembership;
        break;
     }
}

if ($groupMembership)
{
    $groupMembership->delete();
}
Clone this wiki locally